diff --git a/config/pool.md b/config/pool.md index ad4642f4..fe3ac6af 100644 --- a/config/pool.md +++ b/config/pool.md @@ -22,8 +22,14 @@ outline: deep ## vmThreads 使用 [VM 上下文](https://nodejs.org/api/vm.html)(在沙箱环境中)在 `threads` 线程池中运行测试。 + +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). -这使得测试运行速度更快,但 VM 模块在运行 [ESM 代码](https://github.com/nodejs/node/issues/37648) 时不稳定。你的测试可能会 [泄漏内存](https://github.com/nodejs/node/issues/33439),为了解决这个问题,考虑手动设置 [`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 在沙箱中运行代码有一些优势(测试速度更快),但也存在一些劣势。 @@ -48,3 +54,5 @@ catch (err) { ## vmForks 类似于 `vmThreads` 线程池,但使用 `child_process` 代替 `worker_threads`。测试与主进程之间的通信不如 `vmThreads` 线程池快。在 `vmForks` 线程池中可以使用与进程相关的 API,如 `process.chdir()`。请注意,此线程池具有 `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/testnamepattern.md b/config/testnamepattern.md index 3768d40b..c2f07985 100644 --- a/config/testnamepattern.md +++ b/config/testnamepattern.md @@ -23,3 +23,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/config/vmmemorylimit.md b/config/vmmemorylimit.md index 3205f294..3709a147 100644 --- a/config/vmmemorylimit.md +++ b/config/vmmemorylimit.md @@ -6,11 +6,22 @@ outline: deep # vmMemoryLimit - **类型:** `string | number` -- **默认值:** `1 / CPU 核心` +- **默认值:** `1 / 最大线程数` 此选项仅影响 `vmForks` 和 `vmThreads` 线程池。 -指定工作线程被回收之前的内存限制。该值在很大程度上取决于你的运行环境,因此最好手动指定它,而不是依赖默认值。 +指定工作线程被回收之前的内存限制。 + + + +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 该实现基于 Jest 的 [`workerIdleMemoryLimit`](https://jestjs.io/docs/configuration#workeridlememorylimit-numberstring)。 diff --git a/guide/filtering.md b/guide/filtering.md index 93084c24..8da00573 100644 --- a/guide/filtering.md +++ b/guide/filtering.md @@ -45,7 +45,7 @@ basic/foo.test.ts ## 按测试名称过滤 {#filtering-by-test-name} -有时,你关心的那个测试会埋在一个包含许多其他测试的文件里。`-t`(或 `--testNamePattern`)选项会按测试名称而不是文件名进行过滤。它接受一个正则表达式,并会匹配完整的测试名称,其中也包括所有 `describe` 代码块的名称: +有时,你关心的那个测试会埋在一个包含许多其他测试的文件里。`-t`(或 `--testNamePattern`)选项会按测试名称而不是文件名进行过滤。它接受一个正则表达式,并会匹配完整的测试名称,其中也包括所有 `describe` 代码块名称和测试名称通过 `' > '` 连接而成(例如 `math > adds`): ```bash vitest -t "handles empty input" diff --git a/guide/migration.md b/guide/migration.md index d353bf2f..e4682d1a 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: @@ -623,6 +642,15 @@ Vitest 的测试名使用 `>` 符号连接,方便区分测试与套件,而 J + `${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} 与 Jest 一样,如果 `NODE_ENV` 在此之前未被设置,Vitest 会将其设为 `test`。Vitest 还提供了与 `JEST_WORKER_ID` 对应的 `VITEST_POOL_ID`(始终小于或等于 `maxWorkers`),如果你依赖该变量,别忘了重命名。Vitest 还暴露了 `VITEST_WORKER_ID`,它是运行中 worker 的唯一 ID 且该编号不受 `maxWorkers` 影响,每创建一个新 worker 就会递增。