docs(en): merge docs-cn/sync-docs into docs-cn/dev @ a141f9d (#955)

* feat: add `experimental.preParse` flag (#10070)

* feat(coverage): default to text reporter `skipFull` if agent detected (#10018)

* docs: document browser mode auto cleanup behavior (#10045)

Co-authored-by: Codex <noreply@openai.com>

* feat(experimental): expose `assertion` as a public field (#10095)

* docs: add "Learn" section (#10092)

* docs(cn): dissolve the conflict

* [autofix.ci] apply automated fixes

---------

Co-authored-by: Vladimir <sleuths.slews0s@icloud.com>
Co-authored-by: Hiroshi Ogawa <hi.ogawa.zz@gmail.com>
Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: noise <noisefan@163.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: 5 people

.vitepress/config.ts

@@ -722,6 +722,57 @@ export default ({ mode }: { mode: string }) => {
               },
             ],
           },
+          {
+            text: 'Learn',
+            collapsed: false,
+            items: [
+              {
+                text: 'Writing Tests',
+                link: '/guide/learn/writing-tests',
+                docFooterText: 'Writing Tests | Learn',
+              },
+              {
+                text: 'Using Matchers',
+                link: '/guide/learn/matchers',
+                docFooterText: 'Using Matchers | Learn',
+              },
+              {
+                text: 'Testing Async Code',
+                link: '/guide/learn/async',
+                docFooterText: 'Testing Async Code | Learn',
+              },
+              {
+                text: 'Setup and Teardown',
+                link: '/guide/learn/setup-teardown',
+                docFooterText: 'Setup and Teardown | Learn',
+              },
+              {
+                text: 'Mock Functions',
+                link: '/guide/learn/mock-functions',
+                docFooterText: 'Mock Functions | Learn',
+              },
+              {
+                text: 'Snapshot Testing',
+                link: '/guide/learn/snapshots',
+                docFooterText: 'Snapshot Testing | Learn',
+              },
+              {
+                text: 'Testing in Practice',
+                link: '/guide/learn/testing-in-practice',
+                docFooterText: 'Testing in Practice | Learn',
+              },
+              {
+                text: 'Debugging Tests',
+                link: '/guide/learn/debugging-tests',
+                docFooterText: 'Debugging Tests | Learn',
+              },
+              {
+                text: 'Writing Tests with AI',
+                link: '/guide/learn/writing-tests-with-ai',
+                docFooterText: 'Writing Tests with AI | Learn',
+              },
+            ],
+          },
           {
             text: '浏览器模式',
             collapsed: false,
@@ -796,35 +847,35 @@ export default ({ mode }: { mode: string }) => {
                 collapsed: true,
                 items: [
                   {
-                    text: '模拟日期',
+                    text: '日期',
                     link: '/guide/mocking/dates',
                   },
                   {
-                    text: '模拟函数',
+                    text: '函数',
                     link: '/guide/mocking/functions',
                   },
                   {
-                    text: '模拟全局对象',
+                    text: '全局对象',
                     link: '/guide/mocking/globals',
                   },
                   {
-                    text: '模拟模块',
+                    text: '模块',
                     link: '/guide/mocking/modules',
                   },
                   {
-                    text: '模拟文件系统',
+                    text: '文件系统',
                     link: '/guide/mocking/file-system',
                   },
                   {
-                    text: '模拟请求',
+                    text: '请求',
                     link: '/guide/mocking/requests',
                   },
                   {
-                    text: '模拟计时器',
+                    text: '计时器',
                     link: '/guide/mocking/timers',
                   },
                   {
-                    text: '模拟类',
+                    text: '类',
                     link: '/guide/mocking/classes',
                   },
                 ],

api/browser/interactivity.md

@@ -40,6 +40,25 @@ await originalUserEvent.keyboard('{/Shift}') // 没有放开 shift 键，因为
 这种行为更有用，因为我们并没有模拟键盘，而是实际按下了 Shift 键，所以保留原来的行为会在字段中键入时造成意想不到的问题。
 :::
 
+::: warning
+With `playwright` and `webdriverio` providers, interactions are performed by the underlying browser driver. That means some interaction state, like pressed keys or pointer position and the resulting hover state, can persist between tests in the same file.
+
+Vitest resets unreleased keyboard state automatically before starting each test case, but pointer position and the resulting hover state are not reset automatically since resetting pointer position can be expensive.
+
+This applies both to `userEvent.*` calls and locator shortcuts like `locator.click()` or `locator.hover()`, because they use the same underlying interaction state.
+
+If your tests depend on a neutral hover state, reset it explicitly, for example in `beforeEach`:
+
+```ts
+import { beforeEach } from 'vitest'
+import { userEvent } from 'vitest/browser'
+
+beforeEach(async () => {
+  await userEvent.unhover(document.body)
+})
+```
+:::
+
 ## userEvent.click
 
 ```ts

config/coverage.md

@@ -132,6 +132,10 @@ npx vitest --coverage.enabled --coverage.provider=istanbul
 ```
 
 你可以在 Vitest UI 模式中查看代码覆盖率报告。更多详情请参阅 [Vitest UI Coverage](/guide/coverage#vitest-ui)。
+<!-- TODO: translation -->
+::: tip AI coding agents
+When Vitest detects it is running inside an AI coding agent, it automatically adds the `text-summary` reporter and sets `skipFull: true` on the `text` reporter to reduce output and minimize token usage.
+:::
 
 ## coverage.reportOnFailure {#coverage-reportonfailure}
 

config/experimental.md

@@ -478,3 +478,36 @@ export default {
 如果禁用模块运行器，Vitest 会使用原生 [Node.js 模块加载器](https://nodejs.org/api/module.html#customization-hooks) 来转换文件，以支持 `import.meta.vitest`、`vi.mock` 和 `vi.hoisted` 功能。
 
 如果你不使用这些特性，可禁用此功能以提升性能。
+<!-- TODO: translation -->
+## experimental.preParse <Version type="experimental">4.1.3</Version> {#experimental-preparse}
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Parses test specifications before running them. This applies the [`.only`](/api/test#test-only) modifier, the [`-t`](/config/testnamepattern) test name pattern, [`--tags-filter`](/guide/test-tags#syntax), [test lines](/api/advanced/test-specification#testlines), and [test IDs](/api/advanced/test-specification#testids) across all files without executing them. For example, if only a single test is marked with `.only`, Vitest will skip all other tests in all files.
+
+::: tip
+This option is recommended when using [`.only`](/api/test#test-only), the [`-t`](/config/testnamepattern) flag, or [`--tags-filter`](/guide/test-tags#syntax).
+
+Enabling it unconditionally may slow down your test runs due to the additional parsing step.
+:::
+
+::: warning
+Pre-parsing uses static analysis (AST parsing) instead of executing your test files. This means that test names, tags, and modifiers (`.only`, `.skip`, `.todo`) must be statically analyzable. Dynamic test names (e.g., names stored in variables or returned from function calls) and non-literal tags will not be resolved correctly.
+
+```ts
+// ✅ works — static string literal
+test('adds numbers', () => {})
+
+// ✅ works — static tags
+test('my test', { tags: ['unit'] }, () => {})
+
+// ❌ won't match correctly — dynamic name
+const name = getName()
+test(name, () => {})
+
+// ❌ won't match correctly — dynamic tags
+const tags = getTags()
+test('my test', { tags }, () => {})
+```
+:::

config/index.md

@@ -78,5 +78,11 @@ export default defineConfig(configEnv => mergeConfig(
 ```
 
 由于 Vitest 使用 Vite 的配置，我们也可以使用 [Vite](https://vitejs.dev/config/) 中的任何配置选项。例如，使用 `define` 来定义全局变量，或者使用 `resolve.alias` 来定义别名——这些选项应该在顶级定义，而不是在 `test` 属性内部。
+<!-- TODO: translation -->
+## Automatic Dependency Installation
+
+Vitest will prompt you to install certain dependencies if they are not already installed. You can disable this behavior by setting the `VITEST_SKIP_INSTALL_CHECKS=1` environment variable.
+
+## Config Options
 
 在 [项目](/guide/projects) 配置中不支持的配置选项旁边会显示 <CRoot /> 图标。这意味着它们只能在 Vitest 根配置文件中进行设置。

guide/cli-generated.md

@@ -963,3 +963,10 @@ watch 模式下重新运行测试时清除终端屏幕（默认值：`true`）
 - **Config:** [experimental.vcsProvider](/config/experimental#experimental-vcsprovider)
 
 Custom provider for detecting changed files. (default: `git`)
+
+### experimental.preParse
+
+- **CLI:** `--experimental.preParse`
+- **Config:** [experimental.preParse](/config/experimental#experimental-preparse)
+
+Parse test specifications before running them. This will apply `.only` flag and test name pattern across all files without running them. (default: `false`)

guide/coverage.md

@@ -510,3 +510,12 @@ export function ignored() { // [!code error]
 
 <img alt="html coverage in Vitest UI" img-light src="/ui-coverage-1-light.png">
 <img alt="html coverage in Vitest UI" img-dark src="/ui-coverage-1-dark.png">
+<!-- TODO: translation -->
+## Coverage in Agent Environments
+
+When Vitest detects it is running inside an AI coding agent, it automatically adjusts the default `text` reporter to reduce output and minimize token usage:
+
+- `skipFull: true` is set on the `text` reporter, so files with 100% coverage are omitted from the terminal output.
+- The [`text-summary`](/config/coverage#coverage-reporter) reporter is added automatically, so the agent always sees a concise totals table even when `skipFull` hides all individual files.
+
+These adjustments only apply when the `text` reporter is already part of the active reporter list (it is included in the default). Explicitly configured reporters are never removed.

guide/extending-matchers.md

@@ -156,6 +156,10 @@ When using the global `expect` with concurrent tests, `this.task` is `undefined`
 
 断言是否以 [`soft`](/api/expect#soft) 方式调用。您无需手动处理该逻辑，Vitest 始终会捕获错误。
 
+## `assertion` <Advanced /> <Version type="experimental">4.1.4</Version> {#assertion}
+
+The underlying [Chai assertion](https://www.chaijs.com/guide/plugins/) object. This is the same instance that Chai plugins receive, giving you access to Chai's flag system and chainable methods. This can be useful for building custom matchers that need to interact with Chai's internals.
+
 ::: tip
 以上并非全部可用属性，仅列出最实用的部分。其他状态值由 Vitest 内部使用。
 :::

guide/features.md

@@ -16,10 +16,16 @@ import FeaturesList from '../.vitepress/components/FeaturesList.vue'
 ## 一套配置可以运用在多种环境 {#shared-config-between-test-dev-and-build}
 
 <div h-2 />
+<!-- TODO: translation -->
+::: tip
+This page is a high-level overview of Vitest's capabilities. If you're new to Vitest, we recommend reading the [Learn](/guide/learn/writing-tests) tutorial first for a hands-on introduction.
+:::
+
+## Shared Config between Test, Dev and Build
 
 与 Vite 的配置、转换器、解析器和插件通用，将会使用应用中的相同配置来运行测试。
 
-了解更多信息 [配置 Vitest](/guide/#configuring-vitest) 。
+更多详情请参阅 [配置 Vitest](/config/) 。
 
 ## 监听模式(watch mode) {#watch-mode}