| | |

Vitest 18 🧪 Coverage — @vitest/coverage-v8 and Threshold Enforcement

⏱️ Estimated read: 8 min | |

Coverage in Vitest is a separate package and a configuration block. The package is @vitest/coverage-v8, and the configuration is test.coverage in vitest.config.ts. The provider option selects the engine, and v8 is the default: it uses the V8 inspector to collect coverage at runtime, with no pre-instrumentation step . The thresholds block is the gate: when the coverage falls below the configured minimum, Vitest fails the run, which is the mechanism that turns coverage from a report into a CI check.

This chapter covers the V8 provider, the threshold configuration that enforces the minimum, and the include/exclude patterns that determine what the report measures. The sections that follow walk through the provider choice, the threshold types, and the CI script that fails the build on a coverage regression.

Key point: @vitest/coverage-v8 is the default provider and the recommended choice for a V8 runtime; the coverage.thresholds block fails the run when the measured coverage is below the configured minimum, and perFile: true checks every file individually rather than the project aggregate.


a. The V8 provider and the package

The coverage feature is not built into vitest itself. The provider is a separate package, and the V8 variant is installed as a dev dependency .

npm install -D vitest @vitest/coverage-v8

The coverage.provider option selects the engine, and v8 is the default . The V8 provider collects coverage at runtime through node:inspector, with no pre-instrumentation, and since Vitest 3.2 the results are remapped to the source with AST analysis, which brings the accuracy to the Istanbul level while keeping the speed advantage . The recommendation in the documentation is v8 unless the runtime is not V8 (Firefox, Bun, Cloudflare Workers) or the measurement shows that loading many modules makes the V8 provider slower than Istanbul .

The coverage.enabled option turns the collection on for a run, and the --coverage CLI flag is the equivalent. The reporter array selects the output formats: text for the terminal, html for the browsable report, json for a machine-readable file, and lcov for the Codecov/Coveralls upload .

// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    coverage: {
      provider: "v8",
      reporter: ["text", "html", "lcov"],
      reportsDirectory: "./coverage",
    },
  },
});

b. The thresholds and the failure gate

The coverage.thresholds block is the enforcement. It sets the minimum for lines, functions, branches, and statements, and Vitest fails the run when the measured coverage is below any of them .

export default defineConfig({
  test: {
    coverage: {
      provider: "v8",
      thresholds: {
        lines: 80,
        functions: 80,
        branches: 70,
        statements: 80,
      },
    },
  },
});

The perFile option changes the unit of the check. With perFile: true, every file is checked against the thresholds individually, rather than the project-wide aggregate . The aggregate check can pass while a single file is completely untested, and the perFile check closes that gap.

thresholds: {
  lines: 80,
  functions: 80,
  branches: 70,
  statements: 80,
  perFile: true, // every file must meet the minimum
},

The perFile object form sets a different minimum for each file. The top-level thresholds still apply to the aggregate, and the object’s values apply to each file, which is the pattern for a project that wants a high aggregate but tolerates a lower per-file minimum .

thresholds: {
  lines: 80, // aggregate
  perFile: {
    lines: 50, // every file
    functions: 50,
  },
},

The 100: true shortcut sets all four metrics to 100, and the autoUpdate option rewrites the thresholds in the config when the coverage improves, which is the pattern for ratcheting the minimum up over time .


c. The include/exclude and the ignore hints

The coverage.include option determines which files are measured. In Vitest 4, the all and extensions options were removed, and only the files loaded during the run are reported unless include is set . The include pattern is the way to report an untested source file that the tests never import.

coverage: {
  include: ["src/**/*.{ts,tsx}"],
  exclude: [
    "**/*.d.ts",
    "**/*.test.ts",
    "**/__mocks__/**",
    "**/dist/**",
  ],
},

The exclude array is applied to the files matched by include. The type definitions, the test files, the mocks, and the build output are the standard exclusions, and the excludeAfterRemap option is the fix for a transpiled source that appears in the report despite the exclusion .

The ignore hints are the per-line exclusions. The V8 provider uses /* v8 ignore ... */ and the Istanbul provider uses /* istanbul ignore ... */, and the -- @preserve suffix is required when the source is transpiled by esbuild, which strips the comments . Without the suffix, the hint is removed before the coverage collection sees it.

/* v8 ignore next -- @preserve */
if (process.env.NODE_ENV === "production") {
  // excluded from coverage
}

The /* v8 ignore file -- @preserve */ hint excludes an entire file, and the /* v8 ignore start -- @preserve */ and /* v8 ignore stop -- @preserve */ pair excludes a block .


Complete Example Session

// ============================================
// PART 1: THE INSTALL
// ============================================
// npm install -D vitest @vitest/coverage-v8

// ============================================
// PART 2: THE CONFIG
// ============================================
// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    coverage: {
      provider: "v8",
      reporter: ["text", "html", "lcov"],
      reportsDirectory: "./coverage",
      include: ["src/**/*.{ts,tsx}"],
      exclude: ["**/*.d.ts", "**/*.test.ts", "**/dist/**"],
      thresholds: {
        lines: 80,
        functions: 80,
        branches: 70,
        statements: 80,
        perFile: true,
      },
    },
  },
});

// ============================================
// PART 3: THE SCRIPT
// ============================================
// package.json
// "scripts": {
//   "test:coverage": "vitest run --coverage"
// }

// ============================================
// PART 4: THE FAILURE
// ============================================
// A file with 60% line coverage fails the per-file check.
// The run exits with a non-zero code, and CI fails.

// ============================================
// PART 5: THE IGNORE HINT
// ============================================
// /* v8 ignore next -- @preserve */
// if (process.env.NODE_ENV === "production") { ... }

The parts covered the install, the config with the threshold block, the coverage script, the failure gate, and the ignore hint.


Quick Reference

Packages

ProviderPackageDefault
v8@vitest/coverage-v8Yes
istanbul@vitest/coverage-istanbulNo

Threshold Options

OptionEffect
lines / functions / branches / statementsAggregate minimum
perFile: trueEach file individually
perFile: { ... }Per-file minimums
100: trueAll metrics at 100
autoUpdateRatchet the thresholds up

Reporters

ReporterOutput
textTerminal summary
htmlBrowsable report
lcovCodecov/Coveralls
jsonMachine-readable

Best Practices

✅ Do This:

// Use the v8 provider
provider: "v8"                                                 // ✅

// Set the thresholds
thresholds: { lines: 80, functions: 80, branches: 70, statements: 80 } // ✅

// Check each file
perFile: true                                                  // ✅

// Use -- @preserve for the ignore hints
/* v8 ignore next -- @preserve */                              // ✅

❌ Don’t Do This:

// Use the v8 provider on Bun or Firefox
// (not a V8 runtime)                                          // ❌

// Rely on the aggregate check alone
// (a single untested file passes)                             // ❌

// Use the ignore hint without -- @preserve
/* v8 ignore next */ // stripped by esbuild                    // ❌

Common Pitfalls

PitfallWhy It HappensFix
@vitest/coverage-v8 not foundPackage not installednpm install -D @vitest/coverage-v8
Threshold not failing the runthresholds not setAdd the block
Untested file not in the reportNo includeAdd the pattern
Ignore hint has no effectNo -- @preserveAdd the suffix

Real-World Examples

1. Install

npm install -D vitest @vitest/coverage-v8

2. Basic config

coverage: { provider: "v8", reporter: ["text", "html"] }

3. Thresholds

thresholds: { lines: 80, functions: 80, branches: 70, statements: 80 }

4. Per-file

thresholds: { lines: 80, perFile: true }

5. Per-file object

perFile: { lines: 50, functions: 50 }

6. Include

include: ["src/**/*.ts"]

7. Exclude

exclude: ["**/*.test.ts", "**/*.d.ts"]

8. Ignore file

/* v8 ignore file -- @preserve */

9. Coverage script

vitest run --coverage

10. Auto-update

thresholds: { lines: 80, autoUpdate: true }

Visual

The Coverage Pipeline

┌─────────────────────────────────────────────────────────┐
│  vitest run --coverage                                  │
│         │                                               │
│         ▼                                               │
│  V8 inspector collects runtime coverage                 │
│         │                                               │
│         ▼                                               │
│  AST remapping to source                                │
│         │                                               │
│         ▼                                               │
│  Threshold check                                        │
│         │                                               │
│    ┌────┴────┐                                          │
│    ▼         ▼                                          │
│  pass      below minimum                                │
│    │         │                                          │
│    ▼         ▼                                          │
│  report    exit non-zero                                │
└─────────────────────────────────────────────────────────┘

The Threshold Gate

┌─────────────────────────────────────────────────────────┐
│  lines: 80, perFile: true                               │
│                                                         │
│  file-a.ts: 90%  ✓                                     │
│  file-b.ts: 85%  ✓                                     │
│  file-c.ts: 60%  ✗  → run fails                        │
│                                                         │
│  The aggregate may be above 80, but file-c fails.       │
└─────────────────────────────────────────────────────────┘

The Include/Exclude

┌─────────────────────────────────────────────────────────┐
│  include: ["src/**/*.ts"]                               │
│         │                                               │
│         ▼                                               │
│  exclude: ["**/*.test.ts", "**/*.d.ts"]                 │
│         │                                               │
│         ▼                                               │
│  measured files = source without tests and types        │
└─────────────────────────────────────────────────────────┘

The Ignore Hint

┌─────────────────────────────────────────────────────────┐
│  /* v8 ignore next -- @preserve */                      │
│  if (unreachable) { ... }                               │
│                                                         │
│  Without -- @preserve, esbuild strips the comment       │
│  and the line is counted.                               │
└─────────────────────────────────────────────────────────┘

Summary

ItemValue
Package@vitest/coverage-v8
Providerv8 (default)
Thresholdslines, functions, branches, statements
Per-file checkperFile: true
Includecoverage.include
Ignore hint/* v8 ignore ... -- @preserve */
Reportertext, html, lcov, json

Key takeaways:

  • The coverage provider is a separate package. @vitest/coverage-v8 is the default and the recommended choice for a V8 runtime, and the provider: "v8" option selects it .
  • The thresholds block is the gate. It sets the minimum for the four metrics, and Vitest fails the run when the measured coverage is below any of them .
  • perFile: true checks every file. The aggregate check can pass while a single file is untested, and the per-file check closes that gap .
  • include is how an untested file appears in the report. In Vitest 4, only the files loaded during the run are reported unless include is set .
  • The -- @preserve suffix is required for the ignore hints. esbuild strips the comments, and the suffix is what keeps the hint in the transpiled code .

Remember: Coverage is a report until the thresholds make it a gate. Install the V8 provider, set the four metrics, decide whether the check is per-file or aggregate, and use the include pattern so an untested file is visible rather than absent. The ignore hint needs the -- @preserve suffix, and the threshold is the line that makes the CI fail when the coverage regresses.

Was this helpful?


Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!