docs/config/coverage.md
You can use v8, istanbul or a custom coverage solution for coverage collection.
You can provide coverage options to CLI with dot notation:
npx vitest --coverage.enabled --coverage.provider=istanbul
::: warning
If you are using coverage options with dot notation, don't forget to specify --coverage.enabled. Do not provide a single --coverage option in that case.
:::
'v8' | 'istanbul' | 'custom''v8'--coverage.provider=<provider>Use provider to select the tool for coverage collection.
booleanfalse'v8' | 'istanbul'--coverage.enabled, --coverage.enabled=falseEnables coverage collection. Can be overridden using --coverage CLI option.
string[]'v8' | 'istanbul'--coverage.include=<pattern>, --coverage.include=<pattern1> --coverage.include=<pattern2>List of files included in coverage as glob patterns. By default only files covered by tests are included.
It is recommended to pass file extensions in the pattern.
See Including and excluding files from coverage report for examples.
string[][]'v8' | 'istanbul'--coverage.exclude=<path>, --coverage.exclude=<path1> --coverage.exclude=<path2>List of files excluded from coverage as glob patterns.
See Including and excluding files from coverage report for examples.
booleantrue'v8' | 'istanbul'--coverage.clean, --coverage.clean=falseClean coverage results before running tests.
booleantrue'v8' | 'istanbul'--coverage.cleanOnRerun, --coverage.cleanOnRerun=falseClean coverage report on watch rerun. Set to false to preserve coverage results from previous run in watch mode.
string'./coverage''v8' | 'istanbul'--coverage.reportsDirectory=<path>::: warning
Vitest will delete this directory before running tests if coverage.clean is enabled (default value).
:::
Directory to write coverage report to.
string | string[] | [string, {}][]['text', 'html', 'clover', 'json']'v8' | 'istanbul'--coverage.reporter=<reporter>, --coverage.reporter=<reporter1> --coverage.reporter=<reporter2>Coverage reporters to use. See istanbul documentation for detailed list of all reporters. See @types/istanbul-reports for details about reporter specific options.
The reporter has three different types:
{ reporter: 'html' }{ reporter: ['html', 'json'] }{
reporter: [
['lcov', { 'projectRoot': './src' }],
['json', { 'file': 'coverage.json' }],
['text']
]
}
You can also pass custom coverage reporters. See Guide - Custom Coverage Reporter for more information.
<!-- eslint-skip --> {
reporter: [
// Specify reporter using name of the NPM package
'@vitest/custom-coverage-reporter',
['@vitest/custom-coverage-reporter', { someOption: true }],
// Specify reporter using local path
'/absolute/path/to/custom-reporter.cjs',
['/absolute/path/to/custom-reporter.cjs', { someOption: true }],
]
}
You can check your coverage report in Vitest UI: check Vitest UI Coverage for more details.
::: tip AI coding agents
When Vitest detects it is running inside an AI coding agent, it automatically adds the text-summary reporter and sets skipFull: true on the text reporter to reduce output and minimize token usage.
:::
booleanfalse'v8' | 'istanbul'--coverage.reportOnFailure, --coverage.reportOnFailure=falseGenerate coverage report even when tests fail.
booleanfalse'v8' | 'istanbul'--coverage.allowExternal, --coverage.allowExternal=falseCollect coverage of files outside the project root.
booleanfalse'v8' | 'istanbul'--coverage.excludeAfterRemap, --coverage.excludeAfterRemap=falseApply exclusions again after coverage has been remapped to original sources. This is useful when your source files are transpiled and may contain source maps of non-source files.
Use this option when you are seeing files that show up in report even if they match your coverage.exclude patterns.
booleanfalse'v8' | 'istanbul'--coverage.skipFull, --coverage.skipFull=falseDo not show files with 100% statement, branch, and function coverage.
Options for coverage thresholds.
If a threshold is set to a positive number, it will be interpreted as the minimum percentage of coverage required. For example, setting the lines threshold to 90 means that 90% of lines must be covered.
If a threshold is set to a negative number, it will be treated as the maximum number of uncovered items allowed. For example, setting the lines threshold to -10 means that no more than 10 lines may be uncovered.
{
coverage: {
thresholds: {
// Requires 90% function coverage
functions: 90,
// Require that no more than 10 lines are uncovered
lines: -10,
}
}
}
number'v8' | 'istanbul'--coverage.thresholds.lines=<number>Global threshold for lines.
number'v8' | 'istanbul'--coverage.thresholds.functions=<number>Global threshold for functions.
number'v8' | 'istanbul'--coverage.thresholds.branches=<number>Global threshold for branches.
number'v8' | 'istanbul'--coverage.thresholds.statements=<number>Global threshold for statements.
booleanfalse'v8' | 'istanbul'--coverage.thresholds.perFile, --coverage.thresholds.perFile=falseCheck thresholds per file.
boolean | functionfalse'v8' | 'istanbul'--coverage.thresholds.autoUpdate=<boolean>Update all threshold values lines, functions, branches and statements to configuration file when current coverage is better than the configured thresholds.
This option helps to maintain thresholds when coverage is improved.
You can also pass a function for formatting the updated threshold values:
<!-- eslint-skip -->{
coverage: {
thresholds: {
// Update thresholds without decimals
autoUpdate: (newThreshold) => Math.floor(newThreshold),
// 95.85 -> 95
functions: 95,
}
}
}
booleanfalse'v8' | 'istanbul'--coverage.thresholds.100, --coverage.thresholds.100=falseSets global thresholds to 100.
Shortcut for --coverage.thresholds.lines 100 --coverage.thresholds.functions 100 --coverage.thresholds.branches 100 --coverage.thresholds.statements 100.
{ statements?: number functions?: number branches?: number lines?: number }undefined'v8' | 'istanbul'Sets thresholds for files matching the glob pattern.
::: tip NOTE Vitest counts all files, including those covered by glob-patterns, into the global coverage thresholds. This is different from Jest behavior. :::
<!-- eslint-skip -->{
coverage: {
thresholds: {
// Thresholds for all files
functions: 95,
branches: 70,
// Thresholds for matching glob pattern
'src/utils/**.ts': {
statements: 95,
functions: 90,
branches: 85,
lines: 80,
},
// Files matching this pattern will only have lines thresholds set.
// Global thresholds are not inherited.
'**/math.ts': {
lines: 100,
}
}
}
}
booleanfalse'v8' | 'istanbul'Sets thresholds to 100 for files matching the glob pattern.
<!-- eslint-skip -->{
coverage: {
thresholds: {
// Thresholds for all files
functions: 95,
branches: 70,
// Thresholds for matching glob pattern
'src/utils/**.ts': { 100: true },
'**/math.ts': { 100: true }
}
}
}
string[][]'v8' | 'istanbul'--coverage.ignoreClassMethods=<method>Set to array of class method names to ignore for coverage. See istanbul documentation for more information.
{
statements?: [number, number],
functions?: [number, number],
branches?: [number, number],
lines?: [number, number]
}
{
statements: [50, 80],
functions: [50, 80],
branches: [50, 80],
lines: [50, 80]
}
'v8' | 'istanbul'--coverage.watermarks.statements=50,80, --coverage.watermarks.branches=50,80Watermarks for statements, lines, branches and functions. See istanbul documentation for more information.
booleanMath.min(20, os.availableParallelism?.() ?? os.cpus().length)'v8' | 'istanbul'--coverage.processingConcurrency=<number>Concurrency limit used when processing the coverage results.
(options: InstrumenterOptions) => CoverageInstrumenter'istanbul'Factory for a custom instrumenter to use in place of the default istanbul-lib-instrument. Vitest calls the factory once during initialization and reuses the returned instrumenter for every file. The rest of the Istanbul pipeline (collection, merging, reporting) is unchanged.
The factory receives an InstrumenterOptions object with Vitest's runtime coverage settings, and must return an object implementing the CoverageInstrumenter interface. Both types are exported from vitest/node.
interface InstrumenterOptions {
coverageVariable: string
coverageGlobalScope: string
coverageGlobalScopeFunc: boolean
ignoreClassMethods: string[]
}
interface CoverageInstrumenter {
instrumentSync: (code: string, filename: string, inputSourceMap?: any) => string
lastSourceMap: () => any
lastFileCoverage: () => any
}
import { defineConfig } from 'vitest/config'
import { createInstrumenter } from '@vitest/some-custom-instrumenter'
export default defineConfig({
test: {
coverage: {
provider: 'istanbul',
instrumenter: options => createInstrumenter(options),
}
}
})
string'custom'--coverage.customProviderModule=<path or module name>Specifies the module name or path for the custom coverage provider module. See Guide - Custom Coverage Provider for more information.
stringhtml, html-spa, or lcov coverage reporters--coverage.htmlDir=<path>Directory of HTML coverage output to be served in Vitest UI and HTML reporter.
This is automatically configured when using builtin coverage reporters that produce HTML output (html, html-spa, and lcov). Use this option to override with a custom coverage reporting location when using custom coverage reporters.
Note that setting this option does not change where coverage HTML report is generated. Configure the coverage.reporter option to change the directory instead.
boolean | stringfalse (inherits from test.changed)'v8' | 'istanbul'--coverage.changed, --coverage.changed=<commit/branch>Collect coverage only for files changed since a specified commit or branch. When set to true, it uses staged and unstaged changes.