Vitest 18 🧪 Coverage — @vitest/coverage-v8 and Threshold Enforcement
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
| Provider | Package | Default |
|---|---|---|
| v8 | @vitest/coverage-v8 | Yes |
| istanbul | @vitest/coverage-istanbul | No |
Threshold Options
| Option | Effect |
|---|---|
lines / functions / branches / statements | Aggregate minimum |
perFile: true | Each file individually |
perFile: { ... } | Per-file minimums |
100: true | All metrics at 100 |
autoUpdate | Ratchet the thresholds up |
Reporters
| Reporter | Output |
|---|---|
text | Terminal summary |
html | Browsable report |
lcov | Codecov/Coveralls |
json | Machine-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
| Pitfall | Why It Happens | Fix |
|---|---|---|
@vitest/coverage-v8 not found | Package not installed | npm install -D @vitest/coverage-v8 |
| Threshold not failing the run | thresholds not set | Add the block |
| Untested file not in the report | No include | Add the pattern |
| Ignore hint has no effect | No -- @preserve | Add 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
| Item | Value |
|---|---|
| Package | @vitest/coverage-v8 |
| Provider | v8 (default) |
| Thresholds | lines, functions, branches, statements |
| Per-file check | perFile: true |
| Include | coverage.include |
| Ignore hint | /* v8 ignore ... -- @preserve */ |
| Reporter | text, html, lcov, json |
Key takeaways:
- The coverage provider is a separate package.
@vitest/coverage-v8is the default and the recommended choice for a V8 runtime, and theprovider: "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: truechecks every file. The aggregate check can pass while a single file is untested, and the per-file check closes that gap .includeis how an untested file appears in the report. In Vitest 4, only the files loaded during the run are reported unlessincludeis set .- The
-- @preservesuffix 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.
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!