Vitest 5.0 prerequisites
Vitest 5.0 requires Vite >= 6.4.0 and Node.js >= 22.12.0. Running Vitest 5.0 on older versions of Vite or Node.js is not supported and may result in unexpected errors.
writing & running tests
55 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Test titles and inspected values use pretty-format
In Vitest 5.0, values are formatted with pretty-format instead of loupe when inspected, including values interpolated into test.each and test.for titles. A string value interpolated through a $ placeholder is no longer wrapped in quotes (e.g., 'case a1' instead of 'case \'a1\'). The length limit for interpolated values is controlled by the new taskTitleValueFormatTruncate option (default 40).
taskTitleValueFormatTruncate option controls value formatting
In Vitest 5.0, the taskTitleValueFormatTruncate option (default: 40) controls the length limit for values interpolated into test titles when using test.each or test.for.
Removed test.sequential, describe.sequential, and sequential option
In Vitest 5.0, test.sequential, describe.sequential, and the sequential option are removed. Use concurrent: false when you need a test or suite to opt out of inherited or globally configured concurrency.
DOM environment global assignments update underlying window
In Vitest 5.0, assignments to properties on globalThis or window in jsdom and happy-dom environments are now propagated to the underlying DOM implementation. Mutable properties such as innerWidth can affect APIs implemented by the DOM environment.
populateGlobal returns descriptors in originals
In Vitest 5.0, the originals map returned by populateGlobal now holds property descriptors instead of plain values. This avoids invoking native lazy getters while capturing the original. When restoring them manually in a custom environment, use Object.defineProperty instead of assignment.
testNamePattern uses > separator in reporter output
In Vitest, expect.getState().currentTestName uses a > symbol to join describe title and test title, making it easier to distinguish tests from suites. Test names are formatted as 'describeTitle > testTitle' rather than space-separated.
vi.setConfig for setting timeout
To set a timeout for a test in Vitest, use vi.setConfig({ testTimeout: milliseconds }) instead of Jest's jest.setTimeout.
Vitest globals configuration
Jest has its globals API enabled by default. Vitest does not. Either enable globals via the globals configuration setting or import from the vitest module instead.
Designate multiple output files for reporters
When using multiple reporters, specify outputFile as an object with reporter names as keys and file paths as values. Example: outputFile: { junit: './junit-report.xml', json: './json-report.json' }
Default reporter displays test summary
The default reporter displays summary of running tests and their status at the bottom. Once a suite passes, its status is reported on top of the summary.
Disable summary in default reporter
Configure the default reporter with summary: false to disable the summary output. Example: ['default', { summary: false }]
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
The verbose reporter prints every test case once it is finished. It does not report suites or files separately. It prints test error messages right away, with the full test error reported when the test run is finished.
Verbose reporter reports test annotations
The verbose reporter is the only terminal reporter that reports annotations when the test doesn't fail.
Tree reporter displays individual tests
The tree reporter is same as the default reporter, but it also displays each individual test after the suite has finished. You can disable the summary by configuring it with summary: false.
Dot reporter minimal output
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 default output location
The JUnit reporter outputs a report in JUnit XML format to .vitest/junit/output.xml by default. Use the outputFile configuration option or the reporter's own outputFile option to write elsewhere.
JUnit reporter XML structure
The JUnit reporter output contains nested testsuites → testsuite → testcase tags in XML format.
JUnit reporter configuration options
JUnit reporter options: suiteName (default 'vitest tests'), suiteNameTemplate (template for testsuite name, default relative file path), classnameTemplate (template for classname attribute, default relative file path), titleTemplate (template for testcase name, default full test title), ancestorSeparator (default ' > '), addFileAttribute (default false), includeConsoleOutput (default true), stackTrace (default true).
JUnit reporter suiteNameTemplate placeholders
Available placeholders for suiteNameTemplate: {title} (first top-level describe block name, 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 classnameTemplate and titleTemplate placeholders
Available placeholders: {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).
JUnit reporter function-based templates
JUnit reporter templates can be functions that receive all available variables and return any string. Example: classnameTemplate: ({ classname, filename }) => classname ? `${filename}::${classname}` : filename
JSON reporter default output location
The JSON reporter generates a report in JSON format compatible with Jest's --json option, written to .vitest/json/output.json by default. Use the outputFile configuration option or the reporter's own outputFile option to write elsewhere.
JSON reporter filterMeta option
The meta field in each assertion result 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 interactive GUI
The HTML reporter generates an HTML file to view test results through an interactive GUI. After generation, Vitest keeps a local development server running and provides a link to view the report in a browser.
HTML reporter outputDir option
The HTML reporter uses its outputDir option to specify the report artifact root. The report entry is written to <outputDir>/index.html and UI assets live under <outputDir>/ui/. Default outputDir is .vitest, the shared Vitest artifact directory.
HTML reporter singleFile option
Set singleFile to true to generate a self-contained HTML report with UI assets, metadata, and test attachments inlined into a single index.html file.
TAP flat reporter flat hierarchy
The TAP flat reporter outputs a TAP report with test results following TAP standards, but test suites are formatted as a flat list rather than a nested hierarchy.
Hanging process reporter monitors process lifecycle
The hanging-process reporter displays a list of hanging processes that may be preventing Vitest from exiting safely. It does not display test results itself but can be used in conjunction with another reporter to monitor processes while tests run.
GitHub Actions reporter enabled automatically
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 onWritePath option
The GitHub Actions reporter onWritePath option customizes file paths in GitHub's annotation command format. This is useful when running Vitest in a containerized environment where file paths may not match the GitHub Actions environment.
GitHub Actions reporter displayAnnotations option
The GitHub Actions reporter displayAnnotations option can be set to false to disable inline annotations in the GitHub UI when using the Annotations API.
GitHub Actions reporter generates Job Summary
The GitHub Actions reporter automatically generates a Job Summary with an overview of test results. The summary includes test file and test case statistics, and highlights flaky tests that required retries.
GitHub Actions jobSummary enabled by default
The GitHub Actions reporter job summary is enabled by default and writes to the path specified by $GITHUB_STEP_SUMMARY. Override with jobSummary.outputPath option.
GitHub Actions jobSummary title customization
The job summary title defaults to 'Vitest Test Report' or '(${test.name}) Vitest Test Report' when test.name is set. Customize by setting jobSummary.title to distinguish multiple Vitest invocations appending to the same job summary.
GitHub Actions fileLinks customization
The GitHub Actions reporter generates permalink URLs for flaky tests using environment variables ($GITHUB_REPOSITORY, $GITHUB_SHA, $GITHUB_WORKSPACE). Override via fileLinks option with repository, commitHash, and workspacePath properties.
Minimal reporter optimized for AI agents
The minimal reporter (alias: agent) outputs only failed tests and their error messages. Console logs from passing tests and the summary section are suppressed. It is enabled automatically when Vitest detects it is running inside an AI coding agent.
Blob reporter stores test results for merging
The blob reporter stores test results on the machine so they can be merged later using the --merge-reports command. By default stores all results in .vitest/blob/ folder, but can be overridden with --outputFile or --outputFile.blob flags.
Blob reporter for sharded and multi-environment tests
Use the blob reporter if running Vitest on different machines with the --shard flag or across multiple environments (e.g., linux/macos/windows). All blob reports can be merged into any report using --merge-reports command.
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.
Blob reporter label option
The blob reporter accepts a label option in configuration that has higher priority than VITEST_BLOB_LABEL environment variable.
Blob reporter does not include file-based attachments
Blob reporter output doesn't include file-based attachments. Merge attachmentsDir separately alongside blob reports on CI when using this feature.
Custom reporters from NPM packages
You can use third-party custom reporters installed from NPM by specifying their package name in the reporters option. Example: reporters: ['some-published-vitest-reporter']
Custom reporters from file path
You can define your own custom reporters and use them by specifying their file path. Example: npx vitest --reporter=./path/to/reporter.ts. Custom reporters should implement the Reporter interface.
TAP reporter Test Anything Protocol
The TAP reporter outputs a report following the Test Anything Protocol (TAP) standard.
Watch mode limitation for blob reporter and merge-reports
Both --reporter=blob and --merge-reports do not work in watch mode.
Default reporter selected in different environments
When reporters is not configured, Vitest uses: default reporter in normal terminal runs, minimal reporter when Vitest detects an AI coding agent, and github-actions reporter is added when process.env.GITHUB_ACTIONS === 'true'.
Configure reporters in vitest.config.ts
Set the reporters property in the test configuration object. Example: export default defineConfig({ test: { reporters: ['verbose'] } })
Pass options to reporters in configuration
Reporters with options are specified as an array with the reporter name and an options object. Example: ['junit', { suiteName: 'UI tests' }]
Keep default reporters when adding custom reporters
To add a reporter while keeping Vitest's defaults, extend configDefaults.reporters. Example: reporters: ['json', ...configDefaults.reporters]
Default output locations for reporters
json reporter writes to .vitest/json/output.json, junit reporter writes to .vitest/junit/output.xml, and html reporter writes to .vitest/index.html. The json and junit locations can be overridden with the outputFile configuration option.
Reporter option outputFile takes precedence
The outputFile option specified in the reporter options takes precedence over the top-level outputFile configuration option.
Print reporter output to terminal with stdout option
Set the stdout option to true on the json or junit reporter to print the report to the terminal instead of writing to a file. This is ignored when outputFile is set.
Use multiple reporters simultaneously
You can use multiple reporters at the same time to display test results in different formats. Example: npx vitest --reporter=json --reporter=default