vitest command starts test runner in watch or run mode
The `vitest` command starts Vitest in the current directory. It enters watch mode in development environments and run mode in CI or non-interactive terminals automatically.
cli/commands
20 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 file filter by filename with vitest command
You can pass an additional argument to `vitest` as a filter for test files to run. For example, `vitest foobar` will run only test files that contain 'foobar' in their paths. This filter only checks inclusion and does not support regexp or glob patterns unless the terminal processes them before Vitest receives the filter.
Run tests by filename and line number since Vitest 3
Since Vitest 3, you can specify tests by filename and line number using the format `vitest basic/foo.test.ts:10`. Vitest requires the full filename for this feature to work, which can be relative to the current working directory or an absolute file path. Valid examples: `vitest basic/foo.js:10`, `vitest ./basic/foo.js:10`, `vitest /users/project/basic/foo.js:10`. Invalid examples: `vitest foo:10`, `vitest ./basic/foo:10`. Vitest does not support ranges like `vitest basic/foo.test.ts:10-25`, but does support comma-separated line numbers like `vitest basic/foo.test.ts:10, basic/foo.test.ts:25`.
vitest run performs single run without watch mode
The `vitest run` command performs a single run of tests without entering watch mode.
vitest watch runs tests and watches for changes
The `vitest watch` command runs all test suites and watches for changes, rerunning tests when they change. It is the same as calling `vitest` without an argument. It will fallback to `vitest run` in CI or when stdin is not a TTY (non-interactive environment).
vitest dev alias for watch mode
The `vitest dev` command is an alias to `vitest watch`.
vitest related runs tests covering source files
The `vitest related` command runs only tests that cover a list of source files. It works with static imports like `import('./index.js')` or `import index from './index.js'` but not dynamic ones like `import(filepath)`. All files should be relative to the root folder. Example: `vitest related /src/index.ts /src/hello-world.js`. Useful with lint-staged or CI setup. When using with tools like lint-staged, pass the `--run` option so the command exits normally instead of entering watch mode.
vitest bench runs benchmark tests
The `vitest bench` command runs only benchmark tests, which compare performance results.
vitest init sets up project configuration
The `vitest init <name>` command sets up project configuration. At the moment, it only supports the `browser` value. Example: `vitest init browser`.
vitest list prints matching tests
The `vitest list` command inherits all `vitest` options and prints the list of all matching tests. It ignores the `reporters` option. By default, it prints the names of all tests that matched the file filter and name pattern. Example: `vitest list filename.spec.ts -t="some-test"` outputs the describe blocks and test names in a hierarchical format. The `--json` flag prints tests in JSON format or saves to a file: `vitest list filename.spec.ts -t="some-test" --json=./file.json`. If `--json` does not receive a value, it outputs JSON to stdout. The `--filesOnly` flag prints only test file names: `vitest list --filesOnly`.
vitest list static-parse option
Since Vitest 4.1, the `vitest list` command supports the `--static-parse` flag to parse test files instead of running them to collect tests. Vitest parses test files with limited concurrency, defaulting to `os.availableParallelism()`. You can change the concurrency via the `--static-parse-concurrency` option.
vitest doctor measures test performance under alternative configurations
The `vitest doctor` command measures how much faster the test suite would run under alternative configurations by running it under each of them. The candidates are picked based on the current config. Example output shows baseline and alternative configurations (pool types, isolate settings) with percentage improvements. It runs the full suite several times, so it takes multiple times a normal run's time. Doctor validates that candidates do not break test isolation by running the suite twice with shuffled file order.
vitest doctor probes maxWorkers values
The `vitest doctor` command also probes lower `maxWorkers` values on the winning configuration. Starting from half the current worker count, doctor keeps halving while the suite gets at least 5% faster, and includes the winning value in the recommendation. Every worker funnels its transform requests through the single main-thread Vite server, so past a certain count more workers make the run slower, not faster.
vitest doctor measures DOM environments under both vm pools
Suites running a DOM environment are measured under both vm pools: `vmThreads` and `vmForks`. They amortize the environment creation cost by keeping one environment per worker while every file still gets a fresh VM context. `vmForks` uses child processes instead of worker threads: each child gets its own heap and garbage collector, so either pool can come out faster depending on the suite, and `vmForks` is the vm option for suites that cannot run in worker threads.
vitest doctor measures jsdom against happy-dom
Projects running `jsdom` are also measured under `environment: 'happy-dom'` when the package is installed. The swap is applied per project; projects on other environments keep them. happy-dom implements the DOM differently than jsdom, so tests that depend on layout or navigation should be verified before adopting the swap.
vitest complete provides shell autocompletions
Vitest provides shell autocompletions for commands, options, and option values powered by `@bomb.sh/tab`. For permanent setup in zsh, add `source <(vitest complete zsh)` to `~/.zshrc`. Autocompletions work when running vitest directly through package managers like npm, pnpm, yarn, and bun.
Use vitest run to run tests once without watching
To run tests once without watching for file changes, use the vitest run command. You can also pass additional flags like --reporter or --coverage.
vitest doctor measures alternative configurations
The vitest doctor command measures alternative configurations instead of estimating them: it runs the suite under each candidate and reports the comparison, including whether the tests pass with isolate: false.
Use vitest run when asking AI to execute tests
Vitest runs in watch mode by default. When telling an AI agent to run tests, always use 'vitest run' or 'vitest --no-watch' to ensure the process exits after tests finish, rather than waiting for file changes.
List tags command
Use 'vitest --list-tags' to see all defined tags with their descriptions. Use 'vitest --list-tags=json' to print the tags in JSON format.