docs(en): merge docs-cn/sync-docs into docs-cn/dev @ ad185a83

api/advanced/runner.md

@@ -144,8 +144,12 @@
 如果你没有自定义运行器或没有定义 `runTest` 方法，Vitest 将尝试自动检索任务。如果你没有使用 `setFn` 添加函数，这将会失败。
 :::
 
 ::: tip
+<<<<<<< HEAD
 快照支持和其他功能是依赖于测试运行器的。如果你想保留这些功能，可以从 `vitest/runners` 导入 `VitestTestRunner` 并将你的测试运行器继承该类。如果你想扩展基准测试功能，它还提供了 `NodeBenchmarkRunner`。
+=======
+Snapshot support and some other features depend on the runner. If you don't want to lose it, you can extend your runner from `TestRunner` imported from `vitest`. It also exposes `NodeBenchmarkRunner`, if you want to extend benchmark functionality.
+>>>>>>> ad185a835a130e727cdfb4ac909f05238364dc6a
 :::
 
 ## Tasks {#tasks}

api/browser/locators.md

@@ -1053,19 +1053,74 @@ function all(): Locator[]
 
 - [更多内容请参阅  `locator.elements()`](#elements)
 
+### serialize
+
+```ts
+function serialize(): SerializedLocator
+```
+
+Returns a JSON-serializable representation of the locator. The returned object has two fields:
+
+- [`selector`](#selector): the provider-specific selector string used to query the element at runtime.
+- `locator`: a human-readable description of the locator (e.g. `getByRole('button')`), used for error messages and tracing. Equivalent to calling [`asLocator()`](#aslocator).
+
+This is primarily intended for forwarding a locator to a [browser command](/api/browser/commands), which runs in Node and cannot receive a live `Locator` instance:
+
+```ts
+import { commands, page } from 'vitest/browser'
+
+await commands.myCommand(page.getByRole('button').serialize())
+```
+
+::: tip
+Vitest automatically serializes any `Locator` argument passed to a command, so calling `serialize()` explicitly is rarely necessary. You can also use `JSON.stringify(locator)` (it calls [`toJSON`](#tojson) internally), which produces the same result.
+:::
+
+### toJSON
+
+```ts
+function toJSON(): SerializedLocator
+```
+
+Alias of [`serialize`](#serialize). Defined so that `JSON.stringify(locator)` and structured-clone-based transports return a `SerializedLocator` object.
+
+### asLocator
+
+```ts
+function asLocator(): string
+```
+
+Returns a human-readable description of the locator using the JavaScript locator syntax (e.g. `getByRole('button', { name: 'Submit' })`). This is the same string exposed as the `locator` field of [`serialize()`](#serialize) and is used in error messages and traces.
+
+```ts
+import { page } from 'vitest/browser'
+
+const button = page.getByRole('button', { name: 'Submit' })
+button.asLocator() // "getByRole('button', { name: 'Submit' })"
+```
+
+::: tip
+Use [`selector`](#selector) when you need the provider-specific string to forward to a [browser command](/api/browser/commands). Use `asLocator()` only for diagnostic output. The returned string is not meant to be re-used to query elements.
+:::
+
 ## Properties
 
 ### selector
 
+<<<<<<< HEAD
 `selector` 是一个字符串，将由浏览器提供程序用于定位元素。Playwright 将使用 `playwright` 定位器语法，而 `preview` 和 `webdriverio` 将使用 CSS。
+=======
+The `selector` is a string that will be used to locate the element by the browser provider. Playwright will use a `playwright` locator syntax, and `preview` and `webdriverio` will use CSS.
+>>>>>>> ad185a835a130e727cdfb4ac909f05238364dc6a
 
 ::: danger
 你不应在测试代码中使用此字符串。`selector` 字符串仅应在使用 Commands API 时使用：
 
 ```ts [commands.ts]
 import type { BrowserCommand } from 'vitest/node'
+import type { SerializedLocator } from '@vitest/browser'
 
-const test: BrowserCommand<string> = function test(context, selector) {
+const test: BrowserCommand<SerializedLocator> = function test(context, { selector }) {
   // playwright
   await context.iframe.locator(selector).click()
   // webdriverio
@@ -1078,8 +1133,13 @@ import { test } from 'vitest'
 import { commands, page } from 'vitest/browser'
 
 test('works correctly', async () => {
+<<<<<<< HEAD
   await commands.test(page.getByText('Hello').selector) // ✅
   // Vitest 会自动将其解包为字符串
+=======
+  await commands.test(page.getByText('Hello').serialize()) // ✅
+  // vitest will automatically unwrap it to a SerializedLocator
+>>>>>>> ad185a835a130e727cdfb4ac909f05238364dc6a
   await commands.test(page.getByText('Hello')) // ✅
 })
 ```

api/describe.md

@@ -208,7 +208,24 @@
 })
 ```
 
+<<<<<<< HEAD
 `.skip`、`.only` 和 `.todo` 适用于并发测试套件。以下所有组合都有效：
+=======
+Set `concurrent` to `false` to opt out of concurrency inherited from a parent suite or [`sequence.concurrent`](/config/sequence#sequence-concurrent):
+
+```ts
+describe.concurrent('suite', () => {
+  test('concurrent test', async () => { /* ... */ })
+
+  describe('sequential suite', { concurrent: false }, () => {
+    test('sequential test 1', async () => { /* ... */ })
+    test('sequential test 2', async () => { /* ... */ })
+  })
+})
+```
+
+`.skip`, `.only`, and `.todo` works with concurrent suites. All the following combinations are valid:
+>>>>>>> ad185a835a130e727cdfb4ac909f05238364dc6a
 
 ```ts
 describe.concurrent(/* ... */)
@@ -230,6 +247,7 @@
 })
 ```
 
+<<<<<<< HEAD
 ## describe.sequential
 
 - **别名:** `suite.sequential`
@@ -250,6 +268,8 @@
 })
 ```
 
+=======
+>>>>>>> ad185a835a130e727cdfb4ac909f05238364dc6a
 ## describe.shuffle
 
 - **别名:** `suite.shuffle`

api/test.md

@@ -217,15 +217,23 @@
 
 是否与测试套件中其他并发测试并行运行。
 
-### sequential
+Set `concurrent` to `false` to opt out of concurrency inherited from [`describe.concurrent`](/api/describe#describe-concurrent) or [`sequence.concurrent`](/config/sequence#sequence-concurrent):
 
+<<<<<<< HEAD
 - **类型:** `boolean`
 - **默认值:** `true`
 - **别名:** [`test.sequential`](#test-sequential)
 
 是否按顺序运行测试。如果同时指定了 `concurrent` 和 `sequential`，`concurrent` 优先生效。
+=======
+```ts
+test('runs sequentially', { concurrent: false }, async () => {
+  // ...
+})
+```
+>>>>>>> ad185a835a130e727cdfb4ac909f05238364dc6a
 
 ### skip
 
 - **类型:** `boolean`
 - **默认值:** `false`
@@ -453,6 +461,7 @@
 
 注意，如果测试是同步的，Vitest 仍会按顺序运行它们。
 
+<<<<<<< HEAD
 ## test.sequential
 
 - **别名:** `it.sequential`
@@ -478,6 +487,8 @@
 })
 ```
 
+=======
+>>>>>>> ad185a835a130e727cdfb4ac909f05238364dc6a
 ## test.todo
 
 - **别名:** `it.todo`

config/attachmentsdir.md

@@ -5,7 +5,12 @@ outline: deep
 
 # attachmentsDir
 
+<<<<<<< HEAD
 - **类型:** `string`
 - **默认值:** `'.vitest-attachments'`
+=======
+- **Type:** `string`
+- **Default:** `'.vitest/attachments'`
+>>>>>>> ad185a835a130e727cdfb4ac909f05238364dc6a
 
 用于存储 [`context.annotate`](/guide/test-context#annotate) 所创建附件的目录路径（相对于项目根目录）。

config/browser/expect.md

@@ -104,7 +104,15 @@
 
   [`attachmentsDir`](/config/attachmentsdir) 配置项提供的值，如果未配置则使用其默认值。
 
+<<<<<<< HEAD
 例如，以下示例按浏览器分组存储截图：
+=======
+- `project: TestProject` <Version type="experimental">4.1.6</Version> <Experimental />
+
+  The [`TestProject`](/api/advanced/test-project) the test belongs to.
+
+For example, to group screenshots by browser:
+>>>>>>> ad185a835a130e727cdfb4ac909f05238364dc6a
 
 ```ts
 resolveScreenshotPath: ({ arg, browserName, ext, root, testFileName }) =>

config/coverage.md

@@ -457,4 +457,19 @@
 - **可用的测试提供者:** `'v8' | 'istanbul'`
 - **命令行终端:** `--coverage.changed`, `--coverage.changed=<commit/branch>`
 
+<<<<<<< HEAD
 仅收集自指定提交或分支以来更改的文件的代码覆盖率。设置为 `true` 时，使用已暂存和未暂存的更改。
+=======
+Collect coverage only for files changed since a specified commit or branch. When set to `true`, it uses staged and unstaged changes.
+
+## coverage.autoAttachSubprocess <Version>5.0.0</Version> {#coverage-autoattachsubprocess}
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **Available for providers:** `'v8'`
+- **CLI:** `--coverage.autoAttachSubprocess`
+
+Track coverage of the `node:child_process` and `node:worker_threads` spawned during test run.
+
+Note that this option has some performance overhead as its using [`NODE_V8_COVERAGE`](https://nodejs.org/api/cli.html#node-v8-coveragedir) internally. This triggers Node to write lots of unnecessary files on file system.
+>>>>>>> ad185a835a130e727cdfb4ac909f05238364dc6a

config/reporters.md

@@ -14,10 +14,17 @@ interface UserConfig {
 type ConfigReporter = string | Reporter | [string, object?]
 ```
 
+<<<<<<< HEAD
 - **默认值:** [`'default'`](/guide/reporters#default-reporter)（当 `process.env.GITHUB_ACTIONS === 'true'` 时为 <code>[['default'](/guide/reporters#default-reporter), ['github-actions'](/guide/reporters#github-actions-reporter)]</code>）
 - **命令行终端:**
   - `--reporter=tap` 用于单个报告器
   - `--reporter=verbose --reporter=github-actions` 用于多个报告器
+=======
+- **Default:** [`'default'`](/guide/reporters#default-reporter). See [Default Reporters](/guide/reporters#default-reporters) for environment-specific behavior.
+- **CLI:**
+  - `--reporter=tap` for a single reporter
+  - `--reporter=verbose --reporter=github-actions` for multiple reporters
+>>>>>>> ad185a835a130e727cdfb4ac909f05238364dc6a
 
 此选项定义在 Vitest 测试运行期间可用的单个报告器或报告器列表。
 
@@ -49,16 +56,24 @@ type ConfigReporter = string | Reporter | [string, object?]
 
 ::: code-group
 ```js [vitest.config.js]
-import { defineConfig } from 'vitest/config'
+import { configDefaults, defineConfig } from 'vitest/config'
 
 export default defineConfig({
   test: {
     reporters: [
+<<<<<<< HEAD
       'default',
       // 条件报告器
       process.env.CI ? 'github-actions' : {},
       // 来自 npm 包的自定义报告器
       // 选项将以元组形式向下传递
+=======
+      ...configDefaults.reporters,
+      // conditional reporter
+      ...(process.env.CI ? ['html'] : []),
+      // custom reporter from npm package
+      // options are passed down as a tuple
+>>>>>>> ad185a835a130e727cdfb4ac909f05238364dc6a
       [
         'vitest-sonar-reporter',
         { outputFile: 'sonar-report.xml' }

guide/browser/visual-regression-testing.md

@@ -276,10 +276,10 @@ Reference screenshot:
   tests/__screenshots__/button.test.ts/button-chromium-darwin.png
 
 Actual screenshot:
-  tests/.vitest-attachments/button.test.ts/button-chromium-darwin-actual.png
+  tests/.vitest/attachments/button.test.ts/button-chromium-darwin-actual.png
 
 Diff image:
-  tests/.vitest-attachments/button.test.ts/button-chromium-darwin-diff.png
+  tests/.vitest/attachments/button.test.ts/button-chromium-darwin-diff.png
 ```
 
 ### 如何解读差异图 {#understanding-the-diff-image}

guide/cli-generated.md

@@ -299,6 +299,13 @@
 
 UI 模式和 HTML 报告器中提供的 HTML 覆盖率输出目录。
 
+### coverage.autoAttachSubprocess
+
+- **CLI:** `--coverage.autoAttachSubprocess`
+- **Config:** [coverage.autoAttachSubprocess](/config/coverage#coverage-autoattachsubprocess)
+
+Track coverage of the `node:child_process` and `node:worker_threads` spawned during test run. Supported only by `v8` provider. (default: false)
+
 ### mode
 
 - **命令行终端:** `--mode <name>`
@@ -865,9 +872,13 @@
 - **命令行终端:** `--attachmentsDir <dir>`
 - **配置:** [attachmentsDir](/config/attachmentsdir)
 
+<<<<<<< HEAD
 `context.annotate` 方法所生成附件的存储目录 (默认值: `.vitest-attachments`)
+=======
+The directory where attachments from `context.annotate` are stored in (default: `.vitest/attachments`)
+>>>>>>> ad185a835a130e727cdfb4ac909f05238364dc6a
 
 ### run
 
 - **命令行终端:** `--run`
 

guide/improving-performance.md

@@ -191,7 +191,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: blob-attachments-${{ matrix.shardIndex }}
-          path: .vitest-attachments/**
+          path: .vitest/**
           include-hidden-files: true
           retention-days: 1
 
@@ -222,7 +222,7 @@ jobs:
       - name: Download attachments from GitHub Actions Artifacts
         uses: actions/download-artifact@v4
         with:
-          path: .vitest-attachments
+          path: .vitest
           pattern: blob-attachments-*
           merge-multiple: true