From c18a924db951363778078c62e1a21ee37bfa2c18 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Mon, 3 Aug 2026 14:14:46 +0200 Subject: [PATCH 1/4] fix(deps): update all non-major dependencies (#10861) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: Vladimir Sheremet --- package.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/package.json b/package.json index f937c832..9d3d5262 100644 --- a/package.json +++ b/package.json @@ -22,8 +22,8 @@ "@iconify-json/carbon": "catalog:", "@iconify-json/logos": "catalog:", "@iconify/vue": "catalog:", - "@shikijs/transformers": "^4.3.1", - "@shikijs/vitepress-twoslash": "^4.3.1", + "@shikijs/transformers": "^4.4.1", + "@shikijs/vitepress-twoslash": "^4.4.1", "@unocss/reset": "catalog:", "@vite-pwa/assets-generator": "^1.0.2", "@vite-pwa/vitepress": "^1.1.0", @@ -35,8 +35,8 @@ "vite": "^6.3.5", "vite-plugin-pwa": "^1.3.0", "vitepress": "2.0.0-alpha.16", - "vitepress-plugin-group-icons": "^1.7.5", - "vitepress-plugin-llms": "^1.13.3", + "vitepress-plugin-group-icons": "^1.7.6", + "vitepress-plugin-llms": "^1.13.4", "vitepress-plugin-tabs": "^0.9.1", "workbox-window": "^7.4.1" } From 4ec37663f4224fa1735f0141e4d34581782c1948 Mon Sep 17 00:00:00 2001 From: Vladimir Date: Tue, 4 Aug 2026 15:37:23 +0200 Subject: [PATCH 2/4] fix!: use `>` as separator in `-t`, calculate `only` once (#10686) --- config/testnamepattern.md | 16 ++++++++++++++++ guide/filtering.md | 2 +- guide/migration.md | 26 ++++++++++++++++++++++++++ 3 files changed, 43 insertions(+), 1 deletion(-) diff --git a/config/testnamepattern.md b/config/testnamepattern.md index c0646e5b..5149c0f9 100644 --- a/config/testnamepattern.md +++ b/config/testnamepattern.md @@ -24,3 +24,19 @@ test('doNotRun', () => { expect(true).toBe(true) }) ``` + +The pattern is matched against the test's full name: the enclosing suite names and the test name joined with `' > '` (the same string shown in the reporter output). For example, the test below has the full name `math > adds`, so it is matched by `-t 'math > adds'` or `-t adds`: + +```js +import { describe, expect, test } from 'vitest' + +describe('math', () => { + test('adds', () => { + expect(1 + 1).toBe(2) + }) +}) +``` + +::: warning +Before Vitest 5, the segments were joined with a single space (`math adds`) to mirror Jest. See the [migration guide](/guide/migration#vitest-5) for details. +::: diff --git a/guide/filtering.md b/guide/filtering.md index 3c7501dc..d9c4029e 100644 --- a/guide/filtering.md +++ b/guide/filtering.md @@ -44,7 +44,7 @@ This is useful when you know which file you need to work on and want to skip eve ## Filtering by Test Name -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: +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 is the enclosing `describe` block names and the test name joined with `' > '` (for example `math > adds`): ```bash vitest -t "handles empty input" diff --git a/guide/migration.md b/guide/migration.md index a0f6c1ff..986703a1 100644 --- a/guide/migration.md +++ b/guide/migration.md @@ -56,6 +56,25 @@ export default defineConfig({ }) ``` +### `testNamePattern` Matches the `>`-Joined Full Name + +[`testNamePattern`](/config/testnamepattern) (the `-t` CLI flag) now matches against the test's full name with the suite chain and test name joined by `' > '`, the same string shown in the reporter output. Previously the segments were joined with a single space, mirroring Jest. + +This only affects patterns that span the boundary between a suite and a test (or between nested suites). Patterns that match within a single name segment, and patterns that use `.`/`.*` between segments, are unaffected. + +```ts +describe('math', () => { + test('adds', () => {}) +}) +``` + +```bash +vitest -t 'math adds' # [!code --] +vitest -t 'math > adds' # [!code ++] +``` + +To keep a pattern working regardless of the separator, match a single segment (`-t adds`) or use a wildcard between segments (`-t 'math.*adds'`). + ### Inline Projects Inherit the Root Config by Default The [`extends`](/guide/projects#configuration) option now defaults to `true`: every project defined as an inline configuration in [`test.projects`](/guide/projects) inherits all options from the root configuration, including Vite options like `plugins` or `resolve.alias`. The options are merged with the same rules that applied to an explicit `extends: true` in Vitest 4: @@ -624,6 +643,13 @@ Vitest's `test` names are joined with a `>` symbol to make it easier to distingu + `${describeTitle} > ${testTitle}` ``` +The same applies to [`testNamePattern`](/config/testnamepattern) (the `-t` flag): Vitest matches against the `>`-joined full name, while Jest matches the space-joined name. Update patterns that span a suite and a test accordingly, or match a single segment (`-t adds`) or use a wildcard between segments (`-t 'math.*adds'`). + +```diff +- vitest -t 'math adds' ++ vitest -t 'math > adds' +``` + ### Envs Just like Jest, Vitest sets `NODE_ENV` to `test`, if it wasn't set before. Vitest also has a counterpart for `JEST_WORKER_ID` called `VITEST_POOL_ID` (always less than or equal to `maxWorkers`), so if you rely on it, don't forget to rename it. Vitest also exposes `VITEST_WORKER_ID` which is a unique ID of a running worker - this number is not affected by `maxWorkers`, and will increase with each created worker. From 8bd62ec3a572c72608ac7f771f354094b979491d Mon Sep 17 00:00:00 2001 From: Vladimir Date: Tue, 4 Aug 2026 15:57:58 +0200 Subject: [PATCH 3/4] docs: explain vm pool worker recycling cost (#10855) Co-authored-by: Raul Macarie --- config/pool.md | 10 +++++++++- config/vmmemorylimit.md | 13 +++++++++++-- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/config/pool.md b/config/pool.md index b98bb9fd..4639d18f 100644 --- a/config/pool.md +++ b/config/pool.md @@ -23,7 +23,13 @@ Similar as `threads` pool but uses `child_process` instead of `worker_threads`. Run tests using [VM context](https://nodejs.org/api/vm.html) (inside a sandboxed environment) in a `threads` pool. -This makes tests run faster, but the VM module is unstable when running [ESM code](https://github.com/nodejs/node/issues/37648). Your tests will [leak memory](https://github.com/nodejs/node/issues/33439) - to battle that, consider manually editing [`vmMemoryLimit`](/config/vmmemorylimit) value. +This makes tests run faster, but the VM module is unstable when running [ESM code](https://github.com/nodejs/node/issues/37648). Your tests will [leak memory](https://github.com/nodejs/node/issues/33439) - to battle that, workers are restarted when they exceed [`vmMemoryLimit`](/config/vmmemorylimit). + +::: warning Worker recycling is expensive in `vmThreads` +Restarting a worker thread is not free: Node.js runs a full garbage collection over everything the worker accumulated before the thread can exit, and that work runs on a small pool of background threads shared by every worker in the process. When a large test suite hits [`vmMemoryLimit`](/config/vmmemorylimit) repeatedly, these teardowns pile up and also slow down the workers that are still running tests. + +The `vmForks` pool recycles workers by letting the child process exit, and the operating system reclaims the memory. If your test suite is large enough to recycle workers, `vmForks` is usually noticeably faster than `vmThreads`, even though its communication with the main process is slower. +::: ::: warning Running code in a sandbox has some advantages (faster tests), but also comes with a number of disadvantages. @@ -48,3 +54,5 @@ Please, be aware of these issues when using this option. Vitest team cannot fix ## vmForks Similar as `vmThreads` pool but uses `child_process` instead of `worker_threads`. 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`. + +Unlike `vmThreads`, recycling a worker that exceeded [`vmMemoryLimit`](/config/vmmemorylimit) only requires the child process to exit, so it is much cheaper. On large test suites that recycle workers regularly, prefer `vmForks` over `vmThreads`. diff --git a/config/vmmemorylimit.md b/config/vmmemorylimit.md index 118d9bb1..08a75452 100644 --- a/config/vmmemorylimit.md +++ b/config/vmmemorylimit.md @@ -6,11 +6,20 @@ outline: deep # vmMemoryLimit - **Type:** `string | number` -- **Default:** `1 / CPU Cores` +- **Default:** `1 / maxWorkers` This option affects only `vmForks` and `vmThreads` pools. -Specifies the memory limit for workers before they are recycled. This value heavily depends on your environment, so it's better to specify it manually instead of relying on the default. +Specifies the memory limit for workers before they are recycled. + +By default, the total system memory is split evenly between workers. By increasing [`maxWorkers`](/config/maxworkers), workers have less memory available, so they're recycled more often. + +This value heavily depends on your environment, so it's better to specify it manually instead of relying on the default. + +Recycling exists because VM contexts [leak memory](https://github.com/nodejs/node/issues/33439): a worker's memory usage grows with every test file it runs, so a worker cannot live forever. The limit is a trade-off: + +- A low limit recycles workers frequently. In the `vmThreads` pool this is expensive, because destroying a worker thread runs a full garbage collection over the worker's memory and competes with running tests for the process' shared background threads. The `vmForks` pool recycles workers by letting the child process exit, which makes frequent recycling much cheaper there. +- A high limit lets workers accumulate memory. When the combined memory usage of all workers approaches what the machine can hold, every pool slows down. ::: tip The implementation is based on Jest's [`workerIdleMemoryLimit`](https://jestjs.io/docs/configuration#workeridlememorylimit-numberstring). From 039ef715594682e5920bd8dd9d6aa1fb69d0b44b Mon Sep 17 00:00:00 2001 From: noise Date: Fri, 7 Aug 2026 11:50:39 +0800 Subject: [PATCH 4/4] docs(cn): dissolve the conflict --- config/pool.md | 10 +--------- config/vmmemorylimit.md | 17 +++++------------ guide/filtering.md | 6 +----- guide/migration.md | 8 +++----- package.json | 14 -------------- 5 files changed, 10 insertions(+), 45 deletions(-) diff --git a/config/pool.md b/config/pool.md index 760a1147..fe3ac6af 100644 --- a/config/pool.md +++ b/config/pool.md @@ -22,10 +22,7 @@ outline: deep ## vmThreads 使用 [VM 上下文](https://nodejs.org/api/vm.html)（在沙箱环境中）在 `threads` 线程池中运行测试。 - -<<<<<<< HEAD -这使得测试运行速度更快，但 VM 模块在运行 [ESM 代码](https://github.com/nodejs/node/issues/37648) 时不稳定。你的测试可能会 [泄漏内存](https://github.com/nodejs/node/issues/33439)，为了解决这个问题，考虑手动设置 [`vmMemoryLimit`](/config/vmmemorylimit) 阈值。 -======= + This makes tests run faster, but the VM module is unstable when running [ESM code](https://github.com/nodejs/node/issues/37648). Your tests will [leak memory](https://github.com/nodejs/node/issues/33439) - to battle that, workers are restarted when they exceed [`vmMemoryLimit`](/config/vmmemorylimit). ::: warning Worker recycling is expensive in `vmThreads` @@ -33,7 +30,6 @@ Restarting a worker thread is not free: Node.js runs a full garbage collection o The `vmForks` pool recycles workers by letting the child process exit, and the operating system reclaims the memory. If your test suite is large enough to recycle workers, `vmForks` is usually noticeably faster than `vmThreads`, even though its communication with the main process is slower. ::: ->>>>>>> 8bd62ec3a572c72608ac7f771f354094b979491d ::: warning 在沙箱中运行代码有一些优势（测试速度更快），但也存在一些劣势。 @@ -57,10 +53,6 @@ catch (err) { ## vmForks -<<<<<<< HEAD 类似于 `vmThreads` 线程池，但使用 `child_process` 代替 `worker_threads`。测试与主进程之间的通信不如 `vmThreads` 线程池快。在 `vmForks` 线程池中可以使用与进程相关的 API，如 `process.chdir()`。请注意，此线程池具有 `vmThreads` 中列出的相同缺陷。 -======= -Similar as `vmThreads` pool but uses `child_process` instead of `worker_threads`. 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`. Unlike `vmThreads`, recycling a worker that exceeded [`vmMemoryLimit`](/config/vmmemorylimit) only requires the child process to exit, so it is much cheaper. On large test suites that recycle workers regularly, prefer `vmForks` over `vmThreads`. ->>>>>>> 8bd62ec3a572c72608ac7f771f354094b979491d diff --git a/config/vmmemorylimit.md b/config/vmmemorylimit.md index a0006830..3709a147 100644 --- a/config/vmmemorylimit.md +++ b/config/vmmemorylimit.md @@ -5,30 +5,23 @@ outline: deep # vmMemoryLimit -<<<<<<< HEAD - **类型:** `string | number` -- **默认值:** `1 / CPU 核心` -======= -- **Type:** `string | number` -- **Default:** `1 / maxWorkers` ->>>>>>> 8bd62ec3a572c72608ac7f771f354094b979491d +- **默认值:** `1 / 最大线程数` 此选项仅影响 `vmForks` 和 `vmThreads` 线程池。 -<<<<<<< HEAD -指定工作线程被回收之前的内存限制。该值在很大程度上取决于你的运行环境，因此最好手动指定它，而不是依赖默认值。 -======= -Specifies the memory limit for workers before they are recycled. +指定工作线程被回收之前的内存限制。 + + By default, the total system memory is split evenly between workers. By increasing [`maxWorkers`](/config/maxworkers), workers have less memory available, so they're recycled more often. -This value heavily depends on your environment, so it's better to specify it manually instead of relying on the default. +This value heavily depends on your environment, so it's better to specify it manually instead of relying on the default. Recycling exists because VM contexts [leak memory](https://github.com/nodejs/node/issues/33439): a worker's memory usage grows with every test file it runs, so a worker cannot live forever. The limit is a trade-off: - A low limit recycles workers frequently. In the `vmThreads` pool this is expensive, because destroying a worker thread runs a full garbage collection over the worker's memory and competes with running tests for the process' shared background threads. The `vmForks` pool recycles workers by letting the child process exit, which makes frequent recycling much cheaper there. - A high limit lets workers accumulate memory. When the combined memory usage of all workers approaches what the machine can hold, every pool slows down. ->>>>>>> 8bd62ec3a572c72608ac7f771f354094b979491d ::: tip 该实现基于 Jest 的 [`workerIdleMemoryLimit`](https://jestjs.io/docs/configuration#workeridlememorylimit-numberstring)。 diff --git a/guide/filtering.md b/guide/filtering.md index c41b1045..8da00573 100644 --- a/guide/filtering.md +++ b/guide/filtering.md @@ -45,11 +45,7 @@ basic/foo.test.ts ## 按测试名称过滤 {#filtering-by-test-name} -<<<<<<< HEAD -有时，你关心的那个测试会埋在一个包含许多其他测试的文件里。`-t`（或 `--testNamePattern`）选项会按测试名称而不是文件名进行过滤。它接受一个正则表达式，并会匹配完整的测试名称，其中也包括所有 `describe` 代码块的名称： -======= -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 is the enclosing `describe` block names and the test name joined with `' > '` (for example `math > adds`): ->>>>>>> 8bd62ec3a572c72608ac7f771f354094b979491d +有时，你关心的那个测试会埋在一个包含许多其他测试的文件里。`-t`（或 `--testNamePattern`）选项会按测试名称而不是文件名进行过滤。它接受一个正则表达式，并会匹配完整的测试名称，其中也包括所有 `describe` 代码块名称和测试名称通过 `' > '` 连接而成（例如 `math > adds`）： ```bash vitest -t "handles empty input" diff --git a/guide/migration.md b/guide/migration.md index 44da4890..e4682d1a 100644 --- a/guide/migration.md +++ b/guide/migration.md @@ -642,9 +642,8 @@ Vitest 的测试名使用 `>` 符号连接，方便区分测试与套件，而 J + `${describeTitle} > ${testTitle}` ``` -<<<<<<< HEAD -### 环境变量 {#envs} -======= + + The same applies to [`testNamePattern`](/config/testnamepattern) (the `-t` flag): Vitest matches against the `>`-joined full name, while Jest matches the space-joined name. Update patterns that span a suite and a test accordingly, or match a single segment (`-t adds`) or use a wildcard between segments (`-t 'math.*adds'`). ```diff @@ -652,8 +651,7 @@ The same applies to [`testNamePattern`](/config/testnamepattern) (the `-t` flag) + vitest -t 'math > adds' ``` -### Envs ->>>>>>> 8bd62ec3a572c72608ac7f771f354094b979491d +### 环境变量 {#envs} 与 Jest 一样，如果 `NODE_ENV` 在此之前未被设置，Vitest 会将其设为 `test`。Vitest 还提供了与 `JEST_WORKER_ID` 对应的 `VITEST_POOL_ID`（始终小于或等于 `maxWorkers`），如果你依赖该变量，别忘了重命名。Vitest 还暴露了 `VITEST_WORKER_ID`，它是运行中 worker 的唯一 ID 且该编号不受 `maxWorkers` 影响，每创建一个新 worker 就会递增。 diff --git a/package.json b/package.json index 2db570ad..9f834a7f 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,6 @@ "vue": "^3.5.40" }, "devDependencies": { -<<<<<<< HEAD "@antfu/eslint-config": "^9.2.0", "@antfu/ni": "^30.3.0", "@iconify-json/carbon": "^1.2.25", @@ -32,15 +31,6 @@ "@shikijs/vitepress-twoslash": "^4.3.1", "@types/node": "^26.1.2", "@unocss/reset": "^66.7.5", -======= - "@antfu/ni": "^28.3.0", - "@iconify-json/carbon": "catalog:", - "@iconify-json/logos": "catalog:", - "@iconify/vue": "catalog:", - "@shikijs/transformers": "^4.4.1", - "@shikijs/vitepress-twoslash": "^4.4.1", - "@unocss/reset": "catalog:", ->>>>>>> 8bd62ec3a572c72608ac7f771f354094b979491d "@vite-pwa/assets-generator": "^1.0.2", "@vite-pwa/vitepress": "^1.1.0", "@vitejs/plugin-vue": "^6.0.8", @@ -58,10 +48,6 @@ "vite-plugin-pwa": "^1.3.0", "vitepress": "2.0.0-alpha.16", "vitepress-plugin-group-icons": "^1.7.6", -<<<<<<< HEAD -======= - "vitepress-plugin-llms": "^1.13.4", ->>>>>>> 8bd62ec3a572c72608ac7f771f354094b979491d "vitepress-plugin-tabs": "^0.9.1", "vitest": "^4.1.10", "workbox-window": "^7.4.1"