Vitest · Config reference · all subjects

config

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

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.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.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.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.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.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.

fileParallelism does not affect tests within the same file

The fileParallelism option only controls whether different test files run in parallel. It does not affect how tests within the same file are executed. To run tests concurrently within the same file, use the concurrent option on describe or via config sequence settings.

fileParallelism controls parallel execution of test files

The fileParallelism option determines whether all test files run in parallel. When set to false, it overrides the maxWorkers option to 1.

fileParallelism CLI flags

The fileParallelism option can be set via CLI using --no-file-parallelism or --fileParallelism=false.

fileParallelism type and default

The fileParallelism option has type boolean with a default value of true.

forceRerunTriggers and server.watch.ignored interaction

Files specified in forceRerunTriggers should not be excluded by the server.watch.ignored configuration option, otherwise the rerun triggers will not work as intended.

forceRerunTriggers use case for CLI commands

forceRerunTriggers is useful when testing calling CLI commands, because Vite cannot construct a module graph for external processes like execa('node', ['dist/index.js']). Without this option, Vitest cannot automatically rerun tests when external file content changes.

forceRerunTriggers purpose and behavior

forceRerunTriggers is a glob pattern of file paths that will trigger the whole suite rerun. When paired with the --changed argument, it will run the whole test suite if the trigger is found in the git diff.

forceRerunTriggers config option type and default

forceRerunTriggers is a configuration option with type string[] and default value of ['**/package.json', '**/vitest.config.*', '**/vite.config.*'].

defineCacheKeyGenerator example for opt-out

This example shows how to use defineCacheKeyGenerator to skip caching for modules whose id includes 'do-not-cache', or to vary the cache based on a dynamic environment variable: if (id.includes('do-not-cache')) { return false } or if (sourceCode.includes('myDynamicVar')) { return process.env.DYNAMIC_VAR_VALUE }

fsModuleCache hash computation

Vitest creates a persistent file hash based on file content, its id, Vite's environment configuration, and coverage status. The cache key may become stale if a plugin relies on things outside the file content or public configuration, such as reading another file or folder.

Debug fsModuleCache with environment variable

To debug whether modules are being cached with fsModuleCache enabled, run Vitest with the environment variable DEBUG=vitest:cache:fs. For example: DEBUG=vitest:cache:fs vitest --fsModuleCache

fsModuleCache cache directory location

The fsModuleCache is stored in a single, workspace-wide directory that is shared by every project in the workspace. By default, this cache directory lives in node_modules at the workspace root, which ensures it is naturally invalidated when dependencies are reinstalled. The cache location can be changed using the fsModuleCachePath configuration option, and the cache can be deleted by running vitest --clearCache.

fsModuleCache configuration option

fsModuleCache is a boolean configuration option in Vitest with a default value of false. It can be enabled via CLI using the flags --fsModuleCache or --fsModuleCache=false. When enabled in watch mode, Vitest persists transformed modules on the file system so they can be reused across reruns and separate Vitest processes, instead of discarding the in-memory cache after each test run completes.

Plugin cache key generator for fsModuleCache

Plugin authors can define a cache key generator using defineCacheKeyGenerator to specify dynamic options or opt out of caching for specific modules. If a plugin should not affect the cache key, it can opt out by setting api.vitest.ignoreFsModuleCache to true in the plugin definition.

fsModuleCachePath purpose and behavior

The fsModuleCachePath option specifies the directory where the fsModuleCache is stored. It can be set per project; projects that don't override it fall back to the root's cache directory. By default Vitest stores the cache inside node_modules at the workspace root, based on the package manager's lockfile. Keeping it inside node_modules means the cache is naturally invalidated whenever dependencies are reinstalled.

fsModuleCachePath CLI option

The fsModuleCachePath option can be set via CLI using the flag --fsModuleCachePath=<path>.

fsModuleCachePath type and default value

The fsModuleCachePath option has type string with a default value of 'node_modules/.vitest-cache', resolved from the workspace root.

fsModuleCachePath configuration example

The following example shows how to configure fsModuleCachePath in a Vitest config file: ```ts import { defineConfig } from 'vitest/config' export default defineConfig({ test: { fsModuleCache: true, fsModuleCachePath: 'node_modules/.vitest-cache', }, }) ```

TypeScript globals configuration

To get TypeScript working with global Vitest APIs, add 'vitest/globals' to the types field in tsconfig.json compilerOptions. If you have customized typeRoots in tsconfig.json, you must include node_modules paths alongside your custom types directories to ensure vitest/globals is discoverable.

Enable globals in vitest config

To enable global APIs in Vitest, add globals: true to the test object in the vitest configuration. Example configuration: import { defineConfig } from 'vitest/config'; export default defineConfig({ test: { globals: true, } });

globals config option

The globals configuration option is a boolean that controls whether Vitest provides global APIs. Its type is boolean, and its default value is false. When set to true, it enables global APIs similar to Jest, allowing test APIs to be used without explicit imports. It can be configured via CLI flags --globals, --no-globals, or --globals=false, or by setting globals: true in the test configuration object.

hideSkippedTests option

The hideSkippedTests configuration option is a boolean that controls whether logs for skipped tests are hidden. It can be set via configuration or via the CLI flags --hideSkippedTests or --hide-skipped-tests. The default value is false.

hookTimeout configuration option

hookTimeout is a configuration option that sets the default timeout of a hook in milliseconds. It has type number. The default value is 10000 milliseconds in Node.js and 30000 milliseconds if browser.enabled is true. It can be set via CLI with --hook-timeout=10000 or --hookTimeout=10000. A value of 0 disables the timeout completely.

globalSetup default export function

A global setup file can also export a default function that receives a test project as the first argument and returns a teardown function.

globalSetup onTestsRerun callback

A custom callback can be defined using project.onTestsRerun() to be called when Vitest reruns tests. The test runner will wait for the callback to complete before executing tests. The project parameter cannot be destructured.

globalSetup named exports setup and teardown

A global setup file can export named functions setup and teardown. The setup function receives a test project as the first argument and is called before test workers are created. The teardown function is called after all test files have finished running, or before process exit in watch mode.

globalSetup configuration type and path

The globalSetup configuration option has type string | string[], and specifies the path to global setup files relative to the project root.

globalSetup passing data to tests with provide

Data can be passed from global setup to tests via the project.provide() method and read in tests using inject() imported from vitest. The provide method accepts a key and serializable value.

globalSetup example with provide and ProvidedContext

Example showing how to provide data from globalSetup.ts to tests: export default function setup(project: TestProject) { project.provide('wsPort', 3000) } and declare module 'vitest' { export interface ProvidedContext { wsPort: number } }. In tests, import { inject } from 'vitest' and use inject('wsPort') === 3000.

globalSetup execution context and timing

Global setup is called before test workers are created and only if there is at least one test queued. Global setup runs in a different global scope than tests, so tests do not have access to global variables defined in the setup file.

globalSetup multiple files execution order

Multiple global setup files are possible. Setup and teardown functions are executed sequentially with teardown in reverse order.

includeSource text-based matching warning

Vitest performs a simple text-based inclusion check on source files for the includeSource option. If a file contains import.meta.vitest, even in a comment, it will be matched as an in-source test file.

includeSource config option

includeSource is a configuration option with type string[] and default value of an empty array []. It accepts a list of glob patterns that match in-source test files. These patterns are resolved relative to the root configuration option, which defaults to process.cwd(). When defined, Vitest will run all matched files that have import.meta.vitest inside. Vitest uses the tinyglobby package to resolve the globs.

includeSource example configuration

Example configuration showing includeSource in use: ```js import { defineConfig } from 'vitest/config' export default defineConfig({ test: { includeSource: ['src/**/*.{js,ts}'], }, }) ``` This example configures Vitest to run in-source tests from all JavaScript and TypeScript files in the src directory and its subdirectories.

In-source test file example with import.meta.vitest

Example of writing tests inside a source file using import.meta.vitest: ```ts export function add(...args: number[]) { return args.reduce((a, b) => a + b, 0) } if (import.meta.vitest) { const { it, expect } = import.meta.vitest it('add', () => { expect(add()).toBe(0) expect(add(1)).toBe(1) expect(add(1, 2, 3)).toBe(6) }) } ``` This shows the pattern for embedding tests in source files. For production builds, import.meta.vitest should be replaced with undefined to enable dead code elimination by the bundler.

includeTaskLocation auto-enabled conditions

The includeTaskLocation option is automatically enabled unless explicitly disabled when running Vitest with Vitest UI, Browser Mode without headless mode, or HTML Reporter.

includeTaskLocation config option

includeTaskLocation is a boolean configuration option with a default value of false. It controls whether the location property should be included when Vitest API receives tasks in reporters. The location property contains column and line values that correspond to the test or describe position in the original file. When enabled, it may cause a small performance regression if there are many tests.

include config example for test projects

import { defineConfig } from 'vitest/config' export default defineConfig({ test: { projects: [ { test: { name: 'unit', include: ['./test/unit/*.test.js'], }, }, { test: { name: 'e2e', include: ['./test/e2e/*.test.js'], }, }, ], }, })

include config purpose and glob patterns

The include option takes a list of glob patterns that match test files. These patterns are resolved relative to the root (process.cwd() by default). Vitest uses the tinyglobby package to resolve the globs.

include config CLI usage

The include option can be used from CLI with vitest [...include] or vitest **/*.test.js.

include config option type and default

The include option has type string[] with default value ['**/*.{test,spec}.?(c|m)[jt]s?(x)'].

include config overrides defaults warning

The include option will override Vitest defaults. To extend defaults instead of replacing them, use configDefaults from vitest/config and spread it with ...configDefaults.include.

include config extending defaults example

import { configDefaults, defineConfig } from 'vitest/config' export default defineConfig({ test: { include: [ ...configDefaults.include, './test', './**/*.{test,spec}.ts(x)?', ], }, })

include config and coverage exclude interaction

When using coverage, Vitest automatically adds test files include patterns to coverage's default exclude patterns.

vitest.config file takes priority over vite.config

When a vitest.config.ts file exists, it will have higher priority and will override the configuration from vite.config.ts. This means all options in vite.config will be ignored when vitest.config is present.

mergeConfig function for combining configurations

The mergeConfig function from vitest/config can be used to merge Vite config with Vitest config. This is useful when using a separate vitest.config.js file and extending Vite's options from another config file.

VITEST_SKIP_INSTALL_CHECKS environment variable

Vitest will prompt you to install certain dependencies if they are not already installed. This behavior can be disabled by setting the VITEST_SKIP_INSTALL_CHECKS=1 environment variable.

Type reference for Vitest config in vite.config

When using Vite config, add the triple slash reference types="vitest/config" comment at the top of the vite.config.js file to include Vitest test types.

Config file search order when no --config option provided

When no explicit --config option is provided, Vitest first looks for vitest.config.{ts,mts,cts,js,mjs,cjs}, and then vite.config.{ts,mts,cts,js,mjs,cjs} in the project root. If no config file is found, Vitest will run without one.

Use VITEST environment variable to conditionally apply configuration

The process.env.VITEST variable can be used to conditionally apply different configuration in vite.config.ts. The VITEST variable is set to 'test' by default if not overridden with the --mode option. VITEST is also exposed on import.meta.env in tests.

Supported config file extensions for vitest.config

Vitest supports all conventional JS and TS extensions for vitest.config, including ts, mts, cts, js, mjs, and cjs, but does not support json.

Using vitest/config import for non-Vite projects

If you are not using Vite, import defineConfig from vitest/config to your config file, and add test property to define test options.

configDefaults export from vitest/config

Vitest exports configDefaults from vitest/config that contains default options. These can be retrieved and expanded if needed, such as spreading configDefaults.exclude to extend the default exclusion patterns.

Vitest inherits Vite configuration options

Vitest uses Vite config and supports any configuration option from Vite, such as define for defining global variables or resolve.alias for defining aliases. These Vite options should be defined at the top level, not within the test property.

Give your agent this brain