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

advanced/api/test-suite.md

@@ -198,14 +198,21 @@ describe('collection failed', () => {
 ```ts
 function meta(): TaskMeta
 ```
+<<<<<<< HEAD
 在执行或收集过程中附加到套件的自定义[元数据](/advanced/metadata)。在测试运行期间，可以通过向 `task.meta` 对象分配属性来附加 meta：
+=======
 
-```ts {5,10}
+Custom [metadata](/advanced/metadata) that was attached to the suite during its execution or collection. The meta can be attached by assigning a property to the `suite.meta` object during a test run:
+>>>>>>> a216aa687812e7b0b12168ff92dee69c6f396d92
+
+```ts {7,12}
 import { test } from 'vitest'
+import { getCurrentSuite } from 'vitest/suite'
 
-describe('the validation works correctly', (task) => {
+describe('the validation works correctly', () => {
   // assign "decorated" during collection
-  task.meta.decorated = false
+  const { suite } = getCurrentSuite()
+  suite!.meta.decorated = true
 
   test('some test', ({ task }) => {
     // assign "decorated" during test run, it will be available

guide/browser/config.md

@@ -476,3 +476,116 @@ resolveScreenshotPath: ({ arg, browserName, ext, root, testFileName }) =>
 resolveDiffPath: ({ arg, attachmentsDir, browserName, ext, root, testFileName }) =>
   `${root}/${attachmentsDir}/screenshot-diffs/${testFileName}/${arg}-${browserName}${ext}`
 ```
+
+#### browser.expect.toMatchScreenshot.comparators
+
+- **Type:** `Record<string, Comparator>`
+
+Register custom screenshot comparison algorithms, like [SSIM](https://en.wikipedia.org/wiki/Structural_similarity_index_measure) or other perceptual similarity metrics.
+
+To create a custom comparator, you need to register it in your config. If using TypeScript, declare its options in the `ScreenshotComparatorRegistry` interface.
+
+```ts
+import { defineConfig } from 'vitest/config'
+
+// 1. Declare the comparator's options type
+declare module 'vitest/browser' {
+  interface ScreenshotComparatorRegistry {
+    myCustomComparator: {
+      sensitivity?: number
+      ignoreColors?: boolean
+    }
+  }
+}
+
+// 2. Implement the comparator
+export default defineConfig({
+  test: {
+    browser: {
+      expect: {
+        toMatchScreenshot: {
+          comparators: {
+            myCustomComparator: async (
+              reference,
+              actual,
+              {
+                createDiff, // always provided by Vitest
+                sensitivity = 0.01,
+                ignoreColors = false,
+              }
+            ) => {
+              // ...algorithm implementation
+              return { pass, diff, message }
+            },
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+Then use it in your tests:
+
+```ts
+await expect(locator).toMatchScreenshot({
+  comparatorName: 'myCustomComparator',
+  comparatorOptions: {
+    sensitivity: 0.08,
+    ignoreColors: true,
+  },
+})
+```
+
+**Comparator Function Signature:**
+
+```ts
+type Comparator<Options> = (
+  reference: {
+    metadata: { height: number; width: number }
+    data: TypedArray
+  },
+  actual: {
+    metadata: { height: number; width: number }
+    data: TypedArray
+  },
+  options: {
+    createDiff: boolean
+  } & Options
+) => Promise<{
+  pass: boolean
+  diff: TypedArray | null
+  message: string | null
+}> | {
+  pass: boolean
+  diff: TypedArray | null
+  message: string | null
+}
+```
+
+The `reference` and `actual` images are decoded using the appropriate codec (currently only PNG). The `data` property is a flat `TypedArray` (`Buffer`, `Uint8Array`, or `Uint8ClampedArray`) containing pixel data in RGBA format:
+
+- **4 bytes per pixel**: red, green, blue, alpha (from `0` to `255` each)
+- **Row-major order**: pixels are stored left-to-right, top-to-bottom
+- **Total length**: `width × height × 4` bytes
+- **Alpha channel**: always present. Images without transparency have alpha values set to `255` (fully opaque)
+
+::: tip Performance Considerations
+The `createDiff` option indicates whether a diff image is needed. During [stable screenshot detection](/guide/browser/visual-regression-testing#how-visual-tests-work), Vitest calls comparators with `createDiff: false` to avoid unnecessary work.
+
+**Respect this flag to keep your tests fast**.
+:::
+
+::: warning Handle Missing Options
+The `options` parameter in `toMatchScreenshot()` is optional, so users might not provide all your comparator options. Always make them optional with default values:
+
+```ts
+myCustomComparator: (
+  reference,
+  actual,
+  { createDiff, threshold = 0.1, maxDiff = 100 },
+) => {
+  // ...comparison logic
+}
+```
+:::

guide/browser/visual-regression-testing.md

@@ -101,7 +101,29 @@ $ vitest --update
 
 提交前务必核对更新后的截图，确保改动符合预期。
 
+<<<<<<< HEAD
 ## 配置可视化测试
+=======
+## How Visual Tests Work
+
+Visual regression tests need stable screenshots to compare against. But pages aren't instantly stable as images load, animations finish, fonts render, and layouts settle.
+
+Vitest handles this automatically through "Stable Screenshot Detection":
+
+1. Vitest takes a first screenshot (or uses the reference screenshot if available) as baseline
+1. It takes another screenshot and compares it with the baseline
+    - If the screenshots match, the page is stable and testing continues
+    - If they differ, Vitest uses the newest screenshot as the baseline and repeats
+1. This continues until stability is achieved or the timeout is reached
+
+This ensures that transient visual changes (like loading spinners or animations) don't cause false failures. If something never stops animating though, you'll hit the timeout, so consider [disabling animations during testing](#disable-animations).
+
+If a stable screenshot is captured after retries (one or more) and a reference screenshot exists, Vitest performs a final comparison with the reference using `createDiff: true`. This will generate a diff image if they don't match.
+
+During stability detection, Vitest calls comparators with `createDiff: false` since it only needs to know if screenshots match. This keeps the detection process fast.
+
+## Configuring Visual Tests
+>>>>>>> a216aa687812e7b0b12168ff92dee69c6f396d92
 
 ### 全局配置
 

guide/reporters.md

@@ -581,6 +581,18 @@ export default defineConfig({
 })
 ```
 
+If you are using [Annotations API](/guide/test-annotations), the reporter will automatically inline them in the GitHub UI. You can disable this by setting `displayAnnotations` option to `false`:
+
+```ts
+export default defineConfig({
+  test: {
+    reporters: [
+      ['github-actions', { displayAnnotations: false }],
+    ],
+  },
+})
+```
+
 ### Blob Reporter
 
 将测试结果存储在计算机上，以便以后可以使用 [`--merge-reports`](/guide/cli#merge-reports) 命令进行合并。