diff --git a/docs/advanced/pool.md b/docs/advanced/pool.md index a8bc3e7de..f465adf0f 100644 --- a/docs/advanced/pool.md +++ b/docs/advanced/pool.md @@ -49,7 +49,7 @@ export interface ProcessPool { The function is called only once (unless the server config was updated), and it's generally a good idea to initialize everything you need for tests inside that function and reuse it when `runTests` is called. -Vitest calls `runTest` when new tests are scheduled to run. It will not call it if `files` is empty. The first argument is an array of tuples: the first element is a reference to a workspace project and the second one is an absolute path to a test file. Files are sorted using [`sequencer`](/config/#sequence.sequencer) before `runTests` is called. It's possible (but unlikely) to have the same file twice, but it will always have a different project - this is implemented via [`vitest.workspace.ts`](/guide/workspace) configuration. +Vitest calls `runTest` when new tests are scheduled to run. It will not call it if `files` is empty. The first argument is an array of tuples: the first element is a reference to a workspace project and the second one is an absolute path to a test file. Files are sorted using [`sequencer`](/config/#sequence-sequencer) before `runTests` is called. It's possible (but unlikely) to have the same file twice, but it will always have a different project - this is implemented via [`vitest.workspace.ts`](/guide/workspace) configuration. Vitest will wait until `runTests` is executed before finishing a run (i.e., it will emit [`onFinished`](/guide/reporters) only after `runTests` is resolved). diff --git a/docs/api/expect.md b/docs/api/expect.md index 5bf3ac2f4..ecb2284ec 100644 --- a/docs/api/expect.md +++ b/docs/api/expect.md @@ -730,7 +730,7 @@ test('matches snapshot', () => { }) ``` -## toMatchFileSnapshot 0.30.0+ +## toMatchFileSnapshot 0.30.0+ {#tomatchfilesnapshot} - **Type:** `(filepath: string, message?: string) => Promise` @@ -1094,7 +1094,7 @@ test('all assertions are called', async () => { }) ``` ::: warning -When using `assertions` with async concurrent tests, `expect` from the local [Test Context](/guide/test-context.md) must be used to ensure the right test is detected. +When using `assertions` with async concurrent tests, `expect` from the local [Test Context](/guide/test-context) must be used to ensure the right test is detected. ::: ## expect.hasAssertions @@ -1208,7 +1208,7 @@ test('"id" is a number', () => { }) ``` -## expect.closeTo 1.0.0+ +## expect.closeTo 1.0.0+ {#expect-closeto} - **Type:** `(expected: any, precision?: number) => any` @@ -1380,7 +1380,7 @@ test('custom matchers', () => { ``` ::: tip -If you want your matchers to appear in every test, you should call this method inside [`setupFiles`](/config/#setupFiles). +If you want your matchers to appear in every test, you should call this method inside [`setupFiles`](/config/#setupfiles). ::: This function is compatible with Jest's `expect.extend`, so any library that uses it to create custom matchers will work with Vitest. @@ -1406,7 +1406,7 @@ Don't forget to include the ambient declaration file in your `tsconfig.json`. If you want to know more, checkout [guide on extending matchers](/guide/extending-matchers). ::: -## expect.addEqualityTesters 1.2.0+ +## expect.addEqualityTesters 1.2.0+ {#expect-addequalitytesters} - **Type:** `(tester: Array) => void` diff --git a/docs/api/index.md b/docs/api/index.md index 6626041b4..7e2576977 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -82,7 +82,7 @@ test('should work as expected', () => { }) ``` -### test.extend 0.32.3+ +### test.extend 0.32.3+ {#test-extended} - **Alias:** `it.extend` @@ -693,7 +693,7 @@ describe.only.concurrent(/* ... */) // or describe.concurrent.only(/* ... */) describe.todo.concurrent(/* ... */) // or describe.concurrent.todo(/* ... */) ``` -When running concurrent tests, Snapshots and Assertions must use `expect` from the local [Test Context](/guide/test-context.md) to ensure the right test is detected. +When running concurrent tests, Snapshots and Assertions must use `expect` from the local [Test Context](/guide/test-context) to ensure the right test is detected. ```ts describe.concurrent('suite', () => { @@ -871,7 +871,7 @@ afterEach(async () => { Here, the `afterEach` ensures that testing data is cleared after each test runs. ::: tip -Vitest 1.3.0 added [`onTestFinished`](##ontestfinished-1-3-0) hook. You can call it during the test execution to cleanup any state after the test has finished running. +Vitest 1.3.0 added [`onTestFinished`](#ontestfinished) hook. You can call it during the test execution to cleanup any state after the test has finished running. ::: ### beforeAll @@ -936,7 +936,7 @@ Vitest provides a few hooks that you can call _during_ the test execution to cle These hooks will throw an error if they are called outside of the test body. ::: -### onTestFinished 1.3.0+ +### onTestFinished 1.3.0+ {#ontestfinished} This hook is always called after the test has finished running. It is called after `afterEach` hooks since they can influence the test result. It receives a `TaskResult` object with the current test result. diff --git a/docs/api/mock.md b/docs/api/mock.md index 11e8aa04b..39a31738a 100644 --- a/docs/api/mock.md +++ b/docs/api/mock.md @@ -133,7 +133,7 @@ test('async callback', () => { }) ``` -Note that this method takes precedence over the [`mockImplementationOnce`](https://vitest.dev/api/mock.html#mockimplementationonce). +Note that this method takes precedence over the [`mockImplementationOnce`](#mockimplementationonce). ## mockRejectedValue @@ -179,7 +179,7 @@ Does what `mockReset` does and restores inner implementation to the original fun Note that restoring mock from `vi.fn()` will set implementation to an empty function that returns `undefined`. Restoring a `vi.fn(impl)` will restore implementation to `impl`. -If you want this method to be called before each test automatically, you can enable [`restoreMocks`](/config/#restoreMocks) setting in config. +If you want this method to be called before each test automatically, you can enable [`restoreMocks`](/config/#restoremocks) setting in config. ## mockResolvedValue diff --git a/docs/api/vi.md b/docs/api/vi.md index 087871bd5..2c69e58ae 100644 --- a/docs/api/vi.md +++ b/docs/api/vi.md @@ -18,7 +18,7 @@ This section describes the API that you can use when [mocking a module](/guide/m - **Type**: `(path: string, factory?: (importOriginal: () => unknown) => unknown) => void` -Substitutes all imported modules from provided `path` with another module. You can use configured Vite aliases inside a path. The call to `vi.mock` is hoisted, so it doesn't matter where you call it. It will always be executed before all imports. If you need to reference some variables outside of its scope, you can define them inside [`vi.hoisted`](/api/vi#vi-hoisted) and reference them inside `vi.mock`. +Substitutes all imported modules from provided `path` with another module. You can use configured Vite aliases inside a path. The call to `vi.mock` is hoisted, so it doesn't matter where you call it. It will always be executed before all imports. If you need to reference some variables outside of its scope, you can define them inside [`vi.hoisted`](#vi-hoisted) and reference them inside `vi.mock`. ::: warning `vi.mock` works only for modules that were imported with the `import` keyword. It doesn't work with `require`. @@ -29,7 +29,7 @@ Vitest will not mock modules that were imported inside a [setup file](/config/#s ::: ::: warning -The [browser mode](/guide/browser) does not presently support mocking modules. You can track this feature in the GitHub issue. +The [browser mode](/guide/browser) does not presently support mocking modules. You can track this feature in the GitHub [issue](https://github.com/vitest-dev/vitest/issues/3046). ::: If `factory` is defined, all imports will return its result. Vitest calls factory only once and caches results for all subsequent imports until [`vi.unmock`](#vi-unmock) or [`vi.doUnmock`](#vi-dounmock) is called. @@ -386,7 +386,7 @@ Will call [`.mockRestore()`](/api/mock#mockrestore) on all spies. This will clea - **Type:** `(object: T, method: K, accessType?: 'get' | 'set') => MockInstance` -Creates a spy on a method or getter/setter of an object similar to [`vi.fn()`](/#vi-fn). It returns a [mock function](/api/mock). +Creates a spy on a method or getter/setter of an object similar to [`vi.fn()`](#vi-fn). It returns a [mock function](/api/mock). ```ts let apples = 0 @@ -421,7 +421,7 @@ console.log(cart.getApples()) // still 42! ``` ::: -### vi.stubEnv 0.26.0+ +### vi.stubEnv 0.26.0+ {#vi-stubenv} - **Type:** `(name: string, value: string) => Vitest` @@ -449,7 +449,7 @@ import.meta.env.MODE = 'test' ``` ::: -### vi.unstubAllEnvs 0.26.0+ +### vi.unstubAllEnvs 0.26.0+ {#vi-unstuballenvs} - **Type:** `() => Vitest` @@ -507,7 +507,7 @@ window.innerWidth = 100 ``` ::: -### vi.unstubAllGlobals 0.26.0+ +### vi.unstubAllGlobals 0.26.0+ {#vi-unstuballglobals} - **Type:** `() => Vitest` @@ -749,7 +749,7 @@ Since version `0.35.0` `vi.useFakeTimers()` no longer automatically mocks `proce It can still be mocked by specifying the option in `toFake` argument: `vi.useFakeTimers({ toFake: ['nextTick'] })`. ::: -### vi.isFakeTimers 0.34.5+ +### vi.isFakeTimers 0.34.5+ {#vi-isfaketimers} - **Type:** `() => boolean` @@ -765,7 +765,7 @@ When timers are run out, you may call this method to return mocked timers to its A set of useful helper functions that Vitest provides. -### vi.waitFor 0.34.5+ +### vi.waitFor 0.34.5+ {#vi-waitfor} - **Type:** `(callback: WaitForCallback, options?: number | WaitForOptions) => Promise` @@ -824,7 +824,7 @@ test('Element exists in a DOM', async () => { If `vi.useFakeTimers` is used, `vi.waitFor` automatically calls `vi.advanceTimersByTime(interval)` in every check callback. -### vi.waitUntil 0.34.5+ +### vi.waitUntil 0.34.5+ {#vi-waituntil} - **Type:** `(callback: WaitUntilCallback, options?: number | WaitUntilOptions) => Promise` @@ -849,7 +849,7 @@ test('Element render correctly', async () => { }) ``` -### vi.hoisted 0.31.0+ +### vi.hoisted 0.31.0+ {#vi-hoisted} - **Type**: `(factory: () => T) => T` diff --git a/docs/config/index.md b/docs/config/index.md index 8cab34385..b297d11c9 100644 --- a/docs/config/index.md +++ b/docs/config/index.md @@ -55,7 +55,7 @@ Include globs for in-source test files. When defined, Vitest will run all matched files with `import.meta.vitest` inside. -### server 0.34.0+ +### server 0.34.0+ {#server} - **Type:** `{ sourcemap?, deps?, ... }` @@ -134,7 +134,7 @@ Directory to save cache files. Handling for dependencies resolution. -#### deps.optimizer 0.34.0+ +#### deps.optimizer 0.34.0+ {#deps-optimizer} - **Type:** `{ ssr?, web? }` - **See also:** [Dep Optimization Options](https://vitejs.dev/config/dep-optimization-options.html) @@ -148,7 +148,7 @@ When Vitest encounters the external library listed in `include`, it will be bund - Your `alias` configuration is now respected inside bundled packages - Code in your tests is running closer to how it's running in the browser -Be aware that only packages in `deps.optimizer?.[mode].include` option are bundled (some plugins populate this automatically, like Svelte). You can read more about available options in [Vite](https://vitejs.dev/config/dep-optimization-options.html) docs (Vitest doesn't support `disable` and `noDiscovery` options). By default, Vitest uses `optimizer.web` for `jsdom` and `happy-dom` environments, and `optimizer.ssr` for `node` and `edge` environments, but it is configurable by [`transformMode`](#transformmode). +Be aware that only packages in `deps.optimizer?.[mode].include` option are bundled (some plugins populate this automatically, like Svelte). You can read more about available options in [Vite](https://vitejs.dev/config/dep-optimization-options.html) docs (Vitest doesn't support `disable` and `noDiscovery` options). By default, Vitest uses `optimizer.web` for `jsdom` and `happy-dom` environments, and `optimizer.ssr` for `node` and `edge` environments, but it is configurable by [`transformMode`](#testtransformmode). This options also inherits your `optimizeDeps` configuration (for web Vitest will extend `optimizeDeps`, for ssr - `ssr.optimizeDeps`). If you redefine `include`/`exclude` option in `deps.optimizer` it will extend your `optimizeDeps` when running tests. Vitest automatically removes the same options from `include`, if they are listed in `exclude`. @@ -167,7 +167,7 @@ Enable dependency optimization. This option only works with Vite 4.3.2 and higher. ::: -#### deps.web 0.34.2+ +#### deps.web 0.34.2+ {#deps-web} - **Type:** `{ transformAssets?, ... }` @@ -185,7 +185,7 @@ Should Vitest process assets (.png, .svg, .jpg, etc) files and resolve them like This module will have a default export equal to the path to the asset, if no query is specified. ::: warning -At the moment, this option only works with [`vmThreads`](#vmthreads) and [`vmForks`](#vmForks) pools. +At the moment, this option only works with [`vmThreads`](#vmthreads) and [`vmForks`](#vmforks) pools. ::: #### deps.web.transformCss @@ -198,7 +198,7 @@ Should Vitest process CSS (.css, .scss, .sass, etc) files and resolve them like If CSS files are disabled with [`css`](#css) options, this option will just silence `ERR_UNKNOWN_FILE_EXTENSION` errors. ::: warning -At the moment, this option only works with [`vmThreads`](#vmthreads) and [`vmForks`](#vmForks) pools. +At the moment, this option only works with [`vmThreads`](#vmthreads) and [`vmForks`](#vmforks) pools. ::: #### deps.web.transformGlobPattern @@ -211,7 +211,7 @@ Regexp pattern to match external files that should be transformed. By default, files inside `node_modules` are externalized and not transformed, unless it's CSS or an asset, and corresponding option is not disabled. ::: warning -At the moment, this option only works with [`vmThreads`](#vmthreads) and [`vmForks`](#vmForks) pools. +At the moment, this option only works with [`vmThreads`](#vmthreads) and [`vmForks`](#vmforks) pools. ::: #### deps.interopDefault @@ -242,7 +242,7 @@ By default, Vitest assumes you are using a bundler to bypass this and will not f - **Type:** `string[]` - **Default**: `['node_modules']` -A list of directories that should be treated as module directories. This config option affects the behavior of [`vi.mock`](/api/vi#vi-mock): when no factory is provided and the path of what you are mocking matches one of the `moduleDirectories` values, Vitest will try to resolve the mock by looking for a `__mocks__` folder in the [root](/config/#root) of the project. +A list of directories that should be treated as module directories. This config option affects the behavior of [`vi.mock`](/api/vi#vi-mock): when no factory is provided and the path of what you are mocking matches one of the `moduleDirectories` values, Vitest will try to resolve the mock by looking for a `__mocks__` folder in the [root](#root) of the project. This option will also affect if a file should be treated as a module when externalizing dependencies. By default, Vitest imports external modules with native Node.js bypassing Vite transformation step. @@ -417,7 +417,7 @@ test('use jsdom in this test file', () => { }) ``` -If you are running Vitest with [`--isolate=false`](#isolate-1-1-0) flag, your tests will be run in this order: `node`, `jsdom`, `happy-dom`, `edge-runtime`, `custom environments`. Meaning, that every test with the same environment is grouped, but is still running sequentially. +If you are running Vitest with [`--isolate=false`](#isolate) flag, your tests will be run in this order: `node`, `jsdom`, `happy-dom`, `edge-runtime`, `custom environments`. Meaning, that every test with the same environment is grouped, but is still running sequentially. Starting from 0.23.0, you can also define custom environment. When non-builtin environment is used, Vitest will try to load package `vitest-environment-${name}`. That package should export an object with the shape of `Environment`: @@ -484,7 +484,7 @@ export default defineConfig({ }) ``` -### poolMatchGlobs 0.29.4+ +### poolMatchGlobs 0.29.4+ {#poolmatchglobs} - **Type:** `[string, 'threads' | 'forks' | 'vmThreads' | 'vmForks' | 'typescript'][]` - **Default:** `[]` @@ -549,7 +549,7 @@ Custom [reporters](/guide/reporters) for output. Reporters can be [a Reporter in Write test results to a file when the `--reporter=json`, `--reporter=html` or `--reporter=junit` option is also specified. By providing an object instead of a string you can define individual outputs when using multiple reporters. -### pool 1.0.0+ +### pool 1.0.0+ {#pool} - **Type:** `'threads' | 'forks' | 'vmThreads' | 'vmForks'` - **Default:** `'threads'` @@ -595,7 +595,7 @@ Please, be aware of these issues when using this option. Vitest team cannot fix Similar as `vmThreads` pool but uses `child_process` instead of `worker_threads` via [tinypool](https://github.com/tinylibs/tinypool). Communication between tests and the main process is not as fast as with `vmThreads` pool. Process related APIs such as `process.chdir()` are available in `vmForks` pool. Please be aware that this pool has the same pitfalls listed in `vmThreads`. -### poolOptions 1.0.0+ +### poolOptions 1.0.0+ {#pooloptions} - **Type:** `Record<'threads' | 'forks' | 'vmThreads' | 'vmForks', {}>` - **Default:** `{}` @@ -637,7 +637,7 @@ Minimum number of threads. You can also use `VITEST_MIN_THREADS` environment var - **Type:** `boolean` - **Default:** `false` -Run all tests with the same environment inside a single worker thread. This will disable built-in module isolation (your source code or [inlined](#deps-inline) code will still be reevaluated for each test), but can improve test performance. +Run all tests with the same environment inside a single worker thread. This will disable built-in module isolation (your source code or [inlined](#server-deps-inline) code will still be reevaluated for each test), but can improve test performance. :::warning Even though this option will force tests to run one after another, this option is different from Jest's `--runInBand`. Vitest uses workers not only for running tests in parallel, but also to provide isolation. By disabling this option, your tests will run sequentially, but in the same global context, so you must provide isolation yourself. @@ -716,7 +716,7 @@ Isolate environment for each test file. - **Type:** `boolean` - **Default:** `false` -Run all tests with the same environment inside a single child process. This will disable built-in module isolation (your source code or [inlined](#deps-inline) code will still be reevaluated for each test), but can improve test performance. +Run all tests with the same environment inside a single child process. This will disable built-in module isolation (your source code or [inlined](#server-deps-inline) code will still be reevaluated for each test), but can improve test performance. :::warning Even though this option will force tests to run one after another, this option is different from Jest's `--runInBand`. Vitest uses child processes not only for running tests in parallel, but also to provide isolation. By disabling this option, your tests will run sequentially, but in the same global context, so you must provide isolation yourself. @@ -866,7 +866,7 @@ Pass additional arguments to `node` process in the VM context. See [Command-line Be careful when using, it as some options may crash worker, e.g. --prof, --title. See https://github.com/nodejs/node/issues/41103. ::: -### fileParallelism 1.1.0+ +### fileParallelism 1.1.0+ {#fileparallelism} - **Type:** `boolean` - **Default:** `true` @@ -878,13 +878,13 @@ Should all test files run in parallel. Setting this to `false` will override `ma This option doesn't affect tests running in the same file. If you want to run those in parallel, use `concurrent` option on [describe](/api/#describe-concurrent) or via [a config](#sequence-concurrent). ::: -### maxWorkers 1.1.0+ +### maxWorkers 1.1.0+ {#maxworkers} - **Type:** `number` Maximum number of workers to run tests in. `poolOptions.{threads,vmThreads}.maxThreads`/`poolOptions.forks.maxForks` has higher priority. -### minWorkers 1.1.0+ +### minWorkers 1.1.0+ {#minworkers} - **Type:** `number` @@ -935,7 +935,7 @@ Changing setup files will trigger rerun of all tests. You can use `process.env.VITEST_POOL_ID` (integer-like string) inside to distinguish between threads. :::tip -Note, that if you are running [`--isolate=false`](#isolate-1-1-0), this setup file will be run in the same global scope multiple times. Meaning, that you are accessing the same global object before each test, so make sure you are not doing the same thing more than you need. +Note, that if you are running [`--isolate=false`](#isolate), this setup file will be run in the same global scope multiple times. Meaning, that you are accessing the same global object before each test, so make sure you are not doing the same thing more than you need. ::: For example, you may rely on a global variable: @@ -1185,7 +1185,7 @@ Since Vitest 1.2.0, you can also pass custom coverage reporters. See [Guide - Cu Since Vitest 0.31.0, you can check your coverage report in Vitest UI: check [Vitest UI Coverage](/guide/coverage#vitest-ui) for more details. -#### coverage.reportOnFailure 0.31.2+ +#### coverage.reportOnFailure 0.31.2+ {#coverage-reportonfailure} - **Type:** `boolean` - **Default:** `false` (since Vitest `0.34.0`) @@ -1201,7 +1201,7 @@ Generate coverage report even when tests fail. - **Available for providers:** `'v8' | 'istanbul'` - **CLI:** `--coverage.allowExternal`, `--coverage.allowExternal=false` -Collect coverage of files outside the [project `root`](https://vitest.dev/config/#root). +Collect coverage of files outside the [project `root`](#root). #### coverage.skipFull @@ -1410,13 +1410,13 @@ Open Vitest UI (WIP) Listen to port and serve API. When set to true, the default port is 51204 -### browser 0.29.4+ +### browser 0.29.4+ {#browser} - **Type:** `{ enabled?, name?, provider?, headless?, api?, slowHijackESM? }` - **Default:** `{ enabled: false, headless: process.env.CI, api: 63315 }` - **CLI:** `--browser`, `--browser=`, `--browser.name=chrome --browser.headless` -Run Vitest tests in a browser. We use [WebdriverIO](https://webdriver.io/) for running tests by default, but it can be configured with [browser.provider](/config/#browser-provider) option. +Run Vitest tests in a browser. We use [WebdriverIO](https://webdriver.io/) for running tests by default, but it can be configured with [browser.provider](#browser-provider) option. ::: tip NOTE Read more about testing in a real browser in the [guide page](/guide/browser). @@ -1432,7 +1432,7 @@ This is an experimental feature. Breaking changes might not follow SemVer, pleas - **Default:** `false` - **CLI:** `--browser`, `--browser.enabled=false` -Run all tests inside a browser by default. Can be overridden with [`poolMatchGlobs`](/config/#poolmatchglobs) option. +Run all tests inside a browser by default. Can be overridden with [`poolMatchGlobs`](#poolmatchglobs) option. #### browser.name @@ -1461,10 +1461,10 @@ Run the browser in a `headless` mode. If you are running Vitest in CI, it will b Run every test in a separate iframe. -### browser.fileParallelism 1.3.0+ +### browser.fileParallelism 1.3.0+ {#browser-fileparallelism} - **Type:** `boolean` -- **Default:** the same as [`fileParallelism`](#fileparallelism-110) +- **Default:** the same as [`fileParallelism`](#fileparallelism) - **CLI:** `--browser.fileParallelism=false` Create all test iframes at the same time so they are running in parallel. @@ -1472,7 +1472,7 @@ Create all test iframes at the same time so they are running in parallel. This makes it impossible to use interactive APIs (like clicking or hovering) because there are several iframes on the screen at the same time, but if your tests don't rely on those APIs, it might be much faster to just run all of them at the same time. ::: tip -If you disabled isolation via [`browser.isolate=false`](#browserisolate), your test files will still run one after another because of the nature of the test runner. +If you disabled isolation via [`browser.isolate=false`](#browser-isolate), your test files will still run one after another because of the nature of the test runner. ::: #### browser.api @@ -1481,7 +1481,7 @@ If you disabled isolation via [`browser.isolate=false`](#browserisolate), your t - **Default:** `63315` - **CLI:** `--browser.api=63315`, `--browser.api.port=1234, --browser.api.host=example.com` -Configure options for Vite server that serves code in the browser. Does not affect [`test.api`](/config/#api) option. +Configure options for Vite server that serves code in the browser. Does not affect [`test.api`](#api) option. #### browser.provider @@ -1502,10 +1502,10 @@ export interface BrowserProvider { ``` ::: warning -This is an advanced API for library authors. If you just need to run tests in a browser, use the [browser](/config/#browser) option. +This is an advanced API for library authors. If you just need to run tests in a browser, use the [browser](#browser) option. ::: -#### browser.providerOptions 1.0.0+ +#### browser.providerOptions 1.0.0+ {#browser-provideroptions} - **Type:** `BrowserProviderOptions` @@ -1540,7 +1540,7 @@ To have a better type safety when using built-in providers, you can add one of t ``` ::: -#### browser.slowHijackESM 0.31.0+ +#### browser.slowHijackESM 0.31.0+ {#browser-slowhijackesm} - **Type:** `boolean` - **Default:** `false` @@ -1572,21 +1572,21 @@ Will call [`.mockReset()`](/api/mock#mockreset) on all spies before each test. T Will call [`.mockRestore()`](/api/mock#mockrestore) on all spies before each test. This will clear mock history and reset its implementation to the original one. -### unstubEnvs 0.26.0+ +### unstubEnvs 0.26.0+ {#unstubenvs} - **Type:** `boolean` - **Default:** `false` Will call [`vi.unstubAllEnvs`](/api/vi#vi-unstuballenvs) before each test. -### unstubGlobals 0.26.0+ +### unstubGlobals 0.26.0+ {#unstubglobals} - **Type:** `boolean` - **Default:** `false` Will call [`vi.unstubAllGlobals`](/api/vi#vi-unstuballglobals) before each test. -### testTransformMode 0.34.0+ +### testTransformMode 0.34.0+ {#testtransformmode} - **Type:** `{ web?, ssr? }` @@ -1617,10 +1617,10 @@ Format options for snapshot testing. These options are passed down to [`pretty-f ::: tip Beware that `plugins` field on this object will be ignored. -If you need to extend snapshot serializer via pretty-format plugins, please, use [`expect.addSnapshotSerializer`](/api/expect#expect-addsnapshotserializer) API or [snapshotSerializers](#snapshotserializers-1-3-0) option. +If you need to extend snapshot serializer via pretty-format plugins, please, use [`expect.addSnapshotSerializer`](/api/expect#expect-addsnapshotserializer) API or [snapshotSerializers](#snapshotserializers) option. ::: -### snapshotSerializers 1.3.0+ +### snapshotSerializers 1.3.0+ {#snapshotserializers} - **Type:** `string[]` - **Default:** `[]` @@ -1776,7 +1776,7 @@ If you want tests to run randomly, you can enable it with this option, or CLI ar Vitest usually uses cache to sort tests, so long running tests start earlier - this makes tests run faster. If your tests will run in random order you will lose this performance improvement, but it may be useful to track tests that accidentally depend on another run previously. -#### sequence.concurrent 0.32.2+ +#### sequence.concurrent 0.32.2+ {#sequence-concurrent} - **Type**: `boolean` - **Default**: `false` @@ -1804,7 +1804,7 @@ Changes the order in which hooks are executed. - `list` will order all hooks in the order they are defined - `parallel` will run hooks in a single group in parallel (hooks in parent suites will still run before the current suite's hooks) -#### sequence.setupFiles 0.29.3+ +#### sequence.setupFiles 0.29.3+ {#sequence-setupfiles} - **Type**: `'list' | 'parallel'` - **Default**: `'parallel'` @@ -1819,7 +1819,7 @@ Changes the order in which setup files are executed. Options for configuring [typechecking](/guide/testing-types) test environment. -#### typecheck.enabled 1.0.0+ +#### typecheck.enabled 1.0.0+ {#typecheck-enabled} - **Type**: `boolean` - **Default**: `false` @@ -1827,7 +1827,7 @@ Options for configuring [typechecking](/guide/testing-types) test environment. Enable typechecking alongside your regular tests. -#### typecheck.only 1.0.0+ +#### typecheck.only 1.0.0+ {#typecheck-only} - **Type**: `boolean` - **Default**: `false` @@ -1894,7 +1894,7 @@ Path to custom tsconfig, relative to the project root. The number of milliseconds after which a test is considered slow and reported as such in the results. -### chaiConfig 0.30.0+ +### chaiConfig 0.30.0+ {#chaiconfig} - **Type:** `{ includeStack?, showDiff?, truncateThreshold? }` - **Default:** `{ includeStack: false, showDiff: true, truncateThreshold: 40 }` @@ -1924,7 +1924,7 @@ Sets length threshold for actual and expected values in assertion errors. If thi This config option affects truncating values in `test.each` titles and inside the assertion error message. -### bail 0.31.0+ +### bail 0.31.0+ {#bail} - **Type:** `number` - **Default:** `0` @@ -1934,7 +1934,7 @@ Stop test execution when given number of tests have failed. By default Vitest will run all of your test cases even if some of them fail. This may not be desired for CI builds where you are only interested in 100% successful builds and would like to stop test execution as early as possible when test failures occur. The `bail` option can be used to speed up CI runs by preventing it from running more tests when failures have occurred. -### retry 0.32.3+ +### retry 0.32.3+ {#retry} - **Type:** `number` - **Default:** `0` @@ -1963,7 +1963,7 @@ export default defineConfig({ }) ``` -### onStackTrace 1.0.0+ +### onStackTrace 1.0.0+ {#onstacktrace} - **Type**: `(error: Error, frame: ParsedStack) => boolean | void` @@ -1990,7 +1990,7 @@ export default defineConfig({ }) ``` -### diff 0.34.5+ +### diff 0.34.5+ {#diff} - **Type:** `string` - **CLI:** `--diff=` @@ -2071,7 +2071,7 @@ Relevant only when using with `shouldAdvanceTime: true`. increment mocked time b Tells fake timers to clear "native" (i.e. not fake) timers by delegating to their respective handlers. These are not cleared by default, leading to potentially unexpected behavior if timers existed prior to starting fake timers session. -### workspace 1.1.0+ +### workspace 1.1.0+ {#workspace} - **Type:** `string` - **CLI:** `--workspace=./file.js` @@ -2079,7 +2079,7 @@ Tells fake timers to clear "native" (i.e. not fake) timers by delegating to thei Path to a [workspace](/guide/workspace) config file relative to [root](#root). -### isolate 1.1.0+ +### isolate 1.1.0+ {#isolate} - **Type:** `boolean` - **Default:** `true` diff --git a/docs/guide/browser.md b/docs/guide/browser.md index dc527db31..316d783c5 100644 --- a/docs/guide/browser.md +++ b/docs/guide/browser.md @@ -2,7 +2,7 @@ title: Browser Mode | Guide --- -# Browser Mode Experimental +# Browser Mode Experimental {#browser-mode} This page provides information about the experimental browser mode feature in the Vitest API, which allows you to run your tests in the browser natively, providing access to browser globals like window and document. This feature is currently under development, and APIs may change in the future. diff --git a/docs/guide/common-errors.md b/docs/guide/common-errors.md index dde26b2d4..5831dbae0 100644 --- a/docs/guide/common-errors.md +++ b/docs/guide/common-errors.md @@ -61,7 +61,7 @@ vi.resetModules() ## Failed to terminate worker -This error can happen when NodeJS's `fetch` is used with default [`pool: 'threads'`](/config/#pool-1-0-0). This issue is tracked on issue [Timeout abort can leave process(es) running in the background #3077](https://github.com/vitest-dev/vitest/issues/3077). +This error can happen when NodeJS's `fetch` is used with default [`pool: 'threads'`](/config/#threads). This issue is tracked on issue [Timeout abort can leave process(es) running in the background #3077](https://github.com/vitest-dev/vitest/issues/3077). As work-around you can switch to [`pool: 'forks'`](/config/#forks) or [`pool: 'vmForks'`](/config/#vmforks). diff --git a/docs/guide/coverage.md b/docs/guide/coverage.md index 72447aba6..f81fbbb4e 100644 --- a/docs/guide/coverage.md +++ b/docs/guide/coverage.md @@ -216,7 +216,7 @@ To see all configurable options for coverage, see the [coverage Config Reference ## Vitest UI -Since Vitest 0.31.0, you can check your coverage report in [Vitest UI](./ui). +Since Vitest 0.31.0, you can check your coverage report in [Vitest UI](/guide/ui). Vitest UI will enable coverage report when it is enabled explicitly and the html coverage reporter is present, otherwise it will not be available: - enable `coverage.enabled=true` in your configuration or run Vitest with `--coverage.enabled=true` flag diff --git a/docs/guide/features.md b/docs/guide/features.md index 80069e641..d44a9c381 100644 --- a/docs/guide/features.md +++ b/docs/guide/features.md @@ -32,9 +32,9 @@ Out-of-the-box ES Module / TypeScript / JSX support / PostCSS ## Threads -By default Vitest runs test files in multiple threads using [`node:worker_threads`](https://nodejs.org/api/worker_threads.html) via [Tinypool](https://github.com/tinylibs/tinypool) (a lightweight fork of [Piscina](https://github.com/piscinajs/piscina)), allowing tests to run simultaneously. If your tests are running code that is not compatible with multi-threading, you can switch to [`--pool=forks`](/config/#pool-1-0-0) which runs tests in multiple processes using [`node:child_process`](https://nodejs.org/api/child_process.html) via Tinypool. +By default Vitest runs test files in multiple threads using [`node:worker_threads`](https://nodejs.org/api/worker_threads.html) via [Tinypool](https://github.com/tinylibs/tinypool) (a lightweight fork of [Piscina](https://github.com/piscinajs/piscina)), allowing tests to run simultaneously. If your tests are running code that is not compatible with multi-threading, you can switch to [`--pool=forks`](/config/#pool) which runs tests in multiple processes using [`node:child_process`](https://nodejs.org/api/child_process.html) via Tinypool. -To run tests in a single thread or process, see [`poolOptions`](/config/#pooloptions-1-0-0). +To run tests in a single thread or process, see [`poolOptions`](/config/#pooloptions). Vitest also isolates each file's environment so env mutations in one file don't affect others. Isolation can be disabled by passing `--no-isolate` to the CLI (trading correctness for run performance). @@ -42,7 +42,7 @@ Vitest also isolates each file's environment so env mutations in one file don't Vitest provided many ways to narrow down the tests to run in order to speed up testing so you can focus on development. -Learn more about [Test Filtering](./filtering.md). +Learn more about [Test Filtering](/guide/filtering). ## Running Tests Concurrently @@ -75,7 +75,7 @@ describe.concurrent('suite', () => { You can also use `.skip`, `.only`, and `.todo` with concurrent suites and tests. Read more in the [API Reference](/api/#test-concurrent). ::: warning -When running concurrent tests, Snapshots and Assertions must use `expect` from the local [Test Context](/guide/test-context.md) to ensure the right test is detected. +When running concurrent tests, Snapshots and Assertions must use `expect` from the local [Test Context](/guide/test-context) to ensure the right test is detected. ::: ## Snapshot @@ -185,7 +185,7 @@ if (import.meta.vitest) { Learn more at [In-source testing](/guide/in-source). -## Benchmarking Experimental +## Benchmarking Experimental {#benchmarking} Since Vitest 0.23.0, you can run benchmark tests with [`bench`](/api/#bench) function via [Tinybench](https://github.com/tinylibs/tinybench) to compare performance results. @@ -210,7 +210,7 @@ describe('sort', () => { }) ``` -## Type Testing Experimental +## Type Testing Experimental {#type-testing} Since Vitest 0.25.0 you can [write tests](/guide/testing-types) to catch type regressions. Vitest comes with [`expect-type`](https://github.com/mmkal/expect-type) package to provide you with a similar and easy to understand API. diff --git a/docs/guide/ide.md b/docs/guide/ide.md index 33fc2c099..0a9cb35dc 100644 --- a/docs/guide/ide.md +++ b/docs/guide/ide.md @@ -4,7 +4,7 @@ title: IDE Integrations | Guide # IDE Integrations -## VS Code Official +## VS Code Official {#vs-code}

diff --git a/docs/guide/improving-performance.md b/docs/guide/improving-performance.md index f12446eb3..1ef6066ad 100644 --- a/docs/guide/improving-performance.md +++ b/docs/guide/improving-performance.md @@ -33,7 +33,7 @@ export default defineConfig({ If you are using `vmThreads` pool, you cannot disable isolation. Use `threads` pool instead to improve your tests performance. ::: -For some projects, it might also be desirable to disable parallelism to improve startup time. To do that, provide `--no-file-parallelism` flag to the CLI or set [`test.fileParallelism`](/config/#fileParallelism) property in the config to `false`. +For some projects, it might also be desirable to disable parallelism to improve startup time. To do that, provide `--no-file-parallelism` flag to the CLI or set [`test.fileParallelism`](/config/#fileparallelism) property in the config to `false`. ::: code-group ```bash [CLI] diff --git a/docs/guide/in-source.md b/docs/guide/in-source.md index 3360823a3..0c3a8f1d1 100644 --- a/docs/guide/in-source.md +++ b/docs/guide/in-source.md @@ -87,7 +87,7 @@ export default defineBuildConfig({ }) ``` -Learn more: unbuild +Learn more: [unbuild](https://github.com/unjs/unbuild) @@ -108,7 +108,7 @@ export default { } ``` -Learn more: Rollup +Learn more: [Rollup](https://rollupjs.org/) diff --git a/docs/guide/index.md b/docs/guide/index.md index 0d95293de..f3f549195 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -8,7 +8,7 @@ title: Getting Started | Guide Vitest is a next generation testing framework powered by Vite. -You can learn more about the rationale behind the project in the [Why Vitest](./why) section. +You can learn more about the rationale behind the project in the [Why Vitest](/guide/why) section. ## Trying Vitest Online @@ -209,7 +209,7 @@ In a project where Vitest is installed, you can use the `vitest` binary in your To run tests once without watching for file changes, use `vitest run`. You can specify additional CLI options like `--port` or `--https`. For a full list of CLI options, run `npx vitest --help` in your project. -Learn more about the [Command Line Interface](./cli.md) +Learn more about the [Command Line Interface](/guide/cli) ## IDE Integrations @@ -217,7 +217,7 @@ We also provided a official extension for Visual Studio Code to enhance your tes [Install from VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=ZixuanChen.vitest-explorer) -Learn more about [IDE Integrations](./ide.md) +Learn more about [IDE Integrations](/guide/ide) ## Examples diff --git a/docs/guide/migration.md b/docs/guide/migration.md index c879c5513..8f9173906 100644 --- a/docs/guide/migration.md +++ b/docs/guide/migration.md @@ -202,7 +202,7 @@ Just like Jest, Vitest sets `NODE_ENV` to `test`, if it wasn't set before. Vites ### Replace property -If you want to modify the object, you will use [replaceProperty API](https://jestjs.io/docs/jest-object#jestreplacepropertyobject-propertykey-value) in Jest, you can use [`vi.stubEnv`](https://vitest.dev/api/vi.html#vi-stubenv) or [`vi.spyOn`](/api/vi#vi-spyon) to do the same also in Vitest. +If you want to modify the object, you will use [replaceProperty API](https://jestjs.io/docs/jest-object#jestreplacepropertyobject-propertykey-value) in Jest, you can use [`vi.stubEnv`](/api/#vi-stubenv) or [`vi.spyOn`](/api/vi#vi-spyon) to do the same also in Vitest. ### Done Callback diff --git a/docs/guide/mocking.md b/docs/guide/mocking.md index e40b9b108..60d4dce64 100644 --- a/docs/guide/mocking.md +++ b/docs/guide/mocking.md @@ -663,7 +663,7 @@ it('changes value', () => { }) ``` -If you want to automatically reset value, you can use `vi.stubEnv` helper with [`unstubEnvs`](/config/#unstubEnvs) config option enabled (or call [`vi.unstubAllEnvs`](/api/vi#vi-unstuballenvs) manually in `beforeEach` hook): +If you want to automatically reset value, you can use `vi.stubEnv` helper with [`unstubEnvs`](/config/#unstubenvs) config option enabled (or call [`vi.unstubAllEnvs`](/api/vi#vi-unstuballenvs) manually in `beforeEach` hook): ```ts import { expect, it, vi } from 'vitest' diff --git a/docs/guide/reporters.md b/docs/guide/reporters.md index b69b73fb8..ca4e19ec8 100644 --- a/docs/guide/reporters.md +++ b/docs/guide/reporters.md @@ -444,7 +444,7 @@ export default defineConfig({ ``` ::: -### Github Actions Reporter 1.3.0+ +### Github Actions Reporter 1.3.0+ {#github-actions-reporter} Output [workflow commands](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message) to provide annotations for test failures. This reporter is automatically enabled with a [`default`](#default-reporter) reporter when `process.env.GITHUB_ACTIONS === 'true'`. diff --git a/docs/guide/snapshot.md b/docs/guide/snapshot.md index 727ad8c99..93fd933d5 100644 --- a/docs/guide/snapshot.md +++ b/docs/guide/snapshot.md @@ -34,7 +34,7 @@ exports['toUpperCase 1'] = '"FOOBAR"' The snapshot artifact should be committed alongside code changes, and reviewed as part of your code review process. On subsequent test runs, Vitest will compare the rendered output with the previous snapshot. If they match, the test will pass. If they don't match, either the test runner found a bug in your code that should be fixed, or the implementation has changed and the snapshot needs to be updated. ::: warning -When using Snapshots with async concurrent tests, `expect` from the local [Test Context](/guide/test-context.md) must be used to ensure the right test is detected. +When using Snapshots with async concurrent tests, `expect` from the local [Test Context](/guide/test-context) must be used to ensure the right test is detected. ::: ## Inline Snapshots @@ -64,7 +64,7 @@ it('toUpperCase', () => { This allows you to see the expected output directly without jumping across different files. ::: warning -When using Snapshots with async concurrent tests, `expect` from the local [Test Context](/guide/test-context.md) must be used to ensure the right test is detected. +When using Snapshots with async concurrent tests, `expect` from the local [Test Context](/guide/test-context) must be used to ensure the right test is detected. ::: ## Updating Snapshots @@ -137,7 +137,7 @@ expect.addSnapshotSerializer({ }) ``` -We also support [snapshotSerializers](/config/#snapshotserializers-1-3-0) option to implicitly add custom serializers. +We also support [snapshotSerializers](/config/#snapshotserializers) option to implicitly add custom serializers. ```ts import { SnapshotSerializer } from 'vitest'