feat: support aria snapshot

docs/api/expect.md

@@ -964,6 +964,75 @@ The same as [`toMatchSnapshot`](#tomatchsnapshot), but expects the same value as
 
 The same as [`toMatchInlineSnapshot`](#tomatchinlinesnapshot), but expects the same value as [`toThrow`](#tothrow).
 
+## toMatchAriaSnapshot {#tomatcharisnapshot}
+
+- **Type:** `() => void`
+
+Captures the accessibility tree of a DOM element and compares it against a stored snapshot. Inspired by [Playwright's aria snapshots](https://playwright.dev/docs/aria-snapshots).
+
+The snapshot uses a YAML-like format describing the accessible roles, names, and states of the element tree.
+
+```ts
+import { expect, test } from 'vitest'
+
+test('navigation accessibility', () => {
+  document.body.innerHTML = `
+    <nav aria-label="Actions">
+      <button>Save</button>
+      <button>Cancel</button>
+    </nav>
+  `
+  expect(document.querySelector('nav')).toMatchAriaSnapshot()
+})
+```
+
+On first run, Vitest generates a snapshot entry like:
+
+```
+- navigation "Actions":
+  - button: Save
+  - button: Cancel
+```
+
+See the [Aria Snapshots guide](/guide/snapshot#aria-snapshots) for more details.
+
+## toMatchAriaInlineSnapshot {#tomatchariaInlinesnapshot}
+
+- **Type:** `(snapshot?: string) => void`
+
+Same as [`toMatchAriaSnapshot`](#tomatcharisnapshot), but stores the snapshot inline in the test file.
+
+```ts
+import { expect, test } from 'vitest'
+
+test('user profile', () => {
+  expect(document.body).toMatchAriaInlineSnapshot(`
+    - heading "Dashboard" [level=1]
+    - button /User \\d+/: Profile
+  `)
+})
+```
+
+## toMatchDomainSnapshot <Badge type="warning">experimental</Badge> {#tomatchdomainsnapshot}
+
+- **Type:** `(domain: string, hint?: string) => void`
+
+Matches a value against a stored snapshot using a registered [domain snapshot adapter](/guide/snapshot#custom-snapshot-domain). The `domain` argument is the adapter's `name`.
+
+```ts
+expect(value).toMatchDomainSnapshot('my-domain')
+```
+
+## toMatchDomainInlineSnapshot <Badge type="warning">experimental</Badge> {#tomatchdomaininlinesnapshot}
+
+- **Type:** `(snapshot: string, domain: string, hint?: string) => void`
+
+Same as [`toMatchDomainSnapshot`](#tomatchdomainsnapshot), but stores the snapshot inline in the test file.
+
+```ts
+expect(value).toMatchDomainInlineSnapshot(`...`, `my-domain`)
+```
+
 ## toHaveBeenCalled
 
 - **Type:** `() => Awaitable<void>`
@@ -2116,6 +2185,19 @@ If you are adding custom serializers, you should call this method inside [`setup
 If you previously used Vue CLI with Jest, you might want to install [jest-serializer-vue](https://npmx.dev/package/jest-serializer-vue). Otherwise, your snapshots will be wrapped in a string, which cases `"` to be escaped.
 :::
 
+## expect.addSnapshotDomain <Badge type="warning">experimental</Badge> {#expect-addsnapshotdomain}
+
+- **Type:** `(adapter: DomainSnapshotAdapter) => void`
+
+Registers a [domain snapshot adapter](/guide/snapshot#custom-snapshot-domain) for use with `toMatchDomainSnapshot` and `toMatchDomainInlineSnapshot`. Call this in [`setupFiles`](/config/setupfiles).
+
+```ts
+import { expect } from 'vitest'
+import { kvAdapter } from './kv-adapter'
+
+expect.addSnapshotDomain(kvAdapter)
+```
+
 ## expect.extend
 
 - **Type:** `(matchers: MatchersObject) => void`

docs/guide/snapshot.md

@@ -118,6 +118,64 @@ test('button looks correct', async () => {
 
 This captures screenshots and compares them against reference images to detect unintended visual changes. Learn more in the [Visual Regression Testing guide](/guide/browser/visual-regression-testing).
 
+## Aria Snapshots
+
+Aria snapshots capture the accessibility tree of a DOM element and compare it against a stored template. Inspired by [Playwright's aria snapshots](https://playwright.dev/docs/aria-snapshots), they provide a semantic alternative to visual regression testing — asserting structure and meaning rather than pixels.
+
+- Works in jsdom, happy-dom, and [Browser Mode](/guide/browser/)
+- Supports regex patterns in names and text (`/User \d+/`)
+- Hand-edited patterns survive `--update` on partial match
+
+### File snapshots
+
+```ts
+import { expect, test } from 'vitest'
+
+test('navigation structure', () => {
+  const nav = document.querySelector('nav')
+  expect(nav).toMatchAriaSnapshot()
+})
+```
+
+On first run, Vitest generates a snapshot file entry like:
+
+```
+- navigation "Actions":
+  - button: Save
+  - button: Cancel
+```
+
+### Inline snapshots
+
+```ts
+import { expect, test } from 'vitest'
+
+test('navigation structure', () => {
+  expect(document.body).toMatchAriaInlineSnapshot(`
+    - navigation "Actions":
+      - button: Save
+      - button: Cancel
+  `)
+})
+```
+
+### Browser Mode
+
+In [Browser Mode](/guide/browser/), use `expect.element()` to automatically retry until the DOM accessibility tree matches the snapshot:
+
+```ts
+await expect.element(page.getByRole('navigation')).toMatchAriaInlineSnapshot(`
+  - button: Save
+  - button: Cancel
+`)
+```
+
+The matcher re-queries the element and re-captures the accessibility tree on each attempt until it matches or the timeout is reached.
+
+Retry only applies when comparing against an existing snapshot. On first run (snapshot creation) or with `--update`, the matcher captures once and writes immediately — no timeout wait.
+
+See [`toMatchAriaSnapshot`](/api/expect#tomatcharisnapshot) and [`toMatchAriaInlineSnapshot`](/api/expect#tomatchariaInlinesnapshot) for the full API reference.
+
 ## Custom Serializer
 
 You can add your own logic to alter how your snapshots are serialized. Like Jest, Vitest has default serializers for built-in JavaScript types, HTML elements, ImmutableJS and for React elements.
@@ -200,6 +258,148 @@ Pretty foo: Object {
 
 We are using Jest's `pretty-format` for serializing snapshots. You can read more about it here: [pretty-format](https://github.com/facebook/jest/blob/main/packages/pretty-format/README.md#serialize).
 
+## Custom Snapshot Domain <Badge type="warning">experimental</Badge> {#custom-snapshot-domain}
+
+Custom serializers control how values are _rendered_ into snapshot strings, but comparison is still string equality. A **domain snapshot adapter** goes further — it owns the entire comparison pipeline: how to capture a value, render it, parse a stored snapshot, and match them semantically.
+
+This is useful when snapshot comparison needs to be smarter than `===`. For example, the built-in [aria snapshots](#aria-snapshots) use a domain adapter to support regex patterns and preserve hand-edited patterns when running with `--update` — the adapter's `match` method can return a `mergedExpected` string so only the changed literal parts are overwritten.
+
+### The adapter interface
+
+A domain adapter implements four methods:
+
+```ts
+import type { DomainSnapshotAdapter } from '@vitest/snapshot'
+
+const myAdapter: DomainSnapshotAdapter<Captured, Expected> = {
+  name: 'my-domain',
+
+  // Extract structured data from the received value
+  capture(received) { /* ... */ },
+
+  // Render captured data as the snapshot string (what gets stored)
+  render(captured) { /* ... */ },
+
+  // Parse a stored snapshot string into a structured expected value
+  parseExpected(input) { /* ... */ },
+
+  // Compare captured vs expected, return pass/fail and diff info
+  match(captured, expected) { /* ... */ },
+}
+```
+
+### Registration
+
+Register an adapter in your test setup file:
+
+```ts [setup.ts]
+import { expect } from 'vitest'
+
+expect.addSnapshotDomain(myAdapter)
+```
+
+Then use it in tests via [`toMatchDomainSnapshot`](/api/expect#tomatchdomainsnapshot) or [`toMatchDomainInlineSnapshot`](/api/expect#tomatchdomaininlinesnapshot):
+
+```ts
+expect(value).toMatchDomainSnapshot('my-domain')
+expect(value).toMatchDomainInlineSnapshot(`key=value`, 'my-domain')
+```
+
+### Example: key-value adapter
+
+A minimal adapter that stores objects as `key=value` lines, with regex pattern support ([full source](https://github.com/vitest-dev/vitest/blob/main/test/snapshots/test/fixtures/domain/basic.ts)):
+
+```ts [kv-adapter.ts]
+import type {
+  DomainMatchResult,
+  DomainSnapshotAdapter,
+} from '@vitest/snapshot'
+
+interface KVCaptured {
+  entries: { key: string; value: string }[]
+}
+
+interface KVExpected {
+  entries: { key: string; value: string | RegExp }[]
+}
+
+export const kvAdapter: DomainSnapshotAdapter<KVCaptured, KVExpected> = {
+  name: 'kv',
+
+  capture(received) {
+    const entries = Object.entries(received as Record<string, string>)
+      .map(([key, value]) => ({ key, value: String(value) }))
+    return { entries }
+  },
+
+  render(captured) {
+    return captured.entries.map(e => `${e.key}=${e.value}`).join('\n')
+  },
+
+  parseExpected(input) {
+    const entries = input.trim().split('\n').map((line) => {
+      const eq = line.indexOf('=')
+      const key = line.slice(0, eq)
+      const raw = line.slice(eq + 1)
+      const value = (raw.startsWith('/') && raw.endsWith('/'))
+        ? new RegExp(raw.slice(1, -1))
+        : raw
+      return { key, value }
+    })
+    return { entries }
+  },
+
+  match(captured, expected): DomainMatchResult {
+    let allPass = true
+    for (let i = 0; i < captured.entries.length; i++) {
+      const cap = captured.entries[i]
+      const exp = expected.entries[i]
+      if (!exp) {
+        allPass = false
+      }
+      else if (exp.value instanceof RegExp) {
+        if (!exp.value.test(cap.value)) allPass = false
+      }
+      else if (cap.value !== exp.value) {
+        allPass = false
+      }
+    }
+    return {
+      pass: allPass,
+      // Optionally return mergedExpected, actual, expected for diffs
+      // and pattern-preserving updates
+      // actual: "...",
+      // expected: "...",
+      // mergedExpected: "...",
+    }
+  },
+}
+```
+
+```ts [setup.ts]
+import { expect } from 'vitest'
+import { kvAdapter } from './kv-adapter'
+
+expect.addSnapshotDomain(kvAdapter)
+```
+
+```ts [example.test.ts]
+import { expect, test } from 'vitest'
+
+test('user data', () => {
+  const user = { name: 'Alice', score: '42' }
+  expect(user).toMatchDomainSnapshot('kv')
+})
+
+test('user data inline', () => {
+  const user = { name: 'Alice', score: '42' }
+  expect(user).toMatchDomainInlineSnapshot(`
+    name=Alice
+    score=/\\d+/
+  `, 'kv')
+})
+```
+
 ## Difference from Jest
 
 Vitest provides an almost compatible Snapshot feature with [Jest's](https://jestjs.io/docs/snapshot-testing) with a few exceptions:

packages/snapshot/package.json

@@ -25,6 +25,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./aria": {
+      "types": "./dist/aria.d.ts",
+      "default": "./dist/aria.js"
+    },
     "./environment": {
       "types": "./dist/environment.d.ts",
       "default": "./dist/environment.js"

packages/snapshot/rollup.config.js

@@ -17,6 +17,7 @@ const external = [
 
 const entries = {
   index: 'src/index.ts',
+  aria: 'src/aria.ts',
   environment: 'src/environment.ts',
   manager: 'src/manager.ts',
 }