Merge pull request #965 from vitest-dev/sync-ec964f36-1

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

Author: NoiseFan

.vitepress/config.ts

@@ -807,6 +807,11 @@ export default ({ mode }: { mode: string }) => {
                 link: '/guide/browser/trace-view',
                 docFooterText: '追踪查看器 | 浏览器模式',
               },
+              {
+                text: 'Playwright Traces',
+                link: '/guide/browser/playwright-traces',
+                docFooterText: 'Playwright Traces | Browser Mode',
+              },
               {
                 text: 'ARIA Snapshots',
                 link: '/guide/browser/aria-snapshots',

api/advanced/vitest.md

@@ -244,7 +244,7 @@ function start(filters?: string[]): Promise<TestRunResult>
 function standalone(): Promise<void>
 ```
 
-- **别名:**: `init` <Deprecated />
+- **别名:** `init` <Deprecated />
 
 初始化报告器和覆盖率提供者。此方法不运行任何测试。如果提供了 `--watch` 标志，Vitest 仍将运行更改的测试，即使未调用此方法。
 
@@ -696,3 +696,120 @@ export interface SourceModuleDiagnostic {
 ::: warning
 [浏览器模式](/guide/browser/) 暂不支持。
 :::
+<!-- TODO: translation -->
+## createReport <Version>5.0.0</Version> {#createreport}
+
+```ts
+function createReport(scope: string): Report
+```
+
+Creates a report that is limited to the given scope. `Report` follows Vitest's rules around [Storing artifacts on file system](/guide/advanced/reporters.html#storing-artifacts-on-file-system).
+
+`Report` provides collection of utilities for writing test results, temporary files and other artifacts on the file system. It's especially intended for third party integrations like custom reporters.
+
+All operations of `Report` are limited to given `scope`. A single report cannot interfere with other reports. Internally Vitest creates `.vitest` directory where each `scope` creates their own directory. This convention of `.vitest` directory reduces the amount of entries end-users need to specify in their `.gitignore`.
+
+```ts
+import type { Report } from 'vitest/node'
+
+const scope = 'example-yaml-reporter'
+
+// Automatically creates `<project-root>/.vitest/example-yaml-reporter/`
+// directory if it does not exist already
+const report: Report = vitest.createReport(scope)
+```
+
+### Report.root
+
+```ts
+const root: string
+```
+
+The root directory for this scope.
+
+```ts
+const report = vitest.createReport('my-json-reporter')
+
+// Is <project-root>/.vitest/my-json-reporter
+const root = report.root
+```
+
+### Report.clean
+
+```ts
+function clean(): Promise<void>
+```
+
+Clean up the report directory for this scope.
+
+```ts
+const report = vitest.createReport('my-json-reporter')
+
+// Removes everything inside <project-root>/.vitest/my-json-reporter/
+await report.clean()
+```
+
+### Report.writeFile
+
+```ts
+function writeFile(
+  filename: string,
+  content: string | Uint8Array,
+  encoding?: BufferEncoding
+): Promise<void>
+```
+
+Write a file to the report directory for this scope. By default the file will be written with UTF-8 encoding. The filename is relative to the scope directory.
+
+```ts
+const report = vitest.createReport('my-json-reporter')
+
+// Writes file to .vitest/my-json-reporter/test-report.json
+await report.writeFile('test-report.json', JSON.stringify(results))
+```
+
+### Report.readFile
+
+```ts
+function readFile(filename: string, encoding?: BufferEncoding): Promise<string>
+```
+
+Read a file from the report directory for this scope.
+
+```ts
+const report = vitest.createReport('my-json-reporter')
+
+// Reads file from .vitest/my-json-reporter/test-report.json
+const content: string = await report.readFile('test-report.json')
+```
+
+### Report.readdir
+
+```ts
+function readdir(): Promise<string[]>
+```
+
+Read contents of the report directory for this scope.
+
+```ts
+const report = vitest.createReport('my-json-reporter')
+
+// Reads contents from .vitest/my-json-reporter
+const filenames: string[] = await report.readdir()
+```
+
+### Report.delete
+
+<!-- eslint-skip -->
+```ts
+function delete(filename: string): Promise<void>
+```
+
+Delete a file from the report directory for this scope.
+
+```ts
+const report = vitest.createReport('my-json-reporter')
+
+// Deletes file from .vitest/my-json-reporter/test-report.json
+await report.delete('test-report.json')
+```

api/assert.md

@@ -36,7 +36,7 @@ test('assert.fail', () => {
 ## isOk
 
 - **类型:** `<T>(value: T, message?: string) => asserts value`
-- **Alias** `ok`
+- **别名:** `ok`
 
 断言给定的 `value` 是 true 。
 
@@ -52,7 +52,7 @@ test('assert.isOk', () => {
 ## isNotOk
 
 - **类型:** `<T>(value: T, message?: string) => void`
-- **Alias** `notOk`
+- **别名:** `notOk`
 
 断言给定的 `value` 是 false 。
 

api/browser/context.md

@@ -267,6 +267,17 @@ export const utils: {
    * Creates "Cannot find element" error. Useful for custom locators.
    */
   getElementError(selector: string, container?: Element): Error
+  /**
+   * Utilities for generating and working with ARIA trees and templates.
+   * @experimental
+   */
+  aria: {
+    generateAriaTree(rootElement: Element): AriaNode
+    renderAriaTree(root: AriaNode): string
+    renderAriaTemplate(template: AriaTemplateNode): string
+    parseAriaTemplate(text: string): AriaTemplateNode
+    matchAriaTree(root: AriaNode, template: AriaTemplateNode): { pass: boolean; resolved: string }
+  }
 }
 ```
 
@@ -337,3 +348,22 @@ utils.configurePrettyDOM({
 ::: tip
 This feature is inspired by Testing Library's [`defaultIgnore`](https://testing-library.com/docs/dom-testing-library/api-configuration/#defaultignore) configuration.
 :::
+
+### aria <Version type="experimental">5.0.0</Version> {#aria}
+
+The `aria` namespace exposes low-level utilities used by Vitest's ARIA snapshot matchers.
+
+```ts
+import { utils } from 'vitest/browser'
+
+document.body.innerHTML = `
+  <h1>Hello, World!</h1>
+  <button aria-hidden="true">Hidden</button>
+  <button>Visible</button>
+`
+const tree = utils.aria.generateAriaTree(document.body)
+const yaml = utils.aria.renderAriaNode(tree)
+console.log(yaml)
+// - heading "Hello, World!" [level=1]
+// - button "Visible""
+```

api/expect.md

@@ -1077,7 +1077,7 @@ test('spy function', () => {
 
 ## toHaveBeenCalledTimes
 
-- **类型**: `(amount: number) => Awaitable<void>`
+- **类型:** `(amount: number) => Awaitable<void>`
 
 这个断言检查函数是否被调用了特定次数。需要将一个 spy 函数传递给 `expect`。
 
@@ -1102,7 +1102,7 @@ test('spy function called two times', () => {
 
 ## toHaveBeenCalledWith
 
-- **类型**: `(...args: any[]) => Awaitable<void>`
+- **类型:** `(...args: any[]) => Awaitable<void>`
 
 这个断言检查函数是否至少一次被调用，并带有特定的参数。需要将一个 spy 函数传递给 `expect`。
 
@@ -1128,7 +1128,7 @@ test('spy function', () => {
 
 ## toHaveBeenCalledBefore
 
-- **类型**: `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => Awaitable<void>`
+- **类型:** `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => Awaitable<void>`
 
 这个断言检查一个 `Mock` 是否在另一个 `Mock` 之前被调用。
 
@@ -1147,7 +1147,7 @@ test('calls mock1 before mock2', () => {
 
 ## toHaveBeenCalledAfter
 
-- **类型**: `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => Awaitable<void>`
+- **类型:** `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => Awaitable<void>`
 
 这个断言检查一个 `Mock` 是否在另一个 `Mock` 之后被调用。
 
@@ -1166,7 +1166,7 @@ test('calls mock1 after mock2', () => {
 
 ## toHaveBeenCalledExactlyOnceWith
 
-- **类型**: `(...args: any[]) => Awaitable<void>`
+- **类型:** `(...args: any[]) => Awaitable<void>`
 
 这个断言检查函数是否恰好被调用了一次，并且带有特定的参数。需要将一个 spy 函数传递给 `expect`。
 
@@ -1190,7 +1190,7 @@ test('spy function', () => {
 
 ## toHaveBeenLastCalledWith
 
-- **类型**: `(...args: any[]) => Awaitable<void>`
+- **类型:** `(...args: any[]) => Awaitable<void>`
 
 这个断言检查函数在其最后一次调用时是否被传入了特定的参数。需要将一个 spy 函数传递给 `expect`。
 
@@ -1216,7 +1216,7 @@ test('spy function', () => {
 
 ## toHaveBeenNthCalledWith
 
-- **类型**: `(time: number, ...args: any[]) => Awaitable<void>`
+- **类型:** `(time: number, ...args: any[]) => Awaitable<void>`
 
 这个断言检查函数是否在特定的次数被调用时带有特定的参数。计数从 1 开始。因此，要检查第二次调用，我们需要写成 `.toHaveBeenNthCalledWith(2, ...)`。
 
@@ -1243,7 +1243,7 @@ test('first call of spy function called with right params', () => {
 
 ## toHaveReturned
 
-- **类型**: `() => Awaitable<void>`
+- **类型:** `() => Awaitable<void>`
 
 这个断言检查函数是否至少成功返回了一次值（ i.e. ，没有抛出错误）。需要将一个 spy 函数传递给 `expect`。
 
@@ -1267,7 +1267,7 @@ test('spy function returned a value', () => {
 
 ## toHaveReturnedTimes
 
-- **类型**: `(amount: number) => Awaitable<void>`
+- **类型:** `(amount: number) => Awaitable<void>`
 
 这个断言检查函数是否在确切的次数内成功返回了值（ i.e. ，没有抛出错误）。需要将一个 spy 函数传递给 `expect`。
 
@@ -1286,7 +1286,7 @@ test('spy function returns a value two times', () => {
 
 ## toHaveReturnedWith
 
-- **类型**: `(returnValue: any) => Awaitable<void>`
+- **类型:** `(returnValue: any) => Awaitable<void>`
 
 我们可以调用这个断言来检查函数是否至少一次成功返回了带有特定参数的值。需要将一个 spy 函数传递给 `expect`。
 
@@ -1304,7 +1304,7 @@ test('spy function returns a product', () => {
 
 ## toHaveLastReturnedWith
 
-- **类型**: `(returnValue: any) => Awaitable<void>`
+- **类型:** `(returnValue: any) => Awaitable<void>`
 
 我们可以使用这个断言来检查函数在最后一次被调用时是否成功返回了特定的值。需要将一个 spy 函数传递给 `expect`。
 
@@ -1323,7 +1323,7 @@ test('spy function returns bananas on a last call', () => {
 
 ## toHaveNthReturnedWith
 
-- **类型**: `(time: number, returnValue: any) => Awaitable<void>`
+- **类型:** `(time: number, returnValue: any) => Awaitable<void>`
 
 我们可以调用这个断言来检查函数是否在特定的调用中成功返回了带有特定参数的值。需要将一个 spy 函数传递给 `expect`。
 
@@ -1344,7 +1344,7 @@ test('spy function returns bananas on second call', () => {
 
 ## toHaveResolved
 
-- **类型**: `() => Awaitable<void>`
+- **类型:** `() => Awaitable<void>`
 
 这个断言检查函数是否至少一次成功地解析了一个值（ i.e. ，没有被拒绝）。需要将一个 spy 函数传递给 `expect`。
 
@@ -1370,7 +1370,7 @@ test('spy function resolved a value', async () => {
 
 ## toHaveResolvedTimes
 
-- **类型**: `(amount: number) => Awaitable<void>`
+- **类型:** `(amount: number) => Awaitable<void>`
 
 此断言检查函数是否已成功解析值精确次数（即未 reject）。需要将 spy 函数传递给`expect`。
 

api/test.md

@@ -614,9 +614,9 @@ test.each`
   expect(a + b).toBe(expected)
 })
 ```
-
+<!-- TODO: translation -->
 ::: tip
-Vitest 使用 Chai 的 `format` 方法处理 `$values`。如果值被截断，可在配置文件中调大 [chaiConfig.truncateThreshold](/config/chaiconfig#chaiconfig-truncatethreshold)。
+Vitest formats interpolated title values with its display formatter. If the value is too truncated, you can increase [taskTitleValueFormatTruncate](/config/tasktitlevalueformattruncate) in your config file.
 :::
 
 ## test.for

config/allowonly.md

@@ -5,8 +5,8 @@ outline: deep
 
 # allowOnly
 
-- **类型:**: `boolean`
-- **默认值:**: `!process.env.CI`
+- **类型:** `boolean`
+- **默认值:** `!process.env.CI`
 - **命令行终端:** `--allowOnly`, `--allowOnly=false`
 
 默认情况下，Vitest 不允许在持续集成（CI）环境中运行带有 [`only`](/api/test#test-only) 标记的测试。相反，在本地开发环境中，Vitest 允许运行这些测试。

config/browser/trace.md

@@ -10,6 +10,8 @@ outline: deep
 - **默认值:** `'off'`
 
 捕获浏览器测试运行的追踪记录。你可以通过 [Playwright Trace Viewer](https://trace.playwright.dev/) 预览追踪文件。
+<!-- TODO: translation -->
+See [Playwright Traces](/guide/browser/playwright-traces) for the full workflow.
 
 该选项支持以下取值：