Vitest · Config reference · all subjects

config

342 notes in this subject, read out of this brain and free to use. This is page 6 of 6.

typecheck.ignoreSourceErrors configuration

The typecheck.ignoreSourceErrors option is a boolean that prevents test failure if Vitest finds errors outside the test files. Its type is boolean and the default value is false. When this option is enabled, non-test errors will not be shown at all. By default, if Vitest finds a source error, it will fail the test suite.

typecheck.checker configuration

The typecheck.checker option specifies which tools to use for type checking. Its type is 'tsc' | 'vue-tsc' | string, and the default value is 'tsc'. Vitest spawns a process with certain parameters depending on the type. The checker must implement the same output format as tsc. You can pass a path to a custom binary or command name that produces the same output as 'tsc --noEmit --pretty false'. The tsc checker requires the typescript package to be installed, and vue-tsc requires the vue-tsc package to be installed.

typecheck.spawnTimeout configuration

The typecheck.spawnTimeout option specifies the minimum time in milliseconds it takes to spawn the typechecker. Its type is number and the default value is 10_000 (10 seconds).

unstubGlobals configuration option

unstubGlobals is a boolean configuration option with a default value of false. When enabled, Vitest automatically calls vi.unstubAllGlobals() before each test.

unstubGlobals pitfall with async concurrent tests

The unstubGlobals option may cause problems with async concurrent tests. If enabled, the completion of one test will restore all global values that were changed with vi.stubGlobal, including those currently being used by other tests in progress.

unstubGlobals example configuration

To enable unstubGlobals in vitest.config.js: import { defineConfig } from 'vitest/config' followed by export default defineConfig({ test: { unstubGlobals: true } })

update false default behavior in local runs

When update is false (the default) and running locally in a non-CI environment, Vitest resolves snapshot update mode the same as 'new'.

update config option type and default

The update config option has type boolean | 'new' | 'all' | 'none', with a default value of false.

update config CLI flags

The update config option can be set via CLI flags: -u, --update, --update=false, --update=new, or --update=none.

update option true or all value behavior

When update is set to true or 'all', Vitest updates all changed snapshots and deletes obsolete ones.

update option new value behavior

When update is set to 'new', Vitest generates new snapshots without changing or deleting obsolete ones.

update option none value behavior

When update is set to 'none', Vitest does not write snapshots and fails on snapshot mismatches, missing snapshots, and obsolete snapshots.

update false default behavior in CI runs

When update is false (the default) and running in CI (when process.env.CI is truthy), Vitest resolves snapshot update mode the same as 'none'.

watch option enables watch mode

The watch option enables watch mode in Vitest. In interactive environments this is the default unless --run is specified explicitly. In CI or when run from a non-interactive shell, watch mode is not the default but can be enabled explicitly with the watch flag.

watch option type and default value

The watch option has type boolean with default value !process.env.CI && process.stdin.isTTY. This means watch mode is enabled by default in interactive environments unless CI environment variable is set or stdin is not a TTY.

watch option CLI flags

The watch option can be set via CLI using three flags: -w, --watch, or --watch=false.

vmMemoryLimit type and default

The vmMemoryLimit config option has type string | number. The default value is 1 / maxWorkers, which means the total system memory is split evenly between workers.

vmMemoryLimit purpose

vmMemoryLimit specifies the memory limit for workers before they are recycled. Workers are recycled because VM contexts leak memory: a worker's memory usage grows with every test file it runs, so a worker cannot live forever.

vmMemoryLimit default calculation based on maxWorkers

By default, the total system memory is split evenly between workers. By increasing maxWorkers, workers have less memory available, so they are recycled more often.

vmMemoryLimit numeric value formats

The vmMemoryLimit value can be specified in several formats, and Math.floor is used to turn the result into an integer: Values <= 1 are assumed to be a percentage of system memory (e.g., 0.5 sets the limit to half of total system memory). Values > 1 are assumed to be a fixed byte value. If you need exactly 1 byte, you can use 1.1.

vmMemoryLimit unit-based formats

vmMemoryLimit supports percentage and unit-based formats: 50% denotes a percentage of total system memory. Units for fixed memory limits include: K or KB (Kilobytes, x1000), KiB (Kibibytes, x1024), M or MB (Megabytes), MiB (Mebibytes), G or GB (Gigabytes), GiB (Gibibytes). Examples: 100KB, 65MB.

vmMemoryLimit trade-offs for recycling frequency

A low memory limit recycles workers frequently, which is expensive in the vmThreads pool because destroying a worker thread runs a full garbage collection and competes with running tests for the process' shared background threads. The vmForks pool recycles workers by letting the child process exit, making frequent recycling much cheaper. A high limit lets workers accumulate memory, but when combined memory usage of all workers approaches machine capacity, every pool slows down.

vmMemoryLimit percentage-based limit not working on Linux CircleCI

Percentage-based memory limits do not work on Linux CircleCI workers due to incorrect system memory being reported.

watchTriggerPatterns example configuration

Example showing how to configure watchTriggerPatterns: ```ts import { defineConfig } from 'vitest/config' export default defineConfig({ test: { watchTriggerPatterns: [ { pattern: /src\/(mailers|templates)\/(.*)\.{ts|html|txt}$/, testsToRun: (id, match) => { // relative to the root value return `./api/tests/mailers/${match[2]}.test.ts` }, }, ], }, }) ``` This example matches TypeScript, HTML, and text files in src/mailers or src/templates directories, and runs the corresponding test file.

watchTriggerPatterns file path requirements

Returned files from the testsToRun function should be either absolute paths or relative to the root directory.

watchTriggerPatterns is a global option

watchTriggerPatterns is a global option and cannot be used inside project-specific configs.

watchTriggerPatterns option type

The watchTriggerPatterns config option has the type WatcherTriggerPattern[].

watchTriggerPatterns available since version

The watchTriggerPatterns option is available from Vitest version 3.2.0 onwards.

watchTriggerPatterns purpose

watchTriggerPatterns allows you to define regex patterns and functions that return lists of test files to run. This is useful when Vitest cannot detect dependencies through static and dynamic import statements, such as when tests depend on files read from the file system or data fetched from a proxy.

WatcherTriggerPattern object properties

A WatcherTriggerPattern object has a pattern property (a regex pattern) and a testsToRun property (a function that takes id and match parameters and returns a list of test files to run).

fakeTimers.shouldAdvanceTime option

The fakeTimers.shouldAdvanceTime option has type boolean with default value false. It tells @sinonjs/fake-timers to increment mocked time automatically based on the real system time shift (e.g. the mocked time will be incremented by 20ms for every 20ms change in the real system time).

fakeTimers.now option

The fakeTimers.now option has type number | Date with default value Date.now(). It installs fake timers with the specified Unix epoch.

fakeTimers config type

The fakeTimers option has type FakeTimerConfig and passes options down to @sinon/fake-timers when using vi.useFakeTimers().

fakeTimers.toNotFake option

fakeTimers.toNotFake nextTick with forks pool

Mocking nextTick is not supported when running Vitest inside node:child_process by using --pool=forks. When running with --pool=forks, Vitest automatically adds nextTick to the toNotFake array.

fakeTimers toFake and toNotFake cannot be used together

Using both toFake and toNotFake together is not supported.

fakeTimers.advanceTimeDelta option

The fakeTimers.advanceTimeDelta option has type number with default value 20. Relevant only when using with shouldAdvanceTime: true, it increments mocked time by advanceTimeDelta ms every advanceTimeDelta ms change in the real system time.

fakeTimers.toFake Temporal support

Temporal is only faked when it is available on the global object: natively (Node.js >= 26 by default, behind --harmony-temporal on older versions, and supporting browsers) or through a globally installed polyfill such as import 'temporal-polyfill/global'.

fakeTimers.shouldClearNativeTimers option

The fakeTimers.shouldClearNativeTimers option has type boolean with default value true. It tells fake timers to clear native (i.e. not fake) timers by delegating to their respective handlers. When disabled, it can lead to potentially unexpected behavior if timers existed prior to starting fake timers session.

fakeTimers.loopLimit option

The fakeTimers.loopLimit option has type number with default value 10_000. It sets the maximum number of timers that will be run when calling vi.runAllTimers().

Vitest API mode property deprecated

Since Vitest 5, the mode property is always 'test' and is deprecated.

config property contains resolved test config

The config property on vitest object contains the root or global config, which is Vitest config resolved from the test property and does not extend Vite config. If projects are defined, they reference this as globalConfig.

Give your agent this brain