Vitest · Config reference · all subjects

config

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

dangerouslyIgnoreUnhandledErrors config option

dangerouslyIgnoreUnhandledErrors is a boolean configuration option in Vitest. When set to true, Vitest will not fail the test run if there are unhandled errors, though built-in reporters will still report them. The default value is false. It can be set via CLI using --dangerouslyIgnoreUnhandledErrors or --dangerouslyIgnoreUnhandledErrors=false.

dangerouslyIgnoreUnhandledErrors example configuration

To use dangerouslyIgnoreUnhandledErrors in vitest.config.js, import defineConfig from 'vitest/config' and set it under test: dangerouslyIgnoreUnhandledErrors: true.

onUnhandledError callback for conditional error filtering

The onUnhandledError callback can be used as an alternative to dangerouslyIgnoreUnhandledErrors when you want to filter out certain errors conditionally rather than ignoring all unhandled errors.

detectAsyncLeaks performance impact warning

Enabling the detectAsyncLeaks option will make tests run much slower. It should only be used when debugging or developing tests.

detectAsyncLeaks detects asynchronous resources leaking from test file

The detectAsyncLeaks option detects asynchronous resources leaking from the test file by using node:async_hooks to track creation of async resources. If a resource is not cleaned up, it will be logged after tests have finished.

detectAsyncLeaks example with setTimeout leak

Example: if code has setTimeout calls that execute the callback after tests have finished, the error message will show 'Async Leaks 1' with the file name and line number where the leak occurred. To fix a setTimeout leak, use a cleanup function that calls clearTimeout with the stored timeout reference.

detectAsyncLeaks config option type, CLI, and default

The detectAsyncLeaks configuration option has type boolean, can be set via CLI using --detectAsyncLeaks or --detect-async-leaks flags, and has a default value of false.

diff.expand option

The diff.expand option has Type: boolean, Default: true, and CLI flag: --diff.expand=false. It expands all common lines in the diff output.

diff.truncateThreshold option

The diff.truncateThreshold option has Type: number, Default: 0, and CLI flag: --diff.truncateThreshold=<path>. It sets the maximum length of diff result to be displayed. Diffs above this threshold will be truncated. Truncation won't take effect with the default value of 0.

diff.truncateAnnotationColor option

The diff.truncateAnnotationColor option has Type: DiffOptionsColor = (arg: string) => string and Default: noColor = (string: string): string => string. It sets the color of truncate annotation, with the default outputting no color.

diff.maxDepth option

The diff.maxDepth option has Type: number and Default: 20 (or 8 when comparing different types). It limits the depth to recurse when printing nested objects.

diff configuration as module example

Example of configuring diff as a module path in vitest.config.js: In vitest.config.js: import { defineConfig } from 'vitest/config' export default defineConfig({ test: { diff: './vitest.diff.ts', }, }) In vitest.diff.ts: import type { DiffOptions } from 'vitest' import c from 'picocolors' export default { aIndicator: c.bold('--'), bIndicator: c.bold('++'), omitAnnotationLines: true, } satisfies DiffOptions

diff.printBasicPrototype option

The diff.printBasicPrototype option has Type: boolean and Default: false. It controls whether basic prototype Object and Array are printed in diff output.

diff.truncateAnnotation option

The diff.truncateAnnotation option has Type: string, Default: '... Diff result is truncated', and CLI flag: --diff.truncateAnnotation=<annotation>. It specifies the annotation that is output at the end of diff result if it's truncated.

diff configuration option

The diff option accepts a string (Type: string) via CLI flag --diff=<path> or as a DiffOptions object. It specifies either a DiffOptions configuration object or a path to a module which exports DiffOptions. This is useful if you want to customize diff display. Vitest uses @vitest/pretty-format under the hood for diff rendering, and part of DiffOptions is forwarded to the pretty-format configuration while the rest affects diff rendering itself.

diff configuration as config object example

Example of configuring diff as a config object in vitest.config.js: import { defineConfig } from 'vitest/config' import c from 'picocolors' export default defineConfig({ test: { diff: { aIndicator: c.bold('--'), bIndicator: c.bold('++'), omitAnnotationLines: true, }, }, })

dir config option

The dir configuration option is a string that specifies the base directory to scan for test files. It can be set via the CLI with --dir=<path>. The default value is the same as root. This option is used to speed up test discovery if the root covers the whole project.

disableConsoleIntercept config option

The disableConsoleIntercept config option is a boolean that controls whether Vitest intercepts console output during tests. It has a type of boolean, a CLI flag of --disableConsoleIntercept, and a default value of false. By default, Vitest intercepts console output to add context such as the test file and test title. In browser mode, console interception is required to forward logs from the browser DevTools to the terminal and is also required for console log previews in the Vitest UI. Disabling console interception can be useful when debugging code with normal synchronous terminal logging.

env config option type and purpose

The env config option has type Partial<NodeJS.ProcessEnv> and defines environment variables available on process.env and import.meta.env during tests. These variables are not available in the main process, such as in globalSetup.

environmentOptions configuration example

Example vitest.config.js showing environmentOptions with jsdom configured to use url 'http://localhost:3000' and happyDOM configured with width 300 and height 400: ```js import { defineConfig } from 'vitest/config' export default defineConfig({ test: { environmentOptions: { jsdom: { url: 'http://localhost:3000', }, happyDOM: { width: 300, height: 400, }, }, }, }) ```

environmentOptions environment scoping requirement

Options in environmentOptions are scoped to their environment. jsdom options must be placed under the jsdom key and happyDOM options must be placed under the happyDOM key. This allows mixing multiple environments within the same project.

environmentOptions purpose and usage

environmentOptions contains options that are passed to the setup method of the current environment. By default, you can configure options only for jsdom and happyDOM when you use them as your test environment.

environmentOptions config type and default

environmentOptions is a configuration option with type Record<'jsdom' | 'happyDOM' | string, unknown> and a default value of an empty object {}.

builtinEnvironments export from vitest/environments

Vitest exposes builtinEnvironments through the vitest/environments entry point, which can be used if you want to extend existing environments.

environmentOptions for custom environment configuration

To define custom options for your environment, use the environmentOptions configuration option.

jsdom global variable

When using jsdom environment, Vitest exposes a jsdom global variable equal to the current JSDOM instance. To make TypeScript recognize it, add 'vitest/jsdom' to the types array in compilerOptions in tsconfig.json.

viteEnvironment field in custom environment

The viteEnvironment field in a custom environment corresponds to the environment defined by the Vite Environment API. By default, Vite exposes 'client' environment for the browser and 'ssr' environment for the server.

Custom environment definition

Custom environments can be defined in a file. For non-builtin environments, Vitest tries to load the file if it's relative or absolute path, or loads a package named vitest-environment-${name} for bare specifiers. The custom environment file should export an object with Environment type shape, containing: name (string), viteEnvironment (string), and setup() function that returns an object with teardown() method.

Custom environment example

Example of a custom environment export: import type { Environment } from 'vitest' export default <Environment>{ name: 'custom', viteEnvironment: 'ssr', setup() { // custom setup return { teardown() { // called after all tests with this env have been run } } } }

Browser Mode alternative to environment

Vitest provides Browser Mode as an alternative to mocking the environment, allowing you to run integration or unit tests in the browser.

@vitest-environment docblock for per-file environment

You can specify a different environment for all tests in a file by adding a @vitest-environment docblock or comment at the top. Docblock style: /** @vitest-environment jsdom */. Comment style: // @vitest-environment jsdom.

environment option values

The environment option accepts: 'node' for Node.js environment (default), 'jsdom' for browser-like environment using jsdom package, 'happy-dom' for browser-like environment using happy-dom package, 'edge-runtime' for edge functions environment, or a custom string for custom environments.

environment config option

The environment option specifies which environment will be used for testing. Type: 'node' | 'jsdom' | 'happy-dom' | 'edge-runtime' | string. Default: 'node'. CLI flag: --environment=<env>.

@jest-environment docblock compatibility

For Jest compatibility, Vitest also supports @jest-environment docblock format for specifying per-file environments.

execArgv configuration option

execArgv is a Vitest configuration option with type string[] and default value of an empty array []. It passes additional arguments to node in the runner worker. Refer to Node.js Command-line API documentation for available options. Some options like --prof and --title may crash the worker, so use caution when configuring this option.

exclude config example

Example of configuring exclude in vitest config: ```js import { defineConfig } from 'vitest/config' export default defineConfig({ test: { exclude: [ '**/node_modules/**', '**/dist/**', './temp/**', ], }, }) ```

exclude CLI flag is additive

When using the --exclude flag on the CLI, all glob patterns are added to the config's exclude patterns. This is the only option that doesn't override configuration if provided via CLI flag.

exclude does not affect coverage

The exclude option does not affect coverage reporting. To remove files from coverage reports, use the coverage.exclude option instead.

exclude uses tinyglobby for glob resolution

Vitest uses the tinyglobby package to resolve the glob patterns specified in the exclude option.

exclude option definition

The exclude option is a list of glob patterns that should be excluded from test files. These patterns are resolved relative to the root configuration, which defaults to process.cwd().

exclude config type and default

The exclude option has type string[] with a default value of ['**/node_modules/**', '**/.git/**'].

exclude with configDefaults example

Example of extending default exclude patterns using configDefaults: ```js import { configDefaults, defineConfig } from 'vitest/config' export default defineConfig({ test: { exclude: [ ...configDefaults.exclude, 'packages/template/*', './temp/**', ], }, }) ```

exclude pitfall: config overrides defaults

Manually setting exclude in the config file will replace the default value. To extend rather than replace the default exclude patterns, import and use configDefaults from vitest/config.

exclude CLI usage

The exclude option can be set via CLI using the --exclude flag. Multiple patterns can be added by using multiple --exclude flags, such as: vitest --exclude "**/excluded-file" --exclude "*/other-files/*.js"

expandSnapshotDiff configuration option

expandSnapshotDiff is a boolean configuration option that controls snapshot diff display. It has a type of boolean, a default value of false, and can be set via CLI flags --expandSnapshotDiff or --expand-snapshot-diff. When enabled, it shows the full diff when a snapshot fails instead of displaying only a patch.

expect.requireAssertions concurrent test warning

When running tests with sequence.concurrent and expect.requireAssertions set to true, use local expect from test context instead of the global one to avoid false negatives in some situations.

expect.requireAssertions option

expect.requireAssertions is a boolean option with default value false. When set to true, it calls expect.hasAssertions() at the start of every test, ensuring that no test will pass accidentally. This only works with Vitest's expect; assert or .should assertions will not count and the test will fail due to lack of expect assertions. The value can be changed by calling vi.setConfig({ expect: { requireAssertions: false } }), and this config applies to every subsequent expect call until vi.resetConfig is called manually.

expect.poll.timeout option

expect.poll.timeout is a number option with default value 1000. It specifies the polling timeout in milliseconds for the expect.poll global configuration.

expect.poll.interval option

expect.poll.interval is a number option with default value 50. It specifies the polling interval in milliseconds for the expect.poll global configuration.

experimental.openTelemetry controls OpenTelemetry support

When enabled is set to true, Vitest imports the SDK file in the main thread and before every test file. The sdkPath is resolved relative to the root of the project and should point to a module that exposes a started SDK instance as a default export.

experimental.viteModuleRunner type and default

The experimental.viteModuleRunner option has type boolean with default value true. It controls whether Vitest uses Vite's module runner to run code or falls back to native import. If defined in root config, all projects inherit it automatically. It only works with forks or threads pools.

experimental.openTelemetry type and default

The experimental.openTelemetry option has type OpenTelemetryOptions and default value { enabled: false }. The OpenTelemetryOptions interface has three properties: enabled (required, boolean), sdkPath (optional, string, path to Node.js OpenTelemetry SDK), and browserSdkPath (optional, string, path to browser OpenTelemetry SDK).

experimental.vcsProvider type and default

The experimental.vcsProvider option has type VCSProvider | string with default value 'git'. The VCSProvider interface has one method: findChangedFiles(options: VCSProviderOptions): Promise<string[]>. The VCSProviderOptions interface has two properties: root (required, string) and changedSince (optional, string | boolean).

experimental.nodeLoader type and default

The experimental.nodeLoader option has type boolean with default value true. When module runner is disabled, Vitest uses a native Node.js module loader to transform files to support import.meta.vitest, vi.mock and vi.hoisted. You can disable this to improve performance if these features are not used.

experimental.importDurations type and default

The experimental.importDurations option has type ImportDurationsOptions and default value { print: false, failOnDanger: false, limit: 0, thresholds: { warn: 100, danger: 500 } }. The limit defaults to 10 if print or UI is enabled. The ImportDurationsOptions interface has four properties: print (optional, boolean | 'on-warn'), failOnDanger (optional, boolean), limit (optional, number), and thresholds (optional object with warn and danger number properties).

experimental.importDurations.print type and default

The print property has type boolean | 'on-warn' with default value false. It controls when to print import breakdown to CLI terminal after tests finish: false means never print breakdown, true means always print breakdown, and 'on-warn' means print only when any import exceeds the thresholds.warn value.

experimental.importDurations.failOnDanger type and default

The failOnDanger property has type boolean with default value false. When enabled, it fails the test run if any import exceeds the thresholds.danger value. When the threshold is exceeded, the breakdown is always printed regardless of the print setting.

experimental.importDurations.limit type and default

The limit property has type number with default value 0, or 10 if print, failOnDanger, or UI is enabled. It specifies the maximum number of imports to collect and display in CLI output, Vitest UI, and third-party reporters.

experimental.importDurations.thresholds type and default

The thresholds property has type { warn?: number; danger?: number } with default value { warn: 100, danger: 500 }. The warn threshold is in milliseconds for yellow/warning color (default 100ms), and the danger threshold is in milliseconds for red/danger color and failOnDanger (default 500ms).

experimental.preParse type and default

The experimental.preParse option has type boolean with default value false. When enabled, it parses test specifications before running them, applying the .only modifier, the -t test name pattern, --tags-filter, test lines, and test IDs across all files without executing them.

Give your agent this brain