1---
2name: code-coverage
3description: Code coverage with V8 or Istanbul providers
4---
5 
6# Code Coverage
7 
8## Setup
9 
10```bash
11# Run tests with coverage
12vitest run --coverage
13```
14 
15## Configuration
16 
17```ts
18// vitest.config.ts
19defineConfig({
20  test: {
21    coverage: {
22      // Provider: 'v8' (default, faster) or 'istanbul' (more compatible)
23      provider: 'v8',
24      
25      // Enable coverage
26      enabled: true,
27      
28      // Reporters
29      reporter: ['text', 'json', 'html'],
30      
31      // v4: define `include` to report uncovered files too.
32      // Without it, only files loaded during the run are reported.
33      include: ['src/**/*.{ts,tsx}'],
34      
35      // Exclusion is applied to files matched by `include`
36      exclude: [
37        '**/*.d.ts',
38        '**/*.test.ts',
39      ],
40      
41      // Thresholds
42      thresholds: {
43        lines: 80,
44        functions: 80,
45        branches: 80,
46        statements: 80,
47      },
48    },
49  },
50})
51```
52 
53## Providers
54 
55### V8 (Default)
56 
57```bash
58npm i -D @vitest/coverage-v8
59```
60 
61- Faster, no pre-instrumentation
62- Uses V8's native coverage
63- v4 uses **AST-based remapping** (as accurate as Istanbul); expect coverage numbers to shift when upgrading from v3
64- Recommended for most projects
65 
66### Istanbul
67 
68```bash
69npm i -D @vitest/coverage-istanbul
70```
71 
72- Pre-instruments code
73- Works in any JS runtime
74- More overhead but widely compatible
75 
76## Reporters
77 
78```ts
79coverage: {
80  reporter: [
81    'text',           // Terminal output
82    'text-summary',   // Summary only
83    'json',           // JSON file
84    'html',           // HTML report
85    'lcov',           // For CI tools
86    'cobertura',      // XML format
87  ],
88  reportsDirectory: './coverage',
89}
90```
91 
92## Thresholds
93 
94Fail tests if coverage is below threshold:
95 
96```ts
97coverage: {
98  thresholds: {
99    // Global thresholds
100    lines: 80,
101    functions: 75,
102    branches: 70,
103    statements: 80,
104    
105    // Per-file thresholds
106    perFile: true,
107    
108    // Auto-update thresholds (for gradual improvement)
109    autoUpdate: true,
110 
111    // v5: glob thresholds no longer inherit top-level `perFile` — set it per glob
112    'src/utils/**': { lines: 80, perFile: true },
113  },
114}
115```
116 
117## Ignoring Code
118 
119### V8
120 
121```ts
122/* v8 ignore next -- @preserve */
123function ignored() {
124  return 'not covered'
125}
126 
127/* v8 ignore start -- @preserve */
128// All code here ignored
129/* v8 ignore stop -- @preserve */
130```
131 
132### Istanbul
133 
134```ts
135/* istanbul ignore next -- @preserve */
136function ignored() {}
137 
138/* istanbul ignore if -- @preserve */
139if (condition) {
140  // ignored
141}
142```
143 
144Note: `@preserve` keeps comments through esbuild.
145 
146## Package.json Scripts
147 
148```json
149{
150  "scripts": {
151    "test": "vitest",
152    "test:coverage": "vitest run --coverage",
153    "test:coverage:watch": "vitest --coverage"
154  }
155}
156```
157 
158## Vitest UI Coverage
159 
160Enable HTML coverage in Vitest UI:
161 
162```ts
163coverage: {
164  enabled: true,
165  reporter: ['text', 'html'],
166}
167```
168 
169Run with `vitest --ui` to view coverage visually.
170 
171## CI Integration
172 
173```yaml
174# GitHub Actions
175- name: Run tests with coverage
176  run: npm run test:coverage
177 
178- name: Upload coverage to Codecov
179  uses: codecov/codecov-action@v3
180  with:
181    files: ./coverage/lcov.info
182```
183 
184## Coverage with Sharding
185 
186Merge coverage from sharded runs (blobs default to `.vitest/blob/`):
187 
188```bash
189vitest run --shard=1/3 --coverage --reporter=blob
190vitest run --shard=2/3 --coverage --reporter=blob
191vitest run --shard=3/3 --coverage --reporter=blob
192 
193vitest --merge-reports --coverage --reporter=json
194```
195 
196## v4 Changes
197 
198- **`coverage.all` and `coverage.extensions` removed** — only covered files are reported unless `coverage.include` is set.
199- **`coverage.ignoreEmptyLines` removed**; lines without runtime code are no longer counted.
200- **`coverage.experimentalAstAwareRemapping` removed** — AST remapping is the default and only mode for V8.
201- Programmatic coverage APIs moved from `vitest/coverage` to `vitest/node`.
202 
203## Key Points
204 
205- V8 is faster, Istanbul is more compatible
206- Use `--coverage` flag or `coverage.enabled: true`
207- Define `coverage.include` to report uncovered source files
208- Set thresholds to enforce minimum coverage
209- Use `@preserve` comment to keep ignore hints (e.g. `/* v8 ignore next -- @preserve */`)
210 
211<!-- 
212Source references:
213- https://vitest.dev/guide/coverage.html
214-->
215