docs(en): merge docs-cn/sync-docs into docs-cn/dev @ 8331872 (#399)

* docs: replace old `--threads` flag references (#5099)

Co-authored-by: Anjorin Damilare <[email protected]>

* feat(reporters): support custom options (#5111)

* feat(config): add `snapshotSerializers` option (#5092)

* feat(vitest): add onTestFinished hook (#5128)

* feat(browser): run test files in isolated iframes (#5036)

* feat(vitest): add github actions reporter (#5093)

* docs(cn): synchronize the latest content

---------

Co-authored-by: Hiroshi Ogawa <[email protected]>
Co-authored-by: Anjorin Damilare <[email protected]>
Co-authored-by: Ari Perkkiö <[email protected]>
Co-authored-by: Han <[email protected]>
Co-authored-by: Vladimir <[email protected]>
Co-authored-by: elonehoo <[email protected]>

Author: 7 people

api/index.md

@@ -906,6 +906,10 @@ afterEach(async () => {
 
 在这里，`afterEach` 可确保在每次测试运行后清除测试数据。
 
+::: tip
+Vitest 1.3.0 新增 [`onTestFinished`](##ontestfinished-1-3-0) hook。你可以在测试执行过程中调用，以便在测试运行结束后清理任何状态。
+:::
+
 ### beforeAll
 
 - **类型:** `beforeAll(fn: () => Awaitable<void>, timeout?: number)`
@@ -959,3 +963,96 @@ afterAll(async () => {
 ```
 
 这里的 `afterAll` 确保在所有测试运行后调用 `stopMocking` 方法。
+
+## Test Hooks
+
+Vitest 提供了一些 hooks，你可以在测试执行期间调用这些钩子，以便在测试运行结束后清理状态。
+
+::: warning
+如果在测试体之外调用这些 hooks ，则会出错。
+:::
+
+### onTestFinished <Badge type="info">1.3.0+</Badge>
+
+这个 hook 总是在测试运行结束后调用。它在 `afterEach` 之后被调用，因为它们会影响测试结果。它接收一个包含当前测试结果的 `TaskResult` 。
+
+```ts
+import { onTestFinished, test } from 'vitest'
+
+test('performs a query', () => {
+  const db = connectDb()
+  onTestFinished(() => db.close())
+  db.query('SELECT * FROM users')
+})
+```
+
+::: warning
+如果要并发运行测试，应该始终使用测试上下文中的 `onTestFinished` ，因为 Vitest 不会在全局 hook 中跟踪并发测试：
+
+```ts
+import { test } from 'vitest'
+
+test.concurrent('performs a query', (t) => {
+  const db = connectDb()
+  t.onTestFinished(() => db.close())
+  db.query('SELECT * FROM users')
+})
+```
+:::
+
+这个 hook 在创建可重复使用的逻辑时特别有用：
+
+```ts
+// 这可以是一个单独的文件
+function getTestDb() {
+  const db = connectMockedDb()
+  onTestFinished(() => db.close())
+  return db
+}
+
+test('performs a user query', async () => {
+  const db = getTestDb()
+  expect(
+    await db.query('SELECT * from users').perform()
+  ).toEqual([])
+})
+
+test('performs an organization query', async () => {
+  const db = getTestDb()
+  expect(
+    await db.query('SELECT * from organizations').perform()
+  ).toEqual([])
+})
+```
+
+### onTestFailed
+
+只有在测试失败后才会调用这个 hook 。它在 `afterEach` 之后被调用，因为它们会影响测试结果。它将接收一个包含当前测试结果的 `TaskResult` 。这个 hook 对调试非常有用。
+
+```ts
+import { onTestFailed, test } from 'vitest'
+
+test('performs a query', () => {
+  const db = connectDb()
+  onTestFailed((e) => {
+    console.log(e.result.errors)
+  })
+  db.query('SELECT * FROM users')
+})
+```
+
+::: warning
+如果要并发运行测试，应始终使用测试上下文中的 `onTestFailed` ，因为 Vitest 不会在全局 hook 中跟踪并发测试：
+
+```ts
+import { test } from 'vitest'
+
+test.concurrent('performs a query', (t) => {
+  const db = connectDb()
+  onTestFailed((result) => {
+    console.log(result.errors)
+  })
+  db.query('SELECT * FROM users')
+})
+```
+:::

config/index.md

@@ -494,7 +494,7 @@ test("use jsdom in this test file", () => {
 });
 ```
 
-如果你使用 [`--threads=false`](#threads) 标志运行 Vitest，你的测试将按以下顺序运行：`node`, `jsdom`, `happy-dom`, `edge-runtime`, `custom environments`。 这意味着，具有相同环境的每个测试都组合在一起，但仍按顺序运行。
+如果使用 [`--isolate=false`](#isolate-1-1-0) 运行 Vitest，测试将按以下顺序运行：`node`、`jsdom`、`happy-dom`、`edge-runtime`、`custom environments`。也就是说，具有相同环境的每个测试都会被分组，但仍会按顺序运行。
 
 从 0.23.0 开始，你还可以定义自定义环境。 当使用非内置环境时，Vitest 将尝试加载包 `vitest-environment-${name}`。 该包应导出一个具有 `Environment` 属性的对象：
 
@@ -564,8 +564,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     poolMatchGlobs: [
-      // all tests in "worker-specific" directory will run inside a worker as if you enabled `--threads` for them,
-      ["**/tests/worker-specific/**", "threads"],
+      // all tests in "worker-specific" directory will run inside a worker as if you enabled `--pool=threads` for them,
+      ['**/tests/worker-specific/**', 'threads'],
       // run all tests in "browser" directory in an actual browser
       ["**/tests/browser/**", "browser"],
       // all other tests will run based on "browser.enabled" and "threads" options, if you didn't specify other globs
@@ -666,7 +666,7 @@ try {
 
 #### vmForks<NonProjectOption />
 
-与 `vmThreads` 池类似，但通过 [tinypool](https://github.com/tinylibs/tinypool) 使用 `child_process` 而不是 `worker_threads`。测试与主进程之间的通信速度不如 `vmThreads` 池快。与进程相关的 API（如 `process.chdir()` ）在 `vmForks` 池中可用。请注意，该池与 `vmThreads` 中列出的池具有相同的缺陷。
+与 `vmThreads` 池类似，但通过 [tinypool](https://github.com/tinylibs/tinypool) 使用 `child_process` 而不使用 `worker_threads`。测试与主进程之间的通信速度虽然不如 `vmThreads` 快。但进程相关的 API（如 `process.chdir()` ）在 `vmForks` 中却可以使用。请注意，这个与 `vmThreads` 中列出的池具有相同的缺陷。
 
 ### poolOptions<NonProjectOption /> <Badge type="info">1.0.0+</Badge>
 
@@ -1005,8 +1005,8 @@ setup 文件的路径。它们将运行在每个测试文件之前。
 
 你可以在全局设置文件中使用 `process.env.VITEST_POOL_ID`（类似整数的字符串）来区分不同的线程。
 
-:::tip 提醒
-请注意，如果你正在运行 [`--threads=false`](#threads)，则此设置文件将在同一全局范围内多次运行。 这意味着，你在每次测试之前都在访问同一个全局对象，因此请确保你做的事情没有超出你的需要。
+:::tip
+请注意，如果运行 [`--isolate=false`](#isolate-1-1-0) ，这个-设置文件将在全局范围内多次运行。这意味着每次测试前都要访问同一个全局对象，因此请确保不要重复做同一件事。
 :::
 
 比如，你可能依赖于一个全局变量：
@@ -1550,7 +1550,21 @@ test("doNotRun", () => {
 - **默认值:** `true`
 - **命令行终端:** `--browser.isolate`, `--browser.isolate=false`
 
-在每个测试之后隔离测试环境。
+在单独的 iframe 中运行每个测试。
+
+### browser.fileParallelism <Badge type="info">1.3.0+</Badge>
+
+- **类型:** `boolean`
+- **默认值:** 与 [`fileParallelism`]（#fileparallelism-110）相同
+- **命令行终端:** `--browser.fileParallelism=false`
+
+同时创建所有测试 iframe，使它们并行运行。
+
+这样就无法使用交互式 API（如点击或悬停），因为屏幕上会同时出现多个 iframe，但如果你的测试不依赖于这些 API，那么同时运行所有 iframe 可能会快很多。
+
+::: tip
+如果通过 [`browser.isolate=false`](#browserisolate) 禁用了隔离，由于测试运行器的特性，测试文件仍会一个接一个地运行。
+:::
 
 #### browser.api
 
@@ -1712,9 +1726,16 @@ export default defineConfig({
 ::: tip
 请注意，此对象上的 `plugins` 字段将被忽略。
 
-如果需要通过 pretty-format 插件扩展快照序列化器，请使用 [`expect.addSnapshotSerializer`](/api/expect#expect-addsnapshotserializer) API。
+如果你需要通过 pretty-format 插件扩展快照序列器，请使用 [`expect.addSnapshotSerializer`](/api/expect#expect-addsnapshotserializer) 或 [snapshotSerializers](#snapshotserializers-1-3-0) 选项。
 :::
 
+### snapshotSerializers<NonProjectOption /> <Badge type="info">1.3.0+</Badge>
+
+- **Type:** `string[]`
+- **Default:** `[]`
+
+A list of paths to snapshot serializer modules for snapshot testing, useful if you want add custom snapshot serializers. See [Custom Serializer](/guide/snapshot#custom-serializer) for more information.
+
 ### resolveSnapshotPath<NonProjectOption />
 
 - **类型**: `(testPath: string, snapExtension: string) => string`

guide/reporters.md

@@ -26,6 +26,23 @@ export default defineConfig({
 })
 ```
 
+某些报告器可以通过传递附加选项进行自定义。具体选项将在下面的章节中介绍。
+
+:::tip
+从 Vitest v1.3.0 开始支持
+:::
+
+```ts
+export default defineConfig({
+  test: {
+    reporters: [
+      'default',
+      ['junit', { suiteName: 'UI tests' }]
+    ],
+  },
+})
+```
+
 ## 报告器输出
 
 默认情况下，Vitest 的报告器会将输出打印到终端。当使用 `json` 、`html` 或 `junit` 报告器时，你可以在 Vite 配置文件中或通过 CLI 加入 `outputFile` [配置选项](https://vitest.dev/config/#outputfile)，将测试输出写入文件。
@@ -248,6 +265,17 @@ AssertionError: expected 5 to be 4 // Object.is equality
     </testsuite>
 </testsuites>
 ```
+输出的 XML 包含嵌套的 `testsuites` 和 `testcase` 标记。你可以使用环境变量 `VITEST_JUNIT_SUITE_NAME` 和 `VITEST_JUNIT_CLASSNAME` 分别配置它们的 `name` 和 `classname` 属性。这些属性也可通过 reporter 选项进行自定义：
+
+```ts
+export default defineConfig({
+  test: {
+    reporters: [
+      ['junit', { suiteName: 'custom suite name', classname: 'custom-classname' }]
+    ]
+  },
+})
+```
 
 输出的 XML 包含嵌套的 `testsuites` 和 `testcase` 标记。你可以使用环境变量 `VITEST_JUNIT_SUITE_NAME` 和 `VITEST_JUNIT_CLASSNAME` 分别配置它们的名称和类名属性。
 
@@ -437,6 +465,15 @@ export default defineConfig({
 
 :::
 
+### Github Actions Reporter <Badge type="info">1.3.0+</Badge>
+
+输出[工作流命令](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message)为测试失败提供注释。当 `process.env.GITHUB_ACTIONS === 'true'` 时，该报告器会自动启用，因此无需任何配置。
+
+<img alt="Github Actions" img-dark src="https://github.com/vitest-dev/vitest/assets/4232207/336cddc2-df6b-4b8a-8e72-4d00010e37f5">
+<img alt="Github Actions" img-light src="https://github.com/vitest-dev/vitest/assets/4232207/ce8447c1-0eab-4fe1-abef-d0d322290dca">
+
+
+
 ## 自定义报告器
 
 你可以使用从 NPM 安装的第三方自定义报告器，方法是在 `reporter` 选项中指定它们的软件包名称:

guide/snapshot.md

@@ -116,7 +116,7 @@ test('image snapshot', () => {
 
 你可以添加自己的逻辑来修改快照的序列化方式。像 Jest 一样，Vitest 为内置的 JavaScript 类型、HTML 元素、ImmutableJS 和 React 元素提供了默认的序列化程序。
 
-序列化模块示例：
+可以使用 [`expect.addSnapshotSerializer`](/api/expect#expect-addsnapshotserializer) 添加自定义序列器。
 
 ```ts
 expect.addSnapshotSerializer({
@@ -136,6 +136,39 @@ expect.addSnapshotSerializer({
 })
 ```
 
+我们还支持 [snapshotSerializers](/config/#snapshotserializers-1-3-0) 选项来隐式添加自定义序列化器。
+
+```ts
+import { SnapshotSerializer } from 'vitest'
+
+export default {
+  serialize(val, config, indentation, depth, refs, printer) {
+    // `printer` 是一个使用现有插件序列化数值的函数。
+    return `Pretty foo: ${printer(
+      val.foo,
+      config,
+      indentation,
+      depth,
+      refs,
+    )}`
+  },
+  test(val) {
+    return val && Object.prototype.hasOwnProperty.call(val, 'foo')
+  },
+} satisfies SnapshotSerializer
+```
+
+
+```ts
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  test: {
+    snapshotSerializers: ['path/to/custom-serializer.ts']
+  },
+})
+```
+
 如下所示的测试添加后：
 
 ```ts