0
# @vitest/coverage-istanbul
1

2
Istanbul coverage provider for Vitest that instruments JavaScript and TypeScript code to track code execution during tests. This package provides an alternative to Vitest's default V8 coverage provider, offering the mature Istanbul toolchain for comprehensive code coverage analysis.
3

4
## Package Information
5

6
- **Package Name**: @vitest/coverage-istanbul
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vitest/coverage-istanbul`
10

11
## Core Imports
12

13
```typescript
14
import istanbulProvider from "@vitest/coverage-istanbul";
15
// istanbulProvider is a CoverageProviderModule with takeCoverage, startCoverage, and getProvider methods
16
```
17

18
For CommonJS:
19

20
```javascript
21
const istanbulProvider = require("@vitest/coverage-istanbul");
22
```
23

24
Note: This package exports a default module implementing the `CoverageProviderModule` interface, not named exports.
25

26
## Basic Usage
27

28
```typescript
29
// vitest.config.ts
30
import { defineConfig } from 'vitest/config'
31

32
export default defineConfig({
33
  test: {
34
    coverage: {
35
      provider: 'istanbul',
36
      reporter: ['text', 'json', 'html'],
37
      reportsDirectory: './coverage'
38
    }
39
  }
40
})
41
```
42

43
## Architecture
44

45
The package implements Vitest's coverage provider interface through several key components:
46

47
- **Coverage Provider Module**: Main export implementing `CoverageProviderModule` interface
48
- **Istanbul Coverage Provider**: Core provider class that handles instrumentation and reporting
49
- **Instrumentation**: Uses Istanbul's instrumenter to add coverage tracking to source code
50
- **Coverage Collection**: Gathers coverage data during test execution via global storage
51
- **Report Generation**: Produces coverage reports in multiple formats using Istanbul reporters
52

53
## Capabilities
54

55
### Coverage Provider Module
56

57
Main export that integrates with Vitest's coverage system.
58

59
```typescript { .api }
60
interface CoverageProviderModule {
61
  takeCoverage(): CoverageMapData;
62
  startCoverage(): void;  
63
  getProvider(): Promise<IstanbulCoverageProvider>;
64
}
65

66
interface CoverageMapData {
67
  [filename: string]: FileCoverage;
68
}
69

70
interface FileCoverage {
71
  f: FunctionCoverage;
72
  s: StatementCoverage;
73
  b: BranchCoverage;
74
}
75

76
interface FunctionCoverage {
77
  [key: string]: number;
78
}
79

80
interface StatementCoverage {
81
  [key: string]: number;
82
}
83

84
interface BranchCoverage {
85
  [key: string]: number[];
86
}
87
```
88

89
The default export provides three core functions:
90

91
- `takeCoverage()` - Retrieves coverage data from the global coverage store
92
- `startCoverage()` - Resets coverage counters to prevent duplicate results between test runs
93
- `getProvider()` - Returns an instance of the Istanbul coverage provider
94

95
### Istanbul Coverage Provider
96

97
Core coverage provider implementation that handles instrumentation and reporting.
98

99
```typescript { .api }
100
class IstanbulCoverageProvider extends BaseCoverageProvider<ResolvedCoverageOptions<'istanbul'>> implements CoverageProvider {
101
  name: 'istanbul';
102
  version: string;
103
  instrumenter: Instrumenter;
104
  testExclude: InstanceType<typeof TestExclude>;
105

106
  initialize(ctx: Vitest): void;
107
  onFileTransform(sourceCode: string, id: string, pluginCtx: any): { code: string; map: any } | undefined;
108
  createCoverageMap(): CoverageMap;
109
  generateCoverage(reportContext: ReportContext): Promise<CoverageMap>;
110
  generateReports(coverageMap: CoverageMap, allTestsRun: boolean | undefined): Promise<void>;
111
  parseConfigModule(configFilePath: string): Promise<ProxifiedModule<any>>;
112
}
113

114
interface ReportContext {
115
  allTestsRun?: boolean;
116
}
117

118
interface CoverageMap {
119
  files(): string[];
120
  merge(other: CoverageMap): void;
121
  filter(fn: (filename: string) => boolean): void;
122
  addFileCoverage(coverage: FileCoverage): void;
123
}
124
```
125

126
Key methods:
127

128
- `initialize(ctx)` - Sets up the provider with Vitest context, configures instrumenter and file exclusion rules
129
- `onFileTransform(sourceCode, id, pluginCtx)` - Instruments source code during build process for coverage tracking
130
- `createCoverageMap()` - Creates a new Istanbul coverage map instance
131
- `generateCoverage(reportContext)` - Collects and processes coverage data from test execution
132
- `generateReports(coverageMap, allTestsRun)` - Generates coverage reports in configured formats
133
- `parseConfigModule(configFilePath)` - Parses configuration files using magicast for dynamic config processing
134

135

136
## Usage Examples
137

138
### Basic Configuration
139

140
```typescript
141
// vitest.config.ts
142
import { defineConfig } from 'vitest/config'
143

144
export default defineConfig({
145
  test: {
146
    coverage: {
147
      provider: 'istanbul',
148
      reporter: ['text', 'json-summary', 'html'],
149
      reportsDirectory: './coverage',
150
      exclude: [
151
        'node_modules/',
152
        'src/test-utils/',
153
        '**/*.{test,spec}.{js,ts}',
154
      ],
155
      include: ['src/**/*.{js,ts}'],
156
      all: true,
157
      skipFull: false
158
    }
159
  }
160
})
161
```
162

163
### Advanced Configuration
164

165
```typescript
166
// vitest.config.ts
167
import { defineConfig } from 'vitest/config'
168

169
export default defineConfig({
170
  test: {
171
    coverage: {
172
      provider: 'istanbul',
173
      reporter: [
174
        ['text'],
175
        ['html', { subdir: 'html' }],
176
        ['json', { file: 'coverage.json' }],
177
        ['lcov', { file: 'lcov.info' }]
178
      ],
179
      reportsDirectory: './coverage',
180
      watermarks: {
181
        statements: [80, 95],
182
        functions: [80, 95],
183
        branches: [80, 95],
184
        lines: [80, 95]
185
      },
186
      thresholds: {
187
        statements: 90,
188
        functions: 90,
189
        branches: 90,
190
        lines: 90
191
      },
192
      ignoreClassMethods: ['toString', 'toJSON'],
193
      excludeAfterRemap: true,
194
      all: true,
195
      cleanOnRerun: true
196
    }
197
  }
198
})
199
```
200

201
### Using with Custom Reporters
202

203
```typescript
204
// vitest.config.ts
205
import { defineConfig } from 'vitest/config'
206

207
export default defineConfig({
208
  test: {
209
    coverage: {
210
      provider: 'istanbul',
211
      reporter: [
212
        'text-summary',
213
        ['html', { 
214
          subdir: 'html-report',
215
          skipFull: false 
216
        }],
217
        ['cobertura', { 
218
          file: 'cobertura-coverage.xml' 
219
        }],
220
        ['teamcity', { 
221
          file: 'teamcity-coverage.txt' 
222
        }]
223
      ]
224
    }
225
  }
226
})
227
```
228

229
## Configuration Types
230

231
The Istanbul coverage provider supports specific configuration options through Vitest's coverage configuration.
232

233
```typescript { .api }
234
interface CoverageIstanbulOptions extends BaseCoverageOptions {
235
  /**
236
   * Set to array of class method names to ignore for coverage
237
   *
238
   * @default []
239
   */
240
  ignoreClassMethods?: string[];
241
}
242

243
interface BaseCoverageOptions {
244
  enabled?: boolean;
245
  include?: string[];
246
  extension?: string | string[];
247
  exclude?: string[];
248
  all?: boolean;
249
  clean?: boolean;
250
  cleanOnRerun?: boolean;
251
  reportsDirectory?: string;
252
  reporter?: CoverageReporter[];
253
  skipFull?: boolean;
254
  thresholds?: Thresholds;
255
  watermarks?: {
256
    statements?: [number, number];
257
    functions?: [number, number];
258
    branches?: [number, number];
259
    lines?: [number, number];
260
  };
261
  reportOnFailure?: boolean;
262
  allowExternal?: boolean;
263
  excludeAfterRemap?: boolean;
264
  processingConcurrency?: number;
265
}
266

267
type CoverageReporter = 'text' | 'json' | 'html' | 'lcov' | 'text-summary' | 'json-summary' | 'cobertura' | 'teamcity' | (string & {});
268

269
interface Thresholds {
270
  statements?: number;
271
  functions?: number;
272
  branches?: number;
273
  lines?: number;
274
}
275

276
type ResolvedCoverageOptions<T extends 'istanbul'> = CoverageIstanbulOptions & Required<Pick<CoverageIstanbulOptions, 'enabled' | 'clean' | 'cleanOnRerun' | 'all' | 'skipFull' | 'reportOnFailure' | 'allowExternal' | 'excludeAfterRemap'>>;
277
```
278

279
## Constants
280

281
```typescript { .api }
282
/** Key used to store coverage data in global scope */
283
const COVERAGE_STORE_KEY: string = '__VITEST_COVERAGE__';
284
```
285

286
## Core Types
287

288
```typescript { .api }
289
interface CoverageProviderModule {
290
  takeCoverage(): CoverageMapData;
291
  startCoverage(): void;
292
  getProvider(): Promise<IstanbulCoverageProvider>;
293
}
294

295
interface CoverageMapData {
296
  [filename: string]: FileCoverage;
297
}
298

299
interface FileCoverage {
300
  f: FunctionCoverage;
301
  s: StatementCoverage;
302
  b: BranchCoverage;
303
}
304

305
interface FunctionCoverage {
306
  [key: string]: number;
307
}
308

309
interface StatementCoverage {
310
  [key: string]: number;
311
}
312

313
interface BranchCoverage {
314
  [key: string]: number[];
315
}
316

317
interface CoverageMap {
318
  files(): string[];
319
  merge(other: CoverageMap): void;
320
  filter(fn: (filename: string) => boolean): void;
321
  addFileCoverage(coverage: FileCoverage): void;
322
}
323

324
interface ReportContext {
325
  allTestsRun?: boolean;
326
}
327

328
interface ProxifiedModule<T> {
329
  $ast: any;
330
  $code: string;
331
  exports: T;
332
}
333
```