coverage.thresholds.100 flag sets all thresholds to 100
The `--coverage.thresholds.100` CLI flag is a shortcut to set all coverage thresholds to 100. Default is `false`.
coverage & reporting
64 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
outputFile flag writes test results to file
The `--outputFile <filename/-s>` CLI flag writes test results to a file when a supported reporter is specified. Use cac's dot notation for individual outputs of multiple reporters, e.g., `--outputFile.tap=./tap.txt`.
coverage.provider flag selects coverage tool
The `--coverage.provider <name>` CLI flag selects the tool for coverage collection. Available values: "v8", "istanbul", and "custom".
coverage.enabled flag enables coverage collection
The `--coverage.enabled` CLI flag enables coverage collection. Default is `false`. Can be overridden using the `--coverage` CLI option.
coverage.include flag adds files to coverage
The `--coverage.include <pattern>` CLI flag includes files in coverage as glob patterns. Can be specified multiple times for multiple patterns. By default, only files covered by tests are included.
coverage.exclude flag excludes files from coverage
The `--coverage.exclude <pattern>` CLI flag excludes files from coverage. Can be specified multiple times for multiple extensions.
coverage.clean flag clears coverage before tests
The `--coverage.clean` CLI flag cleans coverage results before running tests. Default is `true`.
coverage.cleanOnRerun flag clears on watch reruns
The `--coverage.cleanOnRerun` CLI flag cleans the coverage report on watch mode reruns. Default is `true`.
coverage.reportsDirectory flag sets output directory
The `--coverage.reportsDirectory <path>` CLI flag specifies the directory to write coverage reports to. Default is `./coverage`.
coverage.reporter flag selects reporters
The `--coverage.reporter <name>` CLI flag specifies coverage reporters to use. Default is `["text", "html", "clover", "json"]`.
coverage.reportOnFailure flag generates report on failure
The `--coverage.reportOnFailure` CLI flag generates a coverage report even when tests fail. Default is `false`.
coverage.thresholds.perFile flag enables per-file checking
The `--coverage.thresholds.perFile <boolean>` CLI flag checks coverage thresholds per file. Default is `false`. Object form is available in config files only. Use with `--coverage.thresholds.lines`, `--coverage.thresholds.functions`, `--coverage.thresholds.branches`, and `--coverage.thresholds.statements`.
coverage.thresholds.autoUpdate flag updates thresholds
The `--coverage.thresholds.autoUpdate <boolean|function>` CLI flag updates threshold values for "lines", "functions", "branches", and "statements" in the configuration file when current coverage exceeds configured thresholds. Default is `false`.
coverage.thresholds.lines flag sets line threshold
The `--coverage.thresholds.lines <number>` CLI flag sets the threshold for lines coverage. This option is not available for custom providers.
coverage.thresholds.functions flag sets function threshold
The `--coverage.thresholds.functions <number>` CLI flag sets the threshold for functions coverage. This option is not available for custom providers.
coverage.thresholds.branches flag sets branch threshold
The `--coverage.thresholds.branches <number>` CLI flag sets the threshold for branches coverage. This option is not available for custom providers.
coverage.thresholds.statements flag sets statement threshold
The `--coverage.thresholds.statements <number>` CLI flag sets the threshold for statements coverage. This option is not available for custom providers.
coverage.ignoreClassMethods flag ignores methods
The `--coverage.ignoreClassMethods <name>` CLI flag specifies an array of class method names to ignore for coverage. This option is only available for istanbul providers. Default is `[]`.
coverage.processingConcurrency flag limits processing
The `--coverage.processingConcurrency <number>` CLI flag sets the concurrency limit when processing coverage results. Default is the minimum between 20 and the number of CPUs.
coverage.customProviderModule flag specifies provider
The `--coverage.customProviderModule <path>` CLI flag specifies the module name or path for a custom coverage provider module. This option is only available for custom providers.
coverage.watermarks flags set coverage watermarks
Coverage watermarks flags: `--coverage.watermarks.statements <watermarks>`, `--coverage.watermarks.lines <watermarks>`, `--coverage.watermarks.branches <watermarks>`, `--coverage.watermarks.functions <watermarks>`. Each takes high and low values in format `<high>,<low>`.
coverage.changed flag filters changed files
The `--coverage.changed <commit/branch>` CLI flag collects coverage only for files changed since a specified commit or branch, e.g., `origin/main` or `HEAD~1`. Inherits value from `--changed` by default.
coverage.excludeAfterRemap flag re-applies exclusions
The `--coverage.excludeAfterRemap` CLI flag applies coverage exclusions again after coverage has been remapped to original sources. Default is `false`.
coverage.htmlDir flag sets HTML output directory
The `--coverage.htmlDir <path>` CLI flag specifies the directory for HTML coverage output to be served in UI mode and HTML reporter.
coverage.autoAttachSubprocess flag tracks subprocess coverage
The `--coverage.autoAttachSubprocess` CLI flag enables tracking coverage of `node:child_process` and `node:worker_threads` spawned during test run. Supported only by `v8` provider. Default is `false`.
coverage.allowExternal flag includes external files
The `--coverage.allowExternal` CLI flag enables coverage collection for files outside the project root. Default is `false`.
coverage.skipFull flag hides 100% coverage files
The `--coverage.skipFull` CLI flag prevents showing files with 100% statement, branch, and function coverage. Default is `false`.
reporter flag specifies output reporters
The `--reporter <name>` CLI flag specifies which reporters to use. Available reporters: default, agent, minimal, blob, verbose, dot, json, tap, tap-flat, junit, tree, hanging-process, github-actions.
Generated reports use .vitest directory
In Vitest 5.0, all generated reports and artifacts use a single .vitest directory at project root. Directory changes: attachments: .vitest-attachements/ → .vitest/attachments/, blob reporter: .vitest-reports/blob-*.json → .vitest/blob/blob-*.json, HTML reporter: html/index.html → .vitest/index.html (outputFile changed to outputDir), JSON reporter: stdout → .vitest/json/output.json, JUnit reporter: stdout → .vitest/junit/output.xml. The json and junit reporters write to files by default instead of stdout.
Coverage glob thresholds no longer inherit perFile
In Vitest 5.0, coverage.thresholds.perFile no longer applies to glob-pattern thresholds. Glob patterns now control their own per-file checking. Set perFile on each glob that needs it individually.
Coverage include and exclude match more precisely
In Vitest 5.0, coverage.include and coverage.exclude patterns are matched against file paths relative to project root, without picomatch's contains option. A pattern with no glob wildcard is treated as a directory and expanded to match everything inside it. Example: include: ['src'] matches src/**, not every path containing 'src'.
Blob reporter VITEST_BLOB_LABEL environment variable
When running the same tests across multiple environments, use the `VITEST_BLOB_LABEL` environment variable to distinguish each environment's blob. Vitest reads labels at merge time and displays results separately. The label can also be provided via the blob reporter option, which has higher priority than `VITEST_BLOB_LABEL`.
Blob reporter does not include file-based attachments
Blob reporter output doesn't include file-based attachments. Make sure to merge `attachmentsDir` separately alongside blob reports on CI when using this feature. Both `--reporter=blob` and `--merge-reports` do not work in watch mode.
Use custom reporters from NPM or local files
Custom reporters can be used by specifying their package name (`some-published-vitest-reporter`) or file path (`./path/to/reporter.ts`). Custom reporters should implement the Reporter interface.
Extend default reporters with configDefaults
To add a reporter while keeping Vitest's defaults, import `configDefaults` from 'vitest/config' and extend it: `reporters: ['json', ...configDefaults.reporters]`.
Select reporters with --reporter flag or reporters config
Reporters can be selected either by using the `--reporter` command line option or by including a `reporters` property in the Vitest configuration file. If no reporter is specified, Vitest auto-selects reporters based on the environment.
Default reporters selected by environment
When `reporters` is not configured, Vitest uses: `default` in normal terminal runs, `minimal` when Vitest detects an AI coding agent, and `github-actions` is added when `process.env.GITHUB_ACTIONS === 'true'`.
Default reporter output locations
By default, Vitest reporters print to the terminal. The `json`, `junit` and `html` reporters write to scoped locations under `.vitest/`: `json` writes `.vitest/json/output.json`, `junit` writes `.vitest/junit/output.xml`, and `html` writes `.vitest/index.html`.
Override reporter output file location
The `json` and `junit` reporters can override their output file location using the `outputFile` configuration option via CLI (`--outputFile=./test-output.json`) or in vitest.config.ts. The reporter's own `outputFile` option takes precedence over the top-level `outputFile`.
Print reporter output to stdout instead of file
Set the `stdout` option on the `json` or `junit` reporter to print the report to the terminal instead of writing to a file. This option is ignored when `outputFile` is set.
Combine multiple reporters simultaneously
Multiple reporters can be used simultaneously to print test results in different formats: `npx vitest --reporter=json --reporter=default` or in config: `reporters: ['json', ...configDefaults.reporters]`. Each reporter can have its own output file when using an object format for `outputFile`.
Default reporter displays summary and status
The `default` reporter displays a summary of running tests and their status at the bottom. Once a suite passes, its status is reported on top of the summary. The summary can be disabled by setting `summary: false` in the reporter configuration.
Default reporter shows full test tree for single file
If there is only one test file running, the default reporter outputs the full test tree of that file, similar to the tree reporter. The default reporter also prints the test tree if there is at least one failed test in the file.
Verbose reporter prints every test case individually
The verbose reporter prints every test case once it is finished and does not report suites or files separately. It prints test error messages right away and is the only terminal reporter that reports annotations when the test doesn't fail. The summary can be disabled by setting `summary: false`.
Verbose reporter with --includeTaskLocation flag
When `--includeTaskLocation` is enabled with the verbose reporter, it includes the location of each test (file path and line number) in the output.
Tree reporter displays each test after suite completion
The tree reporter is the same as the default reporter but also displays each individual test after the suite has finished. The summary can be disabled by setting `summary: false`.
Dot reporter prints minimal output with one dot per test
The dot reporter prints a single dot for each completed test to provide minimal output while still showing all tests that have run. Details are only provided for failed tests, along with the summary for the suite.
JUnit reporter XML structure and options
The JUnit reporter outputs test results in JUnit XML format, written by default to `.vitest/junit/output.xml`. The XML contains nested `testsuites` → `testsuite` → `testcase` tags. Customizable options: `suiteName` (default: "vitest tests"), `suiteNameTemplate`, `classnameTemplate`, `titleTemplate`, `ancestorSeparator` (default: " > "), `addFileAttribute` (default: false), `includeConsoleOutput` (default: true), `stackTrace` (default: true).
JUnit reporter template placeholders for suiteNameTemplate
Available placeholders for `suiteNameTemplate`: `{title}` (name of first top-level describe block, falls back to file basename), `{filename}` (relative file path from root), `{filepath}` (absolute file path), `{basename}` (file name without directory), `{displayName}` (Vitest project name).
JUnit reporter template placeholders for classnameTemplate and titleTemplate
Available placeholders for `classnameTemplate` and `titleTemplate`: `{classname}` (ancestor describe block names joined by ancestorSeparator), `{title}` (leaf test title), `{suitename}` (top-level describe block name), `{filename}` (relative file path from root), `{filepath}` (absolute file path), `{basename}` (file name without directory), `{displayName}` (Vitest project name).
JSON reporter format compatible with Jest
The JSON reporter generates test results in a JSON format compatible with Jest's `--json` option. By default written to `.vitest/json/output.json`. Since Vitest 3, the JSON reporter includes coverage information in `coverageMap` if coverage is enabled.
JSON reporter filterMeta option
The `meta` field in each assertion result of the JSON reporter can be filtered via the `filterMeta` reporter option. It receives the key and value of each field and should return a falsy value to exclude the field from the report.
HTML reporter generates interactive GUI report
The HTML reporter generates an HTML file to view test results through an interactive GUI. The report artifact root can be specified using the reporter's `outputDir` option. The report entry is written to `<outputDir>/index.html` and UI assets live under `<outputDir>/ui/`. By default `outputDir` is `.vitest`. This reporter requires the `@vitest/ui` package to be installed.
HTML reporter singleFile option
Set `singleFile: true` on the HTML reporter to generate a self-contained HTML report with inlined UI assets, metadata, and test attachments. This makes the report easy to share as one artifact. Caveat: the file can grow very large; coverage HTML reports are not inlined and remain as separate files.
TAP reporter outputs Test Anything Protocol format
The TAP reporter outputs a report following the Test Anything Protocol (TAP) standard. The output uses TAP version 13 with nested hierarchical structure for test suites and cases.
TAP Flat reporter outputs flat test list
The TAP Flat reporter outputs a TAP report with test results formatted following TAP standards, but test suites are formatted as a flat list rather than a nested hierarchy.
Hanging Process reporter monitors hanging processes
The `hanging-process` reporter displays a list of hanging processes if any are preventing Vitest from exiting safely. It does not display test results itself but can be used in conjunction with another reporter. Using this reporter can be resource-intensive and should generally be reserved for debugging purposes.
GitHub Actions reporter enabled automatically in CI
The GitHub Actions reporter is enabled automatically when `process.env.GITHUB_ACTIONS === 'true'` (on GitHub Actions environment). It outputs workflow commands to provide annotations for test failures.
GitHub Actions reporter customizes file paths with onWritePath
The GitHub Actions reporter `onWritePath` option customizes the file paths printed in GitHub's annotation command format. This is useful when running Vitest in containerized environments where file paths may not match the paths in the GitHub Actions environment.
GitHub Actions reporter displayAnnotations option
The GitHub Actions reporter can disable automatic inlining of Annotations API in the GitHub UI by setting `displayAnnotations` option to `false`.