CLI boolean options negation with no- prefix
Boolean CLI options can be negated with the `no-` prefix. For example, `vitest --no-api`. Specifying the value as `false` also works: `vitest --api=false`.
cli/options
74 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
CLI argument formats camelCase and kebab-case both work
Vitest supports both camelCase and kebab-case for CLI arguments. For example, `--passWithNoTests` and `--pass-with-no-tests` both work. Exceptions are `--no-color` and `--inspect-brk`. Vitest also supports different ways of specifying values: `--reporter dot` and `--reporter=dot` are both valid.
merge-reports option merges blob reports
The `--merge-reports` option with type `boolean | string` merges every blob report located in the specified folder (`.vitest/blob/` by default). You can use any reporters with this command except the `blob` reporter. Example: `vitest --merge-reports --reporter=junit`.
merge-reports option default path includes shard config
If `--reporter=blob` is used without an output file, the default path will include the current shard config and blob label from `VITEST_BLOB_LABEL` or the blob reporter `label` option to avoid collisions with other Vitest processes.
shard option incompatible with watch mode
The `--shard` option cannot be used with `--watch` enabled (watch is enabled in dev by default).
shard option divides tests into parts
The `--shard` option divides test suite execution in a format of `<index>`/`<count>`, where `count` is a positive integer (count of divided parts) and `index` is a positive integer (index of divided part). This command divides all tests into `count` equal parts and runs only those in the `index` part. Example: `vitest run --shard=1/3`, `vitest run --shard=2/3`, `vitest run --shard=3/3` splits tests into three parts. Type: string. Default: disabled.
CLI array options require multiple passes
If a CLI option supports an array of values, you need to pass the option multiple times. For example: `vitest --reporter=dot --reporter=default`.
Prevent parallel test file execution during debugging
Use the --no-file-parallelism CLI flag to prevent test files from running in parallel during debugging sessions.
Prevent test timeout when using breakpoints
Use the --test-timeout=0 CLI flag to prevent tests from timing out when stopping at breakpoints during debugging.
Keep debugger open during watch mode test re-runs
Use the --isolate false option to keep the debugger open during test re-runs when running in watch mode.
Filter tests by tags with --tags-filter
Use the `--tags-filter` CLI option to run tests labeled with specific tags. Tests are labeled using the tags option in the test definition: `test('renders a form', { tags: ['frontend'] }, () => {...})`. Then run `vitest --tags-filter=frontend` to run only tests with that tag. This is particularly useful in CI pipelines to run different categories of tests in separate jobs or skip slow integration tests.
Filter tests by file name pattern
Pass a filename pattern as a CLI argument to run only test files whose path contains that string. For example, `vitest basic` matches any test file with 'basic' in its path, including basic.test.ts, basic-foo.test.ts, and basic/foo.test.ts.
Filter tests by test name with -t option
Use the `-t` or `--testNamePattern` option to filter tests by their name rather than filename. It accepts a regex pattern and matches against the full test name, which is composed of enclosing describe block names and the test name joined with ' > '. For example, `vitest -t "handles empty input"` runs only tests with that name. You can combine this with a file filter: `vitest utils -t "handles empty input"`.
Performance note: filters require loading test files
Filters like `-t`, `--tags-filter`, `.only`, and `.skip` are applied per test file, meaning Vitest still has to run each test file to discover which tests match. In large projects, this overhead adds up even if only a few tests actually execute. To avoid this overhead, always pass a file path alongside your filter so Vitest only loads the files you care about, for example: `vitest utils.test.ts -t "handles empty input"`.
Use --experimental.preParse to avoid test file execution overhead
Pass the `--experimental.preParse` flag to parse test files and discover test names without fully executing them. This avoids the overhead of loading all test files when filtering. For example: `vitest --experimental.preParse -t "handles empty input"`.
Filter tests by line number
Point directly to a line number to run a specific test: `vitest basic/foo.test.ts:10` runs the test that contains line 10. The full filename (relative or absolute) is required. Valid formats include `vitest basic/foo.test.ts:10`, `vitest ./basic/foo.test.ts:10`, and `vitest /users/project/basic/foo.test.ts:10`. Partial filenames like `vitest foo:10` or missing extensions like `vitest ./basic/foo:10` do not work. To run multiple specific tests, separate them with spaces: `vitest basic/foo.test.ts:10 basic/foo.test.ts:25`. Ranges like `vitest basic/foo.test.ts:10-25` are not supported.
Environment isolation in Vitest
Vitest isolates each file's environment so environment mutations in one file don't affect others. Isolation can be disabled by passing --no-isolate to the CLI, trading correctness for run performance.
Sharding tests across machines
Run tests on different machines using --shard flag with format --shard=N/M and --reporter=blob flag. All test and coverage results can be merged at the end using vitest --merge-reports --reporter=junit --coverage command.
Sharding example
vitest --shard=1/2 --reporter=blob --coverage vitest --shard=2/2 --reporter=blob --coverage vitest --merge-reports --reporter=junit --coverage
Test filtering feature
Vitest provides many ways to narrow down the tests to run to speed up testing during development. Filtering helps focus on specific tests.
Vitest --standalone flag usage
The --standalone flag starts Vitest and keeps it running in the background without running any tests until files change. Vitest will not run tests if only source code is changed until the test that imports the source has been run.
Test file parallelism with threads
By default Vitest runs test files in multiple processes using node:child_process. To speed up test suite further, enable --pool=threads to run tests using node:worker_threads, though some packages might not work with this setup.
VITEST_BLOB_LABEL environment variable for merged reports
When running the same shards across multiple environments, set the VITEST_BLOB_LABEL environment variable so merged reports can display them separately. Example: VITEST_BLOB_LABEL=linux vitest run --reporter=blob --shard=1/3
Test sharding with --shard and --reporter=blob options
To split Vitest tests on multiple different runs, use --shard option with --reporter=blob option. Example: vitest run --reporter=blob --shard=1/3 for 1st machine, --shard=2/3 for 2nd machine, --shard=3/3 for 3rd machine.
Node compile cache with NODE_COMPILE_CACHE environment variable
Vitest supports Node's on-disk compile cache: when the NODE_COMPILE_CACHE environment variable points at a directory, the V8 bytecode of Vitest's own modules and of externalized dependencies is written to disk and reused by later runs instead of being recompiled. Vitest propagates the variable to every worker, and workers persist the modules they compiled when they shut down. Example: NODE_COMPILE_CACHE=node_modules/.cache/node-compile-cache vitest
Enable fsModuleCache for persistent file system caching
In watch mode, Vitest caches all transformed files in memory by default, but this cache is discarded once the test run finishes. By enabling fsModuleCache, Vitest persists this cache to the file system so it can be reused across reruns. This improvement is most noticeable when rerunning a small number of tests that depend on a large module graph.
Limit directory search with test.dir option
You can limit the working directory when Vitest searches for files using the test.dir option. This should make the search faster if you have unrelated folders and files in the root directory.
Disable file parallelism with --no-file-parallelism flag
To disable parallelism and improve startup time, provide the --no-file-parallelism flag to the CLI or set test.fileParallelism property to false in the config.
Disable test isolation with --no-isolate flag
To disable test isolation and improve test speed for projects that don't rely on side effects and properly cleanup their state, provide the --no-isolate flag to the CLI or set test.isolate property to false in the config.
Merge test shards with --merge-reports option
Collect the results stored in .vitest/blob/ directory from each machine and merge them with the --merge-reports option: vitest run --merge-reports
VITEST_MAX_WORKERS for high CPU-count machines
Test sharding can become useful on high CPU-count machines because Vitest runs only a single Vite server in its main thread, and the rest of threads run test files. On a high CPU-count machine the main thread can become a bottleneck. To reduce the load from main thread's Vite server you can use test sharding to balance the load on multiple Vite servers. Example for 32 CPU machine split to 4 shards: VITEST_MAX_WORKERS=7 vitest run --reporter=blob --shard=1/4 (repeated for shards 2, 3, 4), then vitest run --merge-reports
Test sharding splits test files not test cases
Test sharding is a process of splitting your test suite into groups, or shards, for running on multiple machines simultaneously. Vitest splits your test files, not your test cases, into shards. For example, if you have 1000 test files, the --shard=1/4 option will run 250 test files, no matter how many test cases individual files have.
Node compile cache with empty directory
The first run with an empty compile cache directory pays for serializing the compiled modules, so the NODE_COMPILE_CACHE is only worth enabling when the directory survives between runs: local runs, or CI pipelines that cache the directory. NODE_DISABLE_COMPILE_CACHE=1 disables the cache entirely, taking precedence over NODE_COMPILE_CACHE.
Verbose reporter for detailed test output
Use `vitest --reporter=verbose` to show every test individually rather than just the files. This helps spot patterns in which tests pass and which fail when the default output isn't showing enough detail.
Run tests for a single project with --project flag
To run tests only inside a single project, use the --project CLI option with the project name. For example: npm run test --project e2e or yarn test --project e2e.
Run tests for multiple projects with --project flag
The --project CLI option can be used multiple times to filter out several projects. For example: npm run test --project e2e --project unit will run tests only for the e2e and unit projects.
Enable import durations from CLI without config
You can enable import duration profiling from the command line without modifying your configuration: ```bash vitest --experimental.importDurations.print ```
Enable import duration logging with experimental.importDurations
Enable experimental.importDurations in vitest.config.ts to identify slow module imports: ```ts import { defineConfig } from 'vitest/config' export default defineConfig({ test: { experimental: { importDurations: { print: true, }, }, }, }) ``` This prints a breakdown of the slowest imports after tests finish, showing Self and Total times for each module.
Tags filter with wildcards
You can use a wildcard (*) in tags filter to match any number of characters. For example, 'vitest --tags-filter="unit/*"' will match tags like unit/components, unit/utils, etc.
Filtering tests by tag with --tags-filter
Use the --tags-filter CLI option to run only tests with specific tags. Examples: - vitest --tags-filter=frontend - vitest --tags-filter="frontend and backend" - vitest --tags-filter="unit or e2e" - vitest --tags-filter="!slow" - vitest --tags-filter="frontend && !flaky" - vitest --tags-filter="api/*" - vitest --tags-filter="(unit || e2e) && !slow" - vitest --tags-filter="db && (postgres || mysql) && !slow" You can also pass multiple --tags-filter flags; they are combined with AND logic.
HTML reporter configuration example
To generate an HTML report, add reporters: ['html'] to the test configuration in vitest.config.ts.
Cached import displays 0ms in Module Info
When an import was already evaluated earlier in the module graph, Module Info shows 0ms for its total time because it is cached.
Module import time color coding in Module Info
If a module took longer than the danger threshold (default: 500ms) to load, the time displays in red. If longer than the warn threshold (default: 100ms), it displays in orange.
Click import to traverse module graph
In Module Info's Source window, click on an import source to jump to that module and traverse the graph further.
Type-only imports do not display duration
Type-only imports are not executed at runtime and do not display a total duration in Module Info. They also cannot be opened.
Injected imports display in gray
Imports injected by plugins during transformation (such as those from import.meta.glob) display in gray color at the start of the module in Module Info. They show total time and can be traversed.
Import Breakdown shows top modules by load time
The Import Breakdown in the Module Graph tab displays the top 10 modules that take the longest time to load (by default), sorted by Total Time.
Import Breakdown module color indicates externality
In Import Breakdown, external modules are displayed in yellow color, the same color used in the module graph.
Import Breakdown displays self time, total time, and percentage
The Import Breakdown list shows each module's self time, total time, and a percentage relative to the time it took to load the whole test file.
Import Breakdown icon color indicates performance thresholds
The 'Show Import Breakdown' icon displays in red if at least one file exceeded the danger threshold (default: 500ms), and orange if at least one file exceeded the warn threshold (default: 100ms).
Control Import Breakdown list size with experimental.importDurations.limit
Use the config option experimental.importDurations.limit to control the number of imports displayed in the Import Breakdown.
HTML report output directory configuration
The HTML reporter's outputDir option controls the output location. It points to the report artifact root, and the report entry is written to <outputDir>/index.html. The default value is .vitest, the shared Vitest artifact directory.
Preview HTML report locally
Use the command npx vite preview --outDir .vitest to preview the HTML report locally.
Single file portable HTML report
Use the singleFile option in the HTML reporter to generate a portable report that can be opened or shared as one file.
Upload HTML report to GitHub Actions
To view an HTML report from CI in GitHub Actions, upload the output directory as an artifact using actions/upload-artifact@v7 and link to it in the job summary.
View HTML report in Vitest Viewer
After uploading an HTML report to GitHub Actions, create a link to view it using https://viewer.vitest.dev/?url=<artifact-url> to open the report in Vitest Viewer directly in the browser.
Module Graph tab displays module dependencies
The Module Graph tab in Vitest UI displays the module graph of the selected test file, showing how modules depend on each other.
Module Graph displays first two levels when over 50 modules
If there are more than 50 modules, the Module Graph in Vitest UI displays only the first two levels of the graph to reduce visual clutter. Click 'Show Full Graph' to preview the complete graph.
Reset Module Graph to entry module
Click 'Reset' in the Module Graph to restore the entry module graph view.
Expand Module Graph nodes
Right-click or hold Shift while clicking a node in the Module Graph to expand it and display all related nodes.