From 92a531efd418763d8d6496f981964b89f59a6c58 Mon Sep 17 00:00:00 2001 From: Vladimir Date: Fri, 10 Apr 2026 06:11:47 +0200 Subject: [PATCH] docs: expand test filtering and parallelism docs (#10116) --- docs/guide/filtering.md | 165 ++++++++++++++++++++------------------ docs/guide/parallelism.md | 68 +++++++++++++--- 2 files changed, 146 insertions(+), 87 deletions(-) diff --git a/docs/guide/filtering.md b/docs/guide/filtering.md index 56fa545dd..3c7501dcf 100644 --- a/docs/guide/filtering.md +++ b/docs/guide/filtering.md @@ -4,17 +4,35 @@ title: Test Filtering | Guide # Test Filtering -Filtering, timeouts, concurrent for suite and tests +As your test suite grows, running every test on every change becomes slow and distracting. If you're fixing a bug in a single module, you don't need to wait for hundreds of unrelated tests to finish. Test filtering lets you narrow down which tests run so you can stay focused on the code you're actively working on. -## CLI +Vitest offers several ways to filter tests: from the command line, inside your test files, and through tags. Each approach is useful in different situations. -You can use CLI to filter test files by name: +::: tip Performance Note +Filters like `-t`, `--tags-filter`, `.only`, and `.skip` are applied *per test file* — Vitest still has to run each test file to discover which tests match. In a large project, this overhead adds up even if only a few tests actually execute. + +To avoid this, always pass a file path alongside your filter so Vitest only loads the files you care about: ```bash -$ vitest basic +vitest utils.test.ts -t "handles empty input" ``` -Will only execute test files that contain `basic`, e.g. +Alternatively, you can use the [`--experimental.preParse`](/config/experimental#experimental-preparse) flag, which parses test files to discover test names without fully executing them: + +```bash +vitest --experimental.preParse -t "handles empty input" +``` +::: + +## Filtering by File Name + +The simplest way to run a subset of tests is to pass a filename pattern as a CLI argument. Vitest will only run test files whose path contains the given string: + +```bash +vitest basic +``` + +This matches any test file with `basic` in its path: ``` basic.test.ts @@ -22,76 +40,52 @@ basic-foo.test.ts basic/foo.test.ts ``` -You can also use the `-t, --testNamePattern ` option to filter tests by full name. This can be helpful when you want to filter by the name defined within a file rather than the filename itself. - -Since Vitest 3, you can also specify the test by filename and line number: +This is useful when you know which file you need to work on and want to skip everything else. -```bash -$ vitest basic/foo.test.ts:10 -``` +## Filtering by Test Name -::: warning -Note that Vitest requires the full filename for this feature to work. It can be relative to the current working directory or an absolute file path. +Sometimes the test you care about is buried in a file with many other tests. The `-t` (or `--testNamePattern`) option filters by the test's name rather than the filename. It accepts a regex pattern and matches against the full test name, which includes any `describe` block names: ```bash -$ vitest basic/foo.js:10 # ✅ -$ vitest ./basic/foo.js:10 # ✅ -$ vitest /users/project/basic/foo.js:10 # ✅ -$ vitest foo:10 # ❌ -$ vitest ./basic/foo:10 # ❌ +vitest -t "handles empty input" ``` -At the moment Vitest also doesn't support ranges: +You can combine this with a file filter to narrow things down further: ```bash -$ vitest basic/foo.test.ts:10, basic/foo.test.ts:25 # ✅ -$ vitest basic/foo.test.ts:10-25 # ❌ +vitest utils -t "handles empty input" ``` -::: -## Specifying a Timeout +This runs only tests whose name matches `"handles empty input"` inside files matching `utils`. -You can optionally pass a timeout in milliseconds as a third argument to tests. The default is [5 seconds](/config/testtimeout). +## Filtering by Line Number -```ts -import { test } from 'vitest' +When you're looking at a specific test in your editor, you often just want to run *that one test*. You can point directly to a line number: -test('name', async () => { /* ... */ }, 1000) +```bash +vitest basic/foo.test.ts:10 ``` -Hooks also can receive a timeout, with the same 5 seconds default. - -```ts -import { beforeAll } from 'vitest' +Vitest will run the test that contains line 10. This requires the full filename (relative or absolute): -beforeAll(async () => { /* ... */ }, 1000) +```bash +vitest basic/foo.test.ts:10 # ✅ +vitest ./basic/foo.test.ts:10 # ✅ +vitest /users/project/basic/foo.test.ts:10 # ✅ +vitest foo:10 # ❌ partial name won't work +vitest ./basic/foo:10 # ❌ missing file extension ``` -## Skipping Suites and Tests - -Use `.skip` to avoid running certain suites or tests - -```ts -import { assert, describe, it } from 'vitest' - -describe.skip('skipped suite', () => { - it('test', () => { - // Suite skipped, no error - assert.equal(Math.sqrt(4), 3) - }) -}) +To run multiple specific tests, separate them with spaces: -describe('suite', () => { - it.skip('skipped test', () => { - // Test skipped, no error - assert.equal(Math.sqrt(4), 3) - }) -}) +```bash +vitest basic/foo.test.ts:10 basic/foo.test.ts:25 # ✅ +vitest basic/foo.test.ts:10-25 # ❌ ranges are not supported ``` -## Filtering Tags +## Filtering by Tags -If your test defines a [tag](/guide/test-tags), you can filter your tests with a `--tags-filter` option: +For larger projects, you may want to categorize tests and run them by category. [Tags](/guide/test-tags) let you label tests and then filter by those labels from the CLI: ```ts test('renders a form', { tags: ['frontend'] }, () => { @@ -103,66 +97,83 @@ test('calls an external API', { tags: ['backend'] }, () => { }) ``` -```shell +```bash vitest --tags-filter=frontend ``` -## Selecting Suites and Tests to Run +This is particularly helpful in CI pipelines where you might want to run frontend and backend tests in separate jobs, or skip slow integration tests during quick checks. + +## Focusing on Specific Tests with `.only` -Use `.only` to only run certain suites or tests +When you're debugging a failing test, you want to run just that test without modifying CLI arguments every time. Adding `.only` to a test or suite tells Vitest to skip everything else in the file: ```ts -import { assert, describe, it } from 'vitest' +import { describe, expect, it } from 'vitest' -// Only this suite (and others marked with only) are run describe.only('suite', () => { it('test', () => { - assert.equal(Math.sqrt(4), 3) + // This runs because the suite is marked with .only + expect(Math.sqrt(4)).toBe(2) }) }) describe('another suite', () => { it('skipped test', () => { - // Test skipped, as tests are running in Only mode - assert.equal(Math.sqrt(4), 3) + // This does not run + expect(Math.sqrt(4)).toBe(2) }) - it.only('test', () => { - // Only this test (and others marked with only) are run - assert.equal(Math.sqrt(4), 2) + it.only('focused test', () => { + // This also runs because it is marked with .only + expect(Math.sqrt(4)).toBe(2) }) }) ``` -Run Vitest with a file filter and a line number: +You can use `.only` on both `describe` blocks and individual tests. When any test or suite in a file is marked with `.only`, all unmarked tests in that file are skipped. -```shell -vitest ./test/example.test.ts:5 -``` +::: warning +Remember to remove `.only` before committing. By default, Vitest will fail the entire test run if it encounters `.only` in CI (when `process.env.CI` is set), preventing you from accidentally skipping tests in your pipeline. This behavior is controlled by the [`allowOnly`](/config/allowonly) option. + +To catch `.only` even earlier, the [`no-focused-tests`](https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/no-focused-tests.md) ESLint rule (also available in [oxlint](https://oxc.rs/docs/guide/usage/linter/rules/jest/no-focused-tests.html)) can flag it in your editor before you commit. +::: -```ts:line-numbers -import { assert, describe, it } from 'vitest' +## Skipping Tests with `.skip` -describe('suite', () => { - // Run only this test +The opposite of `.only` is `.skip`. Use it to temporarily disable a test or suite without deleting it. Skipped tests still show up in the report so you don't forget about them: + +```ts +import { describe, expect, it } from 'vitest' + +describe.skip('skipped suite', () => { it('test', () => { - assert.equal(Math.sqrt(4), 3) + // This entire suite is skipped + expect(Math.sqrt(4)).toBe(2) + }) +}) + +describe('suite', () => { + it.skip('skipped test', () => { + // Just this one test is skipped + expect(Math.sqrt(4)).toBe(2) }) }) ``` -## Unimplemented Suites and Tests +This is useful when a test is flaky or depends on an external service that's temporarily down. It lets you keep the test in place as a reminder while unblocking the rest of the suite. + +## Placeholder Tests with `.todo` -Use `.todo` to stub suites and tests that should be implemented +When planning new features, you might know what tests you'll need before you write the actual implementation. `.todo` marks a test as planned but not yet written. It shows up in the report as a reminder: ```ts import { describe, it } from 'vitest' -// An entry will be shown in the report for this suite describe.todo('unimplemented suite') -// An entry will be shown in the report for this test describe('suite', () => { it.todo('unimplemented test') }) ``` + +Unlike `.skip`, a `.todo` test has no test body. It's purely a placeholder for future work. diff --git a/docs/guide/parallelism.md b/docs/guide/parallelism.md index c2033531e..4c694c3b8 100644 --- a/docs/guide/parallelism.md +++ b/docs/guide/parallelism.md @@ -5,28 +5,51 @@ outline: deep # Parallelism +Vitest has two levels of parallelism: it can run multiple *test files* at the same time, and within each file it can run multiple *tests* at the same time. Understanding the difference between the two is important because they work differently and have different trade-offs. + ## File Parallelism -By default, Vitest runs _test files_ in parallel. Depending on the specified `pool`, Vitest uses a different mechanism to parallelize test files: +By default, Vitest runs test files in parallel across multiple workers. Each file gets its own isolated environment, so tests in different files can't interfere with each other. + +The mechanism Vitest uses to create workers depends on the configured [`pool`](/config/pool): + +- `forks` (the default) and `vmForks` run each file in a separate [child process](https://nodejs.org/api/child_process.html) +- `threads` and `vmThreads` run each file in a separate [worker thread](https://nodejs.org/api/worker_threads.html) -- `forks` (the default) and `vmForks` run tests in different [child processes](https://nodejs.org/api/child_process.html) -- `threads` and `vmThreads` run tests in different [worker threads](https://nodejs.org/api/worker_threads.html) +You can control how many workers run simultaneously with the [`maxWorkers`](/config/maxworkers) option. More workers means more files run in parallel, but also more memory and CPU usage. The right number depends on your machine and how heavy your tests are. -Both "child processes" and "worker threads" are referred to as "workers". You can configure the number of running workers with [`maxWorkers`](/config/maxworkers) option. +For most projects, file parallelism is the single biggest factor in test suite speed. However, there are cases where you might want to disable it — for example, if your tests share an external resource like a database that can't handle concurrent access. You can set [`fileParallelism`](/config/fileparallelism) to `false` to run files one at a time. -If you have a lot of tests, it is usually faster to run them in parallel, but it also depends on the project, the environment and [isolation](/config/isolate) state. To disable file parallelisation, you can set [`fileParallelism`](/config/fileparallelism) to `false`. To learn more about possible performance improvements, read the [Performance Guide](/guide/improving-performance). +To learn more about tuning performance, see the [Performance Guide](/guide/improving-performance). ## Test Parallelism -Unlike _test files_, Vitest runs _tests_ in sequence. This means that tests inside a single test file will run in the order they are defined. +Within a single file, Vitest runs tests sequentially by default. Tests execute in the order they are defined, one after another. This is the safest default because tests within a file often share setup and state through lifecycle hooks like `beforeEach`. + +If the tests in a file are independent, you can opt into running them concurrently with the [`concurrent`](/api/test#test-concurrent) modifier: + +```ts +import { expect, test } from 'vitest' + +test.concurrent('fetches user profile', async () => { + const user = await fetchUser(1) + expect(user.name).toBe('Alice') +}) -Vitest supports the [`concurrent`](/api/test#test-concurrent) option to run tests together. If this option is set, Vitest will group concurrent tests in the same _file_ (the number of simultaneously running tests depends on the [`maxConcurrency`](/config/maxconcurrency) option) and run them with [`Promise.all`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all). +test.concurrent('fetches user posts', async () => { + const posts = await fetchPosts(1) + expect(posts).toHaveLength(3) +}) +``` -The hook execution order within a single group is also controlled by [`sequence.hooks`](/config/sequence#sequence-hooks). With `sequence.hooks: 'parallel'`, the execution is bounded by the same limit of [`maxConcurrency`](/config/maxconcurrency). +When tests are marked as `concurrent`, Vitest groups them together and runs them with [`Promise.all`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all). The number of tests running at once is bounded by the [`maxConcurrency`](/config/maxconcurrency) option. -Vitest doesn't perform any smart analysis and doesn't create additional workers to run these tests. This means that the performance of your tests will improve only if you rely heavily on asynchronous operations. For example, these tests will still run one after another even though the `concurrent` option is specified. This is because they are synchronous: +::: tip When does `concurrent` actually help? +Vitest doesn't create extra workers for concurrent tests — they all run in the same worker as the file they belong to. This means `concurrent` only speeds things up when your tests spend time *waiting* (on network requests, timers, file I/O, etc.). Purely synchronous tests won't benefit because they still block the single JavaScript thread: ```ts +// These run one after another despite `concurrent`, +// because there is nothing to await test.concurrent('the first test', () => { expect(1).toBe(1) }) @@ -35,5 +58,30 @@ test.concurrent('the second test', () => { expect(2).toBe(2) }) ``` +::: + +You can also apply `concurrent` to an entire suite: + +```ts +import { describe, expect, test } from 'vitest' + +describe.concurrent('user API', () => { + test('fetches profile', async () => { + const user = await fetchUser(1) + expect(user.name).toBe('Alice') + }) + + test('fetches posts', async () => { + const posts = await fetchPosts(1) + expect(posts).toHaveLength(3) + }) +}) +``` + +If you want *all* tests in your project to run concurrently by default, set [`sequence.concurrent`](/config/sequence#sequence-concurrent) to `true` in your config. + +### Hooks with Concurrent Tests + +When tests run concurrently, lifecycle hooks behave differently. `beforeAll` and `afterAll` still run once for the group, but `beforeEach` and `afterEach` run for each test — potentially at the same time, since the tests themselves overlap. -If you wish to run all tests concurrently, you can set the [`sequence.concurrent`](/config/sequence#sequence-concurrent) option to `true`. +The hook execution order is controlled by [`sequence.hooks`](/config/sequence#sequence-hooks). With `sequence.hooks: 'parallel'`, hooks are also bounded by the [`maxConcurrency`](/config/maxconcurrency) limit. -- 2.51.2