vitest-dev · NoiseFan · May 19, 2026 · May 18, 2026 · May 18, 2026 · May 18, 2026
diff --git a/.vitepress/config.ts b/.vitepress/config.ts
@@ -808,9 +808,9 @@ export default ({ mode }: { mode: string }) => {
                 docFooterText: '追踪查看器 | 浏览器模式',
               },
               {
-                text: 'Playwright Traces',
+                text: 'Playwright 追踪',
                 link: '/guide/browser/playwright-traces',
-                docFooterText: 'Playwright Traces | Browser Mode',
+                docFooterText: 'Playwright 追踪 | 浏览器模式',
               },
               {
                 text: 'ARIA 快照',
@@ -819,32 +819,21 @@ export default ({ mode }: { mode: string }) => {
               },
             ],
           },
+          // Authoring — how to express a test in code: constructing it,
+          // asserting, mocking dependencies, attaching metadata. The page is
+          // about *test content*, not the runner. Discriminator: "How do I
+          // write X in a test?" If yes, it belongs here. Mocking sub-pages
+          // live nested because they're a multi-page subtopic.
           {
-            text: '指南',
+            text: '编写测试',
             collapsed: false,
             items: [
-              {
-                text: '命令行界面',
-                link: '/guide/cli',
-              },
-              {
-                text: '测试筛选',
-                link: '/guide/filtering',
-              },
-              {
-                text: '测试标签',
-                link: '/guide/test-tags',
-              },
               {
                 text: '测试上下文',
                 link: '/guide/test-context',
               },
               {
-                text: '测试环境',
-                link: '/guide/environment',
-              },
-              {
-                text: '测试运行生命周期',
+                text: '运行生命周期',
                 link: '/guide/lifecycle',
               },
               {
@@ -891,45 +880,85 @@ export default ({ mode }: { mode: string }) => {
                 ],
               },
               {
-                text: '并行测试',
-                link: '/guide/parallelism',
-              },
-              {
-                text: '测试项目',
-                link: '/guide/projects',
+                text: '测试',
+                link: '/guide/test-tags',
               },
               {
-                text: '报告器',
-                link: '/guide/reporters',
+                text: '测试注释',
+                link: '/guide/test-annotations',
               },
               {
-                text: '覆盖率',
-                link: '/guide/coverage',
+                text: '扩展断言',
+                link: '/guide/extending-matchers',
               },
               {
                 text: '类型测试',
                 link: '/guide/testing-types',
               },
-              {
-                text: 'UI 模式',
-                link: '/guide/ui',
-              },
               {
                 text: '内联测试',
                 link: '/guide/in-source',
               },
+            ],
+          },
+          // Workflow — how to invoke, select, and orchestrate test runs
+          // across files/projects/processes. The page is about the *runner
+          // and tooling around it*, not what's inside a test. Discriminator:
+          // "How do I run / filter / parallelize / integrate Vitest?" If a
+          // page is about the runtime environment of the tests themselves
+          // (jsdom, node), it still belongs here — that's a workflow choice.
+          {
+            text: '工作流',
+            collapsed: false,
+            items: [
               {
-                text: '测试注释',
-                link: '/guide/test-annotations',
+                text: '命令行界面',
+                link: '/guide/cli',
               },
               {
-                text: '扩展断言',
-                link: '/guide/extending-matchers',
+                text: '测试筛选',
+                link: '/guide/filtering',
+              },
+              {
+                text: '测试项目',
+                link: '/guide/projects',
+              },
+              {
+                text: '测试环境',
+                link: '/guide/environment',
+              },
+              {
+                text: '并行测试',
+                link: '/guide/parallelism',
+              },
+              {
+                text: '报告器',
+                link: '/guide/reporters',
+              },
+              {
+                text: 'UI 模式',
+                link: '/guide/ui',
               },
               {
                 text: 'IDE 插件',
                 link: '/guide/ide',
               },
+            ],
+          },
+          // Quality & Debugging — how to verify the test run is healthy and
+          // diagnose it when it isn't. Coverage, perf, leak detection, error
+          // triage, observability. Discriminator: "Is my suite good?" or
+          // "Why did this fail / leak / slow down?" If a page primarily
+          // measures or fixes the suite (rather than authoring or running
+          // it), put it here.
+          {
+            text: '质量与调试',
+            collapsed: false,
+            items: [
+              {
+                text: '覆盖率',
+                link: '/guide/coverage',
+              },
               {
                 text: '调试',
                 link: '/guide/debugging',
@@ -938,25 +967,6 @@ export default ({ mode }: { mode: string }) => {
                 text: '常见错误',
                 link: '/guide/common-errors',
               },
-              {
-                text: '迁移指南',
-                link: '/guide/migration',
-                collapsed: false,
-                items: [
-                  {
-                    text: '迁移到 Vitest 4',
-                    link: '/guide/migration#vitest-4',
-                  },
-                  {
-                    text: '从 Jest 迁移',
-                    link: '/guide/migration#jest',
-                  },
-                  {
-                    text: '从 Mocha + Chai + Sinon 迁移',
-                    link: '/guide/migration#mocha-chai-sinon',
-                  },
-                ],
-              },
               {
                 text: '性能',
                 collapsed: false,
@@ -977,6 +987,62 @@ export default ({ mode }: { mode: string }) => {
               },
             ],
           },
+          // Recipes — end-to-end patterns that solve a concrete problem by
+          // combining multiple features. Each entry is titled by the problem
+          // ("Database Transaction per Test"), not the feature. Add a recipe
+          // when a single feature page would over-explain, when the value
+          // comes from composition, or when users would search by intent
+          // rather than by API name.
+          {
+            text: '技巧',
+            collapsed: false,
+            items: [
+              {
+                text: 'Database Transaction per Test',
+                link: '/guide/recipes/db-transaction',
+              },
+              {
+                text: 'Cancelling Long-Running Operations Gracefully',
+                link: '/guide/recipes/cancellable',
+              },
+              {
+                text: 'Waiting for Async Conditions',
+                link: '/guide/recipes/wait-for',
+              },
+              {
+                text: 'Type Narrowing in Tests',
+                link: '/guide/recipes/type-narrowing',
+              },
+              {
+                text: 'Custom Assertion Helpers',
+                link: '/guide/recipes/custom-assertions',
+              },
+              {
+                text: 'Watching Non-Imported Files',
+                link: '/guide/recipes/watch-templates',
+              },
+              {
+                text: 'Extending Browser Locators',
+                link: '/guide/recipes/browser-locators',
+              },
+              {
+                text: 'Schema-Driven Assertions',
+                link: '/guide/recipes/schema-matching',
+              },
+              {
+                text: 'Auto-Cleanup with `using`',
+                link: '/guide/recipes/explicit-resources',
+              },
+              {
+                text: 'Per-File Isolation Settings',
+                link: '/guide/recipes/disable-isolation',
+              },
+              {
+                text: 'Parallel and Sequential Test Files',
+                link: '/guide/recipes/parallel-sequential',
+              },
+            ],
+          },
           {
             text: '高级指南',
             collapsed: true,
@@ -999,12 +1065,31 @@ export default ({ mode }: { mode: string }) => {
               },
             ],
           },
+          // Migration — one-time transitional content: cross-version
+          // upgrades and porting from other test runners (Jest, Mocha).
+          // Sits near the bottom because it's not daily-use and would push
+          // active-use guides further from the user's first scroll.
           {
+            text: '迁移',
+            link: '/guide/migration',
+            collapsed: false,
             items: [
               {
-                text: '测试技巧',
-                link: '/guide/recipes',
+                text: '迁移至 Vitest 4.0',
+                link: '/guide/migration#vitest-4',
               },
+              {
+                text: '从 Jest 迁移',
+                link: '/guide/migration#jest',
+              },
+              {
+                text: '从 Mocha + Chai + Sinon 迁移',
+                link: '/guide/migration#mocha-chai-sinon',
+              },
+            ],
+          },
+          {
+            items: [
               {
                 text: '测试框架比较',
                 link: '/guide/comparisons',

diff --git a/api/advanced/vitest.md b/api/advanced/vitest.md
@@ -8,7 +8,7 @@ title: Vitest API
 Vitest 实例需要当前的测试模式。它可以是以下之一：
 
 - `test`：运行运行时测试时
-- `benchmark`：运行基准测试时 <Badge type="warning">实验性</Badge>
+- `benchmark`：运行基准测试时 <Experimental />
 
 ::: details New in Vitest 4
 Vitest 4 新增了多个 API（它们都标记有 "4.0.0+" 徽章），并移除了已弃用的 API：
@@ -31,7 +31,7 @@ Vitest 4 新增了多个 API（它们都标记有 "4.0.0+" 徽章），并移除
 
 测试模式只会调用 `test` 或 `it` 中的函数，并在遇到 `bench` 时抛出错误。此模式使用配置中的 `include` 和 `exclude` 选项来查找测试文件。
 
-### benchmark <Badge type="warning">实验性</Badge> {#benchmark-experimental}
+### benchmark <Experimental /> {#benchmark}
 
 基准测试模式调用 `bench` 函数，并在遇到 `test` 或 `it` 时抛出错误。此模式使用配置中的 `benchmark.include` 和 `benchmark.exclude` 选项来查找基准测试文件。
 
@@ -47,7 +47,7 @@ Vitest 4 新增了多个 API（它们都标记有 "4.0.0+" 徽章），并移除
 
 这是全局的 [`ViteDevServer`](https://vite.dev/guide/api-javascript#vitedevserver)。
 
-## state <Badge type="warning">实验性</Badge> {#state-experimental}
+## state <Experimental /> {#state}
 
 ::: warning
 公共 `state` 是一个实验性 API（除了 `vitest.state.getReportedEntity`）。破坏性更改可能不遵循 SemVer，请在使用时固定 Vitest 的版本。

diff --git a/api/browser/assertions.md b/api/browser/assertions.md
@@ -1003,7 +1003,7 @@ await expect.element(queryByTestId('prev')).not.toHaveSelection()
 await expect.element(queryByTestId('next')).toHaveSelection('ne')
 ```
 
-## toMatchScreenshot <Badge type="warning">实验性</Badge> {#tomatchscreenshot}
+## toMatchScreenshot <Experimental /> {#tomatchscreenshot}
 
 ```ts
 function toMatchScreenshot(

diff --git a/api/vi.md b/api/vi.md
@@ -1055,7 +1055,7 @@ vi.useRealTimers()
 ### vi.useFakeTimers
 
 ```ts
-function useFakeTimers(config?: FakeTimerInstallOpts): Vitest
+function useFakeTimers(config?: FakeTimersConfig): Vitest
 ```
 
 要启用模拟定时器，需要调用此方法。在调用 [`vi.useRealTimers()`](#vi-userealtimers) 之前，它将封装所有对定时器的进一步调用（如 `setTimeout` 、`setInterval` 、`clearTimeout` 、`clearInterval` 、`setImmediate` 、`clearImmediate` 和 `Date`）。
@@ -1068,6 +1068,16 @@ function useFakeTimers(config?: FakeTimerInstallOpts): Vitest
 `vi.useFakeTimers()` 不再自动模拟 `process.nextTick` 。
 仍然可以通过在 `toFake` 参数中指定选项来模拟： `vi.useFakeTimers({ toFake: ['nextTick', 'queueMicrotask'] })` 。
 :::
+<!-- TODO: translation -->
+You can use `toFake` to specify which timers to mock, or `toNotFake` to specify which timers to keep native. Note that `toFake` and `toNotFake` cannot be specified together.
+
+```ts
+// only mock setTimeout and clearTimeout
+vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
+
+// mock all timers except setInterval
+vi.useFakeTimers({ toNotFake: ['setInterval'] })
+```
 
 ### vi.setTimerTickMode <Version>4.1.0</Version> {#vi-settimertickmode}
 
@@ -1342,7 +1352,7 @@ function resetConfig(): void
 
 如果之前调用过 [`vi.setConfig`](#vi-setconfig) ，则会将配置重置为原始状态。
 
-### vi.defineHelper <Version>4.1.0</Version> {#vi-defineHelper}
+### vi.defineHelper <Version>4.1.0</Version> {#vi-definehelper}
 
 ```ts
 function defineHelper<F extends (...args: any) => any>(fn: F): F

diff --git a/blog/vitest-3-2.md b/blog/vitest-3-2.md
@@ -219,7 +219,7 @@ export default defineConfig({
   test: {
     watchTriggerPatterns: [
       {
-        pattern: /^src\/templates\/(.*)\.(ts|html|txt)$/,
+        pattern: /src\/templates\/(.*)\.(ts|html|txt)$/,
         testsToRun: (file, match) => {
           return `api/tests/mailers/${match[2]}.test.ts`
         },

diff --git a/config/browser/webdriverio.md b/config/browser/webdriverio.md
@@ -62,3 +62,21 @@ export default defineConfig({
 
 请注意，Vitest 将忽略 `capabilities.browserName` — 请改用 [`test.browser.instances.browser`](/config/browser/instances#browser)。
 :::
+<!-- TODO: translation -->
+## Headful Chrome in CI
+
+Vitest enables [`browser.headless`](/config/browser/headless) automatically in CI.
+If you explicitly set `headless: false` for Chrome on a Linux CI runner, Chrome
+still needs a display server. Without one, WebDriverIO or ChromeDriver can fail
+with a misleading error such as `session not created: probably user data
+directory is already in use`.
+
+Run the test command through `xvfb-run` when you need headful Chrome in GitHub
+Actions or another Linux CI environment:
+
+```bash
+xvfb-run npm test
+```
+
+Alternatively, keep `browser.headless` enabled in CI and use headful mode only
+for local debugging.