printConsoleTrace purpose
The printConsoleTrace option enables always printing console traces when calling any console method. This is useful for debugging.
Vitest · Config reference · all subjects
config
342 notes in this subject, read out of this brain and free to use. This is page 4 of 6.
projects config creates container for tests
A config file that declares projects does not run tests itself, but only provides the projects that do. This also applies to project config files: a referenced config that declares projects becomes a container for nested projects.
projects option not supported in inline project configuration
The projects option is not supported inside an inline project configuration.
projects config option type and default
The projects configuration option has type TestProjectConfiguration[] and a default value of an empty array [].
provide TypeScript type augmentation
To enable type-safe access to provided values in TypeScript, augment the ProvidedContext interface in a .d.ts file by declaring module 'vitest' and extending the ProvidedContext interface with your custom properties.
provide config example usage
Example: In vitest.config.js, define provide: { API_KEY: '123' }. In a test file, use inject('API_KEY') to retrieve the value '123'.
provide config option type and purpose
The provide configuration option has type Partial<ProvidedContext>. It defines values that can be accessed inside tests using the inject method.
provide config option serialization requirement
The provide option requires that properties be strings and values be serializable according to the Web Workers structured clone algorithm, because the object is transferred between different processes.
repeats config option
The repeats option is a number type configuration that defaults to 0. It can be set via CLI using --repeats=<number>. This option repeats every test a specific number of times regardless of the result. A test that uses the repeats test option takes precedence over this config value. If a test fails on any repetition, the whole test is reported as failed.
resolveSnapshotPath default behavior
The default resolveSnapshotPath stores snapshot files in a __snapshots__ directory.
resolveSnapshotPath context parameter access
The context parameter passed to resolveSnapshotPath contains a config property with the project's serialized config. This allows access to the project name via context.config.name when you have multiple projects configured.
resolveSnapshotPath type signature
resolveSnapshotPath is a function with type (testPath: string, snapExtension: string, context: { config: SerializedConfig }) => string. It takes a test file path, snapshot file extension, and context object containing the serialized config, and returns a string representing the resolved snapshot path.
resolveSnapshotPath multi-project example
The following example uses the context parameter to access the project's serialized config and stores snapshots in different locations based on the project name: ```ts import { basename, dirname, join } from 'node:path' import { defineConfig } from 'vitest/config' export default defineConfig({ test: { resolveSnapshotPath(testPath, snapExtension, context) { return join( dirname(testPath), '__snapshots__', context.config.name ?? 'default', basename(testPath) + snapExtension, ) }, }, }) ```
resolveSnapshotPath example storing snapshots next to test files
The following example stores snapshots next to test files instead of in a __snapshots__ directory: ```ts import { defineConfig } from 'vitest/config' export default defineConfig({ test: { resolveSnapshotPath: (testPath, snapExtension) => testPath + snapExtension, }, }) ```
reporters config type and default
The reporters configuration option has type ConfigReporter | Array<ConfigReporter>, where ConfigReporter can be a string, Reporter, or [string, object?]. The default value is ['default']. Environment-specific behavior is documented in the Default Reporters guide.
custom reporter configuration
Alongside built-in reporters, you can pass a custom implementation of a Reporter interface, or a path to a module that exports it as a default export (e.g. './path/to/reporter.ts', '@scope/reporter'). Configure a reporter by providing a tuple [string, object], where the string is a reporter name, and the object is the reporter's options.
reporters config example with conditional and custom reporters
Example vitest.config.js showing how to use reporters: ```js import { configDefaults, defineConfig } from 'vitest/config' export default defineConfig({ test: { reporters: [ ...configDefaults.reporters, // conditional reporter ...(process.env.CI ? ['html'] : []), // custom reporter from npm package // options are passed down as a tuple [ 'vitest-sonar-reporter', { outputFile: 'sonar-report.xml' } ], ] } }) ``` This demonstrates using default reporters with conditional logic and passing options to a custom reporter via tuple syntax.
reporters CLI syntax
Use --reporter=tap for a single reporter. Use --reporter=verbose --reporter=github-actions for multiple reporters.
built-in reporters list
Vitest includes the following built-in reporters: default, verbose, tree, dot, junit, json, html, tap, tap-flat, hanging-process, github-actions, minimal (aliased as agent), and blob.
reporters option purpose
The reporters option defines a single reporter or a list of reporters available to Vitest during the test run.
restoreMocks configuration option
The restoreMocks option is a boolean configuration that controls whether Vitest automatically calls vi.restoreAllMocks() before each test. When enabled, it restores all original implementations on spies created manually with vi.spyOn(). The type is boolean and the default value is false.
restoreMocks async concurrent tests warning
Be aware that the restoreMocks option may cause problems with async concurrent tests. If enabled, the completion of one test will restore the implementation for all spies, including those currently being used by other tests in progress.
restoreMocks configuration example
Example configuration: import { defineConfig } from 'vitest/config' export default defineConfig({ test: { restoreMocks: true, }, })
root config option type and CLI
The root option is of type string. It can be set via CLI using -r <path> or --root=<path>.
root config purpose
The root option specifies the project root.
runner config option type and purpose
The runner configuration option has type VitestRunnerConstructor and specifies a path to a custom test runner. This is an advanced feature intended for use with custom library runners.
retry advanced object config example
This example shows how to configure retry with an object containing count, delay, and condition: ```ts export default defineConfig({ test: { retry: { count: 3, delay: 1000, condition: /ECONNREFUSED|timeout/i, }, }, }) ```
retry CLI flags
The retry config option supports CLI flags: `--retry <times>` for simple retry count, `--retry.count <times>` for count, `--retry.delay <ms>` for delay in milliseconds, and `--retry.condition <pattern>` for error pattern matching.
retry count option
The `count` option specifies the number of times to retry a test if it fails. Type is `number`, default is `0`.
retry delay option
The `delay` option specifies the delay in milliseconds between retry attempts. Type is `number`, default is `0`. It is useful for tests that interact with rate-limited APIs or need time to recover.
retry condition option
The `condition` option is a RegExp pattern or a function to determine if a test should be retried based on the error. When a RegExp, it is tested against the error message. When a function, it receives the error and returns a boolean. Type is `RegExp | (error: Error) => boolean`, default is undefined.
retry condition as function must be in test file
When defining `condition` as a function, it must be done in a test file directly, not in a configuration file, because configurations are serialized for worker threads.
retry simple config example
This example shows how to configure retry with a simple number: ```ts export default defineConfig({ test: { retry: 3, }, }) ```
retry RegExp condition example
This example shows retry with a RegExp condition in the config file: ```ts export default defineConfig({ test: { retry: { count: 2, condition: /ECONNREFUSED|ETIMEDOUT/i, }, }, }) ```
retry function condition example
This example shows retry with a function condition in a test file: ```ts import { describe, test } from 'vitest' describe('tests with advanced retry condition', () => { test('with function condition', { retry: { count: 2, condition: error => error.message.includes('Network') } }, () => { // test code }) }) ```
retry per-test override example
This example shows how to define retry options per test or suite in test files: ```ts import { describe, test } from 'vitest' describe('flaky tests', { retry: { count: 2, delay: 100, }, }, () => { test('network request', () => { // test code }) }) test('another test', { retry: { count: 3, condition: error => error.message.includes('timeout'), }, }, () => { // test code }) ```
retry config option type and default
The retry config option has type `number | { count?: number, delay?: number, condition?: RegExp }` and default value `0`.
server.deps.fallbackCJS option type and default
The server.deps.fallbackCJS option has type boolean and default value of false.
server.deps.fallbackCJS behavior
When enabled, Vitest will try to guess a CommonJS build for an ESM entry by checking a few common CJS/UMD file name and folder patterns (like .mjs, .umd.js, .cjs.js, umd/, cjs/, lib/). This is a best-effort heuristic to work around confusing or incorrect ESM/CJS packaging and may not work for all dependencies.
server.deps.external configuration example
import { defineConfig } from 'vitest/config' export default defineConfig({ test: { server: { deps: { external: ['react'], }, }, }, })
server.deps.external behavior
server.deps.external specifies modules that should not be transformed by Vite and should instead be processed directly by the engine. These modules are imported via native dynamic import and bypass both transformation and resolution phases. External modules and their dependencies are not present in the module graph and will not trigger test restarts when they change. Typically, packages under node_modules are externalized.
server.deps.inline string matching behavior
When a string is provided to server.deps.inline, it is first normalized by prefixing /node_modules/ or other moduleDirectories segments (for example, 'react' becomes /node_modules/react/), and the resulting string is then matched against the full file path. For example, package @company/some-name located inside packages/some-name should be specified as some-name, and packages should be included in deps.moduleDirectories.
server.deps.inline option type and default
The server.deps.inline option has type (string | RegExp)[] | true and default value of everything that is not externalized.
server.deps.inline behavior
server.deps.inline specifies modules that should be transformed and resolved by Vite. These modules are run by Vite's module runner. Typically, source files are inlined.
server.deps.inline RegExp matching behavior
When a RegExp is provided to server.deps.inline, it is matched against the full file path.
server.deps.external option type and default
The server.deps.external option has type (string | RegExp)[] and default value of files inside moduleDirectories.
sequence.shuffle.tests type and default
sequence.shuffle.tests has type boolean with default value false. It determines whether to randomize tests.
sequence.sequencer default and type
sequence.sequencer has type TestSequencerConstructor with default value BaseSequencer. It is a custom class that defines methods for sharding and sorting. You can extend BaseSequencer from vitest/node if you only need to redefine one of the sort and shard methods, but both should exist. Sharding happens before sorting, and only if --shard option is provided. If sequence.groupOrder is specified, the sequencer will be called once for each group and pool.
sequence.groupOrder default and type
sequence.groupOrder has type number with default value 0. It controls the order in which a project runs its tests when using multiple projects. Projects with the same group order number will run together, and groups are run from lowest to highest. If you don't set this option, all projects run in parallel. If several projects use the same group order, they will run at the same time. This setting only affects the order in which projects run, not the order of tests within a project.
sequence.shuffle type and default
sequence.shuffle has type `boolean | { files?, tests? }` with default value false. It controls whether files and tests run randomly. When enabled via this option or CLI argument --sequence.shuffle, files and tests will run in random order.
sequence.shuffle.files type and default
sequence.shuffle.files has type boolean with default value false. It determines whether to randomize files. Be aware that long running tests will not start earlier if you enable this option. File ordering is shared across projects, so this option is resolved from the root config only. A project can still randomize its own tests with sequence.shuffle.tests.
sequence.concurrent type and default
sequence.concurrent has type boolean with default value false. It controls whether tests run in parallel when enabled via this option or CLI argument --sequence.concurrent.
sequence.seed type and default
sequence.seed has type number with default value Date.now(). It sets the randomization seed when tests are running in random order.
sequence.hooks type and default
sequence.hooks has type `'stack' | 'list' | 'parallel'` with default value 'stack'. It changes the order in which hooks are executed. With 'stack', after hooks run in reverse order and before hooks run in the order they were defined. With 'list', all hooks run in the order they are defined. With 'parallel', hooks in a single group run in parallel (hooks in parent suites still run before the current suite's hooks), limited by maxConcurrency. This option does not affect onTestFinished, which is always called in reverse order.
sequence.setupFiles type and default
sequence.setupFiles has type `'list' | 'parallel'` with default value 'parallel'. It changes the order in which setup files are executed. With 'list', setup files run in the order they are defined. With 'parallel', setup files run in parallel.
sequence configuration via CLI with dot notation
Sequence options can be provided to CLI using dot notation, for example: npx vitest --sequence.shuffle --sequence.seed=1000
Vitest groupOrder example with multiple projects
Example of groupOrder in multiple projects configuration: ```ts import { defineConfig } from 'vitest/config' export default defineConfig({ test: { projects: [ { test: { name: 'slow', sequence: { groupOrder: 0, }, }, }, { test: { name: 'fast', sequence: { groupOrder: 0, }, }, }, { test: { name: 'flaky', sequence: { groupOrder: 1, }, }, }, ], }, }) ``` Projects with groupOrder 0 (slow and fast) run together, then the flaky project with groupOrder 1 runs after.
sequence config option type and structure
The sequence config option has type `{ sequencer?, shuffle?, seed?, hooks?, setupFiles?, groupOrder }` and controls options for how tests should be sorted.
silent config purpose
The silent option silences console output from tests.
silent 'passed-only' value behavior
When silent is set to 'passed-only', logs from failing tests are shown while logs from passing tests are suppressed. Logs from failing tests are printed after the test has finished.