docs(en): merging all conflicts

Author: docschina-bot

.vitepress/config.ts

@@ -819,7 +819,13 @@ 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.
           {
+<<<<<<< HEAD
             text: '指南',
             collapsed: false,
             items: [
@@ -845,6 +851,17 @@ export default ({ mode }: { mode: string }) => {
               },
               {
                 text: '测试运行生命周期',
+=======
+            text: 'Authoring',
+            collapsed: false,
+            items: [
+              {
+                text: 'Test Context',
+                link: '/guide/test-context',
+              },
+              {
+                text: 'Test Run Lifecycle',
+>>>>>>> 3a513123224c0041b8cda52ce1f47c912ce05789
                 link: '/guide/lifecycle',
               },
               {
@@ -891,6 +908,7 @@ export default ({ mode }: { mode: string }) => {
                 ],
               },
               {
+<<<<<<< HEAD
                 text: '并行测试',
                 link: '/guide/parallelism',
               },
@@ -917,6 +935,10 @@ export default ({ mode }: { mode: string }) => {
               {
                 text: '内联测试',
                 link: '/guide/in-source',
+=======
+                text: 'Test Tags',
+                link: '/guide/test-tags',
+>>>>>>> 3a513123224c0041b8cda52ce1f47c912ce05789
               },
               {
                 text: '测试注释',
@@ -927,9 +949,77 @@ export default ({ mode }: { mode: string }) => {
                 link: '/guide/extending-matchers',
               },
               {
+<<<<<<< HEAD
                 text: 'IDE 插件',
+=======
+                text: 'Testing Types',
+                link: '/guide/testing-types',
+              },
+              {
+                text: 'In-Source Testing',
+                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: 'Workflow',
+            collapsed: false,
+            items: [
+              {
+                text: 'CLI',
+                link: '/guide/cli',
+              },
+              {
+                text: 'Test Filtering',
+                link: '/guide/filtering',
+              },
+              {
+                text: 'Test Projects',
+                link: '/guide/projects',
+              },
+              {
+                text: 'Test Environment',
+                link: '/guide/environment',
+              },
+              {
+                text: 'Parallelism',
+                link: '/guide/parallelism',
+              },
+              {
+                text: 'Reporters',
+                link: '/guide/reporters',
+              },
+              {
+                text: 'Vitest UI',
+                link: '/guide/ui',
+              },
+              {
+                text: 'IDE Integration',
+>>>>>>> 3a513123224c0041b8cda52ce1f47c912ce05789
                 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: 'Quality & Debugging',
+            collapsed: false,
+            items: [
+              {
+                text: 'Coverage',
+                link: '/guide/coverage',
+              },
               {
                 text: '调试',
                 link: '/guide/debugging',
@@ -939,6 +1029,7 @@ export default ({ mode }: { mode: string }) => {
                 link: '/guide/common-errors',
               },
               {
+<<<<<<< HEAD
                 text: '迁移指南',
                 link: '/guide/migration',
                 collapsed: false,
@@ -959,6 +1050,9 @@ export default ({ mode }: { mode: string }) => {
               },
               {
                 text: '性能',
+=======
+                text: 'Performance',
+>>>>>>> 3a513123224c0041b8cda52ce1f47c912ce05789
                 collapsed: false,
                 items: [
                   {
@@ -977,6 +1071,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: 'Recipes',
+            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,14 +1149,41 @@ 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: 'Migration',
+            link: '/guide/migration',
+            collapsed: false,
             items: [
               {
+<<<<<<< HEAD
                 text: '测试技巧',
                 link: '/guide/recipes',
               },
               {
                 text: '测试框架比较',
+=======
+                text: 'Migrating to Vitest 4.0',
+                link: '/guide/migration#vitest-4',
+              },
+              {
+                text: 'Migrating from Jest',
+                link: '/guide/migration#jest',
+              },
+              {
+                text: 'Migrating from Mocha + Chai + Sinon',
+                link: '/guide/migration#mocha-chai-sinon',
+              },
+            ],
+          },
+          {
+            items: [
+              {
+                text: 'Comparisons',
+>>>>>>> 3a513123224c0041b8cda52ce1f47c912ce05789
                 link: '/guide/comparisons',
               },
             ],

api/advanced/vitest.md

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

api/browser/assertions.md

@@ -1003,7 +1003,11 @@ await expect.element(queryByTestId('prev')).not.toHaveSelection()
 await expect.element(queryByTestId('next')).toHaveSelection('ne')
 ```
 
+<<<<<<< HEAD
 ## toMatchScreenshot <Badge type="warning">实验性</Badge> {#tomatchscreenshot}
+=======
+## toMatchScreenshot <Experimental /> {#tomatchscreenshot}
+>>>>>>> 3a513123224c0041b8cda52ce1f47c912ce05789
 
 ```ts
 function toMatchScreenshot(

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`）。
@@ -1069,6 +1069,16 @@ function useFakeTimers(config?: FakeTimerInstallOpts): Vitest
 仍然可以通过在 `toFake` 参数中指定选项来模拟： `vi.useFakeTimers({ toFake: ['nextTick', 'queueMicrotask'] })` 。
 :::
 
+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}
 
 - **类型:**`(mode: 'manual' | 'nextTimerAsync') => Vitest | (mode: 'interval', interval?: number) => Vitest`
@@ -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

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`
         },

config/browser/webdriverio.md

@@ -60,5 +60,27 @@ export default defineConfig({
 ::: tip
 最有用的选项位于 `capabilities` 对象上。WebdriverIO 允许嵌套功能，但 Vitest 将忽略这些选项，因为我们依赖于不同的机制来生成多个浏览器。
 
+<<<<<<< HEAD
 请注意，Vitest 将忽略 `capabilities.browserName` — 请改用 [`test.browser.instances.browser`](/config/browser/instances#browser)。
+=======
+Note that Vitest will ignore `capabilities.browserName`; use [`test.browser.instances.browser`](/config/browser/instances#browser) instead.
+>>>>>>> 3a513123224c0041b8cda52ce1f47c912ce05789
 :::
+
+## 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.