feat(browser): introduce toMatchScreenshot for Visual Regression Testing (#8041)

Author: macarie

docs/.vitepress/config.ts

@@ -291,6 +291,11 @@ export default ({ mode }: { mode: string }) => {
                 link: '/guide/browser/multiple-setups',
                 docFooterText: 'Multiple Setups | Browser Mode',
               },
+              {
+                text: 'Visual Regression Testing',
+                link: '/guide/browser/visual-regression-testing',
+                docFooterText: 'Visual Regression Testing | Browser Mode',
+              },
             ],
           },
           {

docs/guide/browser/assertion-api.md

@@ -1067,3 +1067,216 @@ await expect.element(queryByTestId('parent')).toHaveSelection('ected text')
 await expect.element(queryByTestId('prev')).not.toHaveSelection()
 await expect.element(queryByTestId('next')).toHaveSelection('ne')
 ```
+
+## toMatchScreenshot <Badge type="warning">experimental</Badge>
+
+```ts
+function toMatchScreenshot(
+  options?: ScreenshotMatcherOptions,
+): Promise<void>
+function toMatchScreenshot(
+  name?: string,
+  options?: ScreenshotMatcherOptions,
+): Promise<void>
+```
+
+::: tip
+The `toMatchScreenshot` assertion can be configured globally in your
+[Vitest config](/guide/browser/config#browser-expect-tomatchscreenshot).
+:::
+
+This assertion allows you to perform visual regression testing by comparing
+screenshots of elements or pages against stored reference images.
+
+When differences are detected beyond the configured threshold, the test fails.
+To help identify the changes, the assertion generates:
+
+- The actual screenshot captured during the test
+- The expected reference screenshot
+- A diff image highlighting the differences (when possible)
+
+::: warning Screenshots Stability
+The assertion automatically retries taking screenshots until two consecutive
+captures yield the same result. This helps reduce flakiness caused by
+animations, loading states, or other dynamic content. You can control this
+behavior with the `timeout` option.
+
+However, browser rendering can vary across:
+
+- Different browsers and browser versions
+- Operating systems (Windows, macOS, Linux)
+- Screen resolutions and pixel densities
+- GPU drivers and hardware acceleration
+- Font rendering and system fonts
+
+It is recommended to read the
+[Visual Regression Testing guide](/guide/browser/visual-regression-testing) to
+implement this testing strategy efficiently.
+:::
+
+::: tip
+When a screenshot comparison fails due to **intentional changes**, you can
+update the reference screenshot by pressing the `u` key in watch mode, or by
+running tests with the `-u` or `--update` flags.
+:::
+
+```html
+<button data-testid="button">Fancy Button</button>
+```
+
+```ts
+// basic usage, auto-generates screenshot name
+await expect.element(getByTestId('button')).toMatchScreenshot()
+
+// with custom name
+await expect.element(getByTestId('button')).toMatchScreenshot('fancy-button')
+
+// with options
+await expect.element(getByTestId('button')).toMatchScreenshot({
+  comparatorName: 'pixelmatch',
+  comparatorOptions: {
+    allowedMismatchedPixelRatio: 0.01,
+  },
+})
+
+// with both name and options
+await expect.element(getByTestId('button')).toMatchScreenshot('fancy-button', {
+  comparatorName: 'pixelmatch',
+  comparatorOptions: {
+    allowedMismatchedPixelRatio: 0.01,
+  },
+})
+```
+
+### Options
+
+- `comparatorName: "pixelmatch" = "pixelmatch"`
+
+  The name of the algorithm/library used for comparing images.
+
+  Currently, [`"pixelmatch"`](https://github.com/mapbox/pixelmatch) is the only
+  supported comparator.
+
+- `comparatorOptions: object`
+
+  These options allow changing the behavior of the comparator. What properties
+  can be set depends on the chosen comparator algorithm.
+
+  Vitest has set default values out of the box, but they can be overridden.
+
+  - [`"pixelmatch"` options](#pixelmatch-comparator-options)
+
+  ::: warning
+  **Always explicitly set `comparatorName` to get proper type inference for
+  `comparatorOptions`**.
+
+  Without it, TypeScript won't know which options are valid:
+
+  ```ts
+  // ❌ TypeScript can't infer the correct options
+  await expect.element(button).toMatchScreenshot({
+    comparatorOptions: {
+      // might error when new comparators are added
+      allowedMismatchedPixelRatio: 0.01,
+    },
+  })
+
+  // ✅ TypeScript knows these are pixelmatch options
+  await expect.element(button).toMatchScreenshot({
+    comparatorName: 'pixelmatch',
+    comparatorOptions: {
+      allowedMismatchedPixelRatio: 0.01,
+    },
+  })
+  ```
+  :::
+
+- `screenshotOptions: object`
+
+  The same options allowed by
+  [`locator.screenshot()`](/guide/browser/locators.html#screenshot), except for:
+
+  - `'base64'`
+  - `'path'`
+  - `'save'`
+  - `'type'`
+
+- `timeout: number = 5_000`
+
+  Time to wait until a stable screenshot is found.
+
+  Setting this value to `0` disables the timeout, but if a stable screenshot
+  can't be determined the process will not end.
+
+#### `"pixelmatch"` comparator options
+
+The following options are available when using the `"pixelmatch"` comparator:
+
+- `allowedMismatchedPixelRatio: number | undefined = undefined`
+
+  The maximum allowed ratio of differing pixels between the captured screenshot
+  and the reference image.
+
+  Must be a value between `0` and `1`.
+
+  For example, `allowedMismatchedPixelRatio: 0.02` means the test will pass
+  if up to 2% of pixels differ, but fail if more than 2% differ.
+
+- `allowedMismatchedPixels: number | undefined = undefined`
+
+  The maximum number of pixels that are allowed to differ between the captured
+  screenshot and the stored reference image.
+
+  If set to `undefined`, any non-zero difference will cause the test to fail.
+
+  For example, `allowedMismatchedPixels: 10` means the test will pass if 10 or
+  fewer pixels differ, but fail if 11 or more differ.
+
+- `threshold: number = 0.1`
+
+  Acceptable perceived color difference between the same pixel in two images.
+
+  Value ranges from `0` (strict) to `1` (very lenient). Lower values mean small
+  differences will be detected.
+
+  The comparison uses the [YIQ color space](https://en.wikipedia.org/wiki/YIQ).
+
+- `includeAA: boolean = false`
+
+  If `true`, disables detection and ignoring of anti-aliased pixels.
+
+- `alpha: number = 0.1`
+
+  Blending level of unchanged pixels in the diff image.
+
+  Ranges from `0` (white) to `1` (original brightness).
+
+- `aaColor: [r: number, g: number, b: number] = [255, 255, 0]`
+
+  Color used for anti-aliased pixels in the diff image.
+
+- `diffColor: [r: number, g: number, b: number] = [255, 0, 0]`
+
+  Color used for differing pixels in the diff image.
+
+- `diffColorAlt: [r: number, g: number, b: number] | undefined = undefined`
+
+  Optional alternative color for dark-on-light differences, to help show what's
+  added vs. removed.
+
+  If not set, `diffColor` is used for all differences.
+
+- `diffMask: boolean = false`
+
+  If `true`, shows only the diff as a mask on a transparent background, instead
+  of overlaying it on the original image.
+
+  Anti-aliased pixels won't be shown (if detected).
+
+::: warning
+When both `allowedMismatchedPixels` and `allowedMismatchedPixelRatio` are set,
+the more restrictive value is used.
+
+For example, if you allow 100 pixels or 2% ratio, and your image has 10,000
+pixels, the effective limit would be 100 pixels instead of 200.
+:::

docs/guide/browser/config.md

@@ -325,3 +325,152 @@ The timeout in milliseconds. If connection to the browser takes longer, the test
 ::: info
 This is the time it should take for the browser to establish the WebSocket connection with the Vitest server. In normal circumstances, this timeout should never be reached.
 :::
+
+## browser.expect
+
+- **Type:** `ExpectOptions`
+
+### browser.expect.toMatchScreenshot
+
+Default options for the
+[`toMatchScreenshot` assertion](/guide/browser/assertion-api.html#tomatchscreenshot).
+These options will be applied to all screenshot assertions.
+
+::: tip
+Setting global defaults for screenshot assertions helps maintain consistency
+across your test suite and reduces repetition in individual tests. You can still
+override these defaults at the assertion level when needed for specific test cases.
+:::
+
+```ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    browser: {
+      enabled: true,
+      expect: {
+        toMatchScreenshot: {
+          comparatorName: 'pixelmatch',
+          comparatorOptions: {
+            threshold: 0.2,
+            allowedMismatchedPixels: 100,
+          },
+          resolveScreenshotPath: ({ arg, browserName, ext, testFileName }) =>
+            `custom-screenshots/${testFileName}/${arg}-${browserName}${ext}`,
+        },
+      },
+    },
+  },
+})
+```
+
+[All options available in the `toMatchScreenshot` assertion](/guide/browser/assertion-api#options)
+can be configured here. Additionally, two path resolution functions are
+available: `resolveScreenshotPath` and `resolveDiffPath`.
+
+#### browser.expect.toMatchScreenshot.resolveScreenshotPath
+
+- **Type:** `(data: PathResolveData) => string`
+- **Default output:** `` `${root}/${testFileDirectory}/${screenshotDirectory}/${testFileName}/${arg}-${browserName}-${platform}${ext}` ``
+
+A function to customize where reference screenshots are stored. The function
+receives an object with the following properties:
+
+- `arg: string`
+
+  Path **without** extension, sanitized and relative to the test file.
+
+  This comes from the arguments passed to `toMatchScreenshot`; if called
+  without arguments this will be the auto-generated name.
+
+  ```ts
+  test('calls `onClick`', () => {
+    expect(locator).toMatchScreenshot()
+    // arg = "calls-onclick-1"
+  })
+
+  expect(locator).toMatchScreenshot('foo/bar/baz.png')
+  // arg = "foo/bar/baz"
+
+  expect(locator).toMatchScreenshot('../foo/bar/baz.png')
+  // arg = "foo/bar/baz"
+  ```
+
+- `ext: string`
+
+  Screenshot extension, with leading dot.
+
+  This can be set through the arguments passed to `toMatchScreenshot`, but
+  the value will fall back to `'.png'` if an unsupported extension is used.
+
+- `browserName: string`
+
+  The instance's browser name.
+
+- `platform: NodeJS.Platform`
+
+  The value of
+  [`process.platform`](https://nodejs.org/docs/v22.16.0/api/process.html#processplatform).
+
+- `screenshotDirectory: string`
+
+  The value provided to
+  [`browser.screenshotDirectory`](/guide/browser/config#browser-screenshotdirectory),
+  if none is provided, its default value.
+
+- `root: string`
+
+  Absolute path to the project's [`root`](/config/#root).
+
+- `testFileDirectory: string`
+
+  Path to the test file, relative to the project's [`root`](/config/#root).
+
+- `testFileName: string`
+
+  The test's filename.
+
+- `testName: string`
+
+  The [`test`](/api/#test)'s name, including parent
+  [`describe`](/api/#describe), sanitized.
+
+- `attachmentsDir: string`
+
+  The value provided to [`attachmentsDir`](/config/#attachmentsdir), if none is
+  provided, its default value.
+
+For example, to group screenshots by browser:
+
+```ts
+resolveScreenshotPath: ({ arg, browserName, ext, root, testFileName }) =>
+  `${root}/screenshots/${browserName}/${testFileName}/${arg}${ext}`
+```
+
+#### browser.expect.toMatchScreenshot.resolveDiffPath
+
+- **Type:** `(data: PathResolveData) => string`
+- **Default output:** `` `${root}/${attachmentsDir}/${testFileDirectory}/${testFileName}/${arg}-${browserName}-${platform}${ext}` ``
+
+A function to customize where diff images are stored when screenshot comparisons
+fail. Receives the same data object as
+[`resolveScreenshotPath`](#browser-expect-tomatchscreenshot-resolvescreenshotpath).
+
+For example, to store diffs in a subdirectory of attachments:
+
+```ts
+resolveDiffPath: ({ arg, attachmentsDir, browserName, ext, root, testFileName }) =>
+  `${root}/${attachmentsDir}/screenshot-diffs/${testFileName}/${arg}-${browserName}${ext}`
+```
+
+::: tip
+To have a better type safety when using built-in providers, you should reference
+one of these types (for provider that you are using) in your
+[config file](/config/):
+
+```ts
+/// <reference types="@vitest/browser/providers/playwright" />
+/// <reference types="@vitest/browser/providers/webdriverio" />
+```
+:::