feat(experimental): support aria snapshot by hi-ogawa · Pull Request #9668 · vitest-dev/vitest

hi-ogawa · 2026-02-15T05:19:56Z

Description

Closes [Brower Mode] Support aria snapshot matcher #6933
Closes Expose updateSnapshot via SnapshotState #9481
Requires feat: add aria snapshot utilities ivya#8

Adds toMatchAriaSnapshot() and toMatchAriaInlineSnapshot() matchers for asserting DOM accessibility trees, inspired by Playwright's aria snapshot feature. Core logic of aria tree generation, parsing, matching are entirely implemented on ivya vitest-dev/ivya#8 as Aria related runtime utility lives there.

Under the hood, this PR also introduces domain snapshot API in Vitest core to allow extending comparison mechanism beyond exact string equality. The simple example is added as a test case and also documented to illustrate the idea. However, I'd treat this API being "experimental" since I haven't too deeply thought through the API shape beyond what I minimally needed for implementing aria snapshot.

API

// file
expect(document.querySelector('nav')).toMatchAriaSnapshot()

// inline
expect(document.body).toMatchAriaInlineSnapshot(`
  - paragraph: Original
  - button "1234": Pattern
`)

// with expect.element
await expect.element(page.getByRole('navigation')).toMatchAriaInlineSnapshot(`
  - button: Save
  - button: Cancel
`)

// with expect.poll (technically works but not documented specifically)
await expect.poll(() => document.body).toMatchAriaInlineSnapshot(`
  - heading "Dashboard" [level=1]
`)

Example

Given HTML like

<p>Original</p>
<button aria-label="1234">Pattern</button>
<p>Extra</p>

Initially generated snapshot looks like:

- paragraph: Original
- button "1234": Pattern
- paragraph: Extra

Snapshot can be manually edited to include regex pattern or remove some part and snapshot assertion continues to pass:

- paragraph: Original
- button /\d+/: Pattern

Now when actual HTML changes to:

<p>Changes</p>        👈 (before: "Original", after: "Changed")
<button aria-label="1234">Pattern</button>
<p>Extra</p>

Snapshot would now fail, but the error diff normalizes partially matching part:

- - paragraph: Original
+ - paragraph: Changed
  - button /\d+/: Pattern

When forcing the snapshot update via --update, newly generated snapshot would reflect the same error diff, which means manually edited part is preserved:

- paragraph: Changed
- button /\d+/: Pattern

TODO

test yaml parse error (the error from adapter.parseExpected)
always require stable snapshot
- more tests
- also document
document feat: support /children directive in aria tree template ivya#10
document feat: add minimal YAML parser for aria snapshot templates ivya#13
Create follow up issues

Questions

Should poll snapshot with --update wait for stable snapshot?
- ~~TODO: new heuristics and new option? employ similar strategy as toMatchScreenshot?~~
  Yes, it should. We can simplify pool more and wait until stable on "new" (initial snaphsot) and "all" (--update) cases
~~How to pull in yaml?~~ (fixed by feat: add minimal YAML parser for aria snapshot templates ivya#13)
- Aria snapshot requires yaml parser and it's now bundled through @vitest/browser/dist/expect-element.js. The package yaml is huge around 100kb. This caused expect-element.js to go from 23kb to 140kb. Should we try code split and lazily load on runtime?
- domain snapshot itself is synchronous. lazy load requires making toMatchAriaSnapshot specifically asynchronous, which is technically possible. Or we can make explicit opt-in/out flag to lazy load early during runtime.
- Or we (AI) can hand-roll simplified yaml parser (note that yaml serializer is already hand-rolled partly by playwright).
  feat: add minimal YAML parser for aria snapshot templates ivya#13

Follow-up considered

"strict matching" via /children property (port https://playwright.dev/docs/aria-snapshots#strict-matching)
- feat: support /children directive in aria tree template ivya#10
support "raw file" output like toMatchFileSnapshot
migrate internal to use snaphsot domain like mechanism and support poll
config to register snapshot domain similar to snapshotSerializers feat(experimental): support aria snapshot #9668 (comment)

TODO

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

It's really useful if your PR references an issue where it is discussed ahead of time. If the feature is substantial or introduces breaking changes without a discussion, PR might be closed.
Ideally, include a test that fails without this PR but passes with it.
Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example.
Please check Allow edits by maintainers to make review process faster. Note that this option is not available for repositories that are owned by Github organizations.

Tests

Run the tests with pnpm test:ci.

Documentation

If you introduce new functionality, document it. You can run documentation with pnpm run docs command.

Changesets

Changes in changelog are generated from PR name. Please, make sure that it explains your changes in an understandable manner. Please, prefix changeset messages with feat:, fix:, perf:, docs:, or chore:.

netlify · 2026-02-15T08:08:06Z

✅ Deploy Preview for vitest-dev ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`d5c1a28`
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/69cce9bc5a1abf0007794baf
😎 Deploy Preview	https://deploy-preview-9668--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

AriPerkkio

First review for docs only:

docs/guide/snapshot.md

AriPerkkio · 2026-03-22T10:33:23Z

docs/guide/snapshot.md

+  expect(user).toMatchDomainInlineSnapshot(`
+    name=Alice
+    score=/\\d+/
+  `, 'kv')
+})


What's the equivalent of current user flow of generating the first snapshot?

// User writes expect(user).toMatchInlineSnapshot(); // note, no args // Snapshot generates into expect(user).toMatchInlineSnapshot(` { "name": ... ... } `);

Do they pass empty string there?

expect(user).toMatchDomainInlineSnapshot("", "kv");

Or does that run into comparison error "" does not match 'name=...?

This is one of unpolished parts of toMatchDomainInlineSnapshot. It currently requires toMatchDomainInlineSnapshot("", "kv") as an initial state to work. Of course, toMatchAriaInlineSnapshot doesn't have this limitation, so I forgot about this.

It should be fixable but it's independent from shipping aria snapshot, so I'd like to deal with this in a follow-up.

Or actually this is also about the API of toMatchDomainInlineSnapshot, so we might change that whole thing basically. I thought simply swapping to toMatchDomainInlineSnapshot("kv", "...snapshot..."), but current inline snapshot logic didn't support, so I went with swapping two arguments for now.

docs/guide/browser/aria-snapshots.md

packages/browser/src/client/tester/aria.ts

packages/browser/jest-dom.d.ts

packages/snapshot/src/port/inlineSnapshot.ts

packages/vitest/src/integrations/snapshot/chai.ts

Co-authored-by: Ari Perkkiö <ari.perkkio@gmail.com>

…ia-snapshot

Co-authored-by: Ari Perkkiö <ari.perkkio@gmail.com>

…ia-snapshot

hi-ogawa · 2026-03-26T06:17:49Z

packages/snapshot/src/port/state.ts

+  get snapshotUpdateState(): SnapshotUpdateState {
+    return this._updateSnapshot
+  }


I realized this public getter is what's requested by

Expose updateSnapshot via SnapshotState #9481

macarie · 2026-03-26T10:17:49Z

docs/api/expect.md

+## expect.addSnapshotDomain <Version type="experimental">4.1.1</Version> <Experimental /> {#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)
+```


Maybe I'm way too late to the party, but would it be possible/worth considering adding this as a config entry rather than in a setup file?

Screenshot comparator algorithms are registered in browser.expect.toMatchScreenshot.comparators, this feels like a similar concept but it's done differently. I think it might be easier for users if something is done one way consistently.

I don't know what feels better to use or if it's possible unifying the behaviors at all, but I think it's something worth talking about.

Domain snapshots run in test thread, browser comparators are running on the server, so I don't think it's possible to define them as functions, but they can follow the snapshotSerializers pattern, I think:

export default defineConfig({ test: { snapshotDomains: ['./path-to-domain.js'] } })

sheremet-va · 2026-03-31T10:25:46Z

docs/api/expect.md


 The same as [`toMatchInlineSnapshot`](#tomatchinlinesnapshot), but expects the same value as [`toThrow`](#tothrow).

+## toMatchAriaSnapshot <Version type="experimental">4.1.1</Version> <Experimental /> {#tomatcharisnapshot}


Suggested change

## toMatchAriaSnapshot <Version type="experimental">4.1.1</Version> <Experimental /> {#tomatcharisnapshot}

## toMatchAriaSnapshot <Version type="experimental">4.1.3</Version> <Experimental /> {#tomatcharisnapshot}

(depends)

sheremet-va · 2026-03-31T10:26:07Z

docs/api/expect.md

+
+See the [ARIA Snapshots guide](/guide/browser/aria-snapshots) for more details.
+
+## toMatchAriaInlineSnapshot <Version type="experimental">4.1.1</Version> <Experimental /> {#tomatchariainlinesnapshot}


Suggested change

## toMatchAriaInlineSnapshot <Version type="experimental">4.1.1</Version> <Experimental /> {#tomatchariainlinesnapshot}

## toMatchAriaInlineSnapshot <Version type="experimental">4.1.3</Version> <Experimental /> {#tomatchariainlinesnapshot}

sheremet-va · 2026-03-31T10:26:15Z

docs/api/expect.md

+})
+```
+
+## toMatchDomainSnapshot <Version type="experimental">4.1.1</Version> <Experimental /> {#tomatchdomainsnapshot}


Suggested change

## toMatchDomainSnapshot <Version type="experimental">4.1.1</Version> <Experimental /> {#tomatchdomainsnapshot}

## toMatchDomainSnapshot <Version type="experimental">4.1.3</Version> <Experimental /> {#tomatchdomainsnapshot}

sheremet-va · 2026-03-31T10:26:22Z

docs/api/expect.md

+expect(value).toMatchDomainSnapshot('my-domain')
+```
+
+## toMatchDomainInlineSnapshot <Version type="experimental">4.1.1</Version> <Experimental /> {#tomatchdomaininlinesnapshot}


Suggested change

## toMatchDomainInlineSnapshot <Version type="experimental">4.1.1</Version> <Experimental /> {#tomatchdomaininlinesnapshot}

## toMatchDomainInlineSnapshot <Version type="experimental">4.1.3</Version> <Experimental /> {#tomatchdomaininlinesnapshot}

sheremet-va · 2026-03-31T10:26:34Z

docs/api/expect.md

 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 <Version type="experimental">4.1.1</Version> <Experimental /> {#expect-addsnapshotdomain}


Suggested change

## expect.addSnapshotDomain <Version type="experimental">4.1.1</Version> <Experimental /> {#expect-addsnapshotdomain}

## expect.addSnapshotDomain <Version type="experimental">4.1.3</Version> <Experimental /> {#expect-addsnapshotdomain}

sheremet-va · 2026-03-31T10:27:09Z

docs/guide/snapshot.md


+## 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.


Suggested change

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.

ARIA snapshots capture the accessibility tree of a DOM element and compare it against a stored template. Based on [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.

sheremet-va · 2026-03-31T10:36:06Z

packages/browser/src/client/tester/aria.ts

+    const r = matchAriaTree(captured, expected)
+    return {
+      pass: r.pass,
+      message: r.pass ? undefined : 'Accessibility tree does not match expected template',


I think it's easier to just

if(r.pass) { return { pass: true } } return {...}

sheremet-va · 2026-03-31T10:36:32Z

packages/browser/jest-dom.d.ts

+   * @see https://vitest.dev/guide/browser/aria-snapshots
+   * @see https://vitest.dev/api/expect#tomatchariasnapshot
+   */
+  toMatchAriaSnapshot: () => void


needs experimental tag

sheremet-va · 2026-03-31T10:36:44Z

packages/browser/package.json

    "birpc": "catalog:",
    "flatted": "catalog:",
-    "ivya": "^1.7.1",
+    "ivya": "https://pkg.pr.new/vitest-dev/ivya/ivya@68f8735",


new version is released

sheremet-va · 2026-04-01T10:49:07Z

packages/ui/client/components/artifacts/visual-regression/VisualRegression.spec.ts

      .toHaveTextContent('Diff')
    await expect.element(page.getByRole('tabpanel').getByRole('img'))
      .toBeInTheDocument()
+    expect(result.container).toMatchAriaInlineSnapshot(`


There is result.locator I think

hi-ogawa added 5 commits February 15, 2026 13:53

feat: aria snapshot

5d3c2ab

feat: toMatchDomainInlineSnapshot

986b451

feat: toMatchDomainSnapshot

5c9458d

wip

9e53df4

chore: design doc

d965f3f

hi-ogawa added 24 commits March 11, 2026 10:41

Merge branch 'main' into feat-aria-snapshot

4df273d

wip: revert slop

54696d7

test: wip

1a2cdb2

wip: comment out more slop

0066bc0

wip: custom match

099cdd3

wip: aria

36a25a9

wip: aria prototype

011712e

wip: aria domain

9ab69f6

wip: more aria

832e4e1

docs: design

3fccafe

wip: docs

e99d081

test/snapshots/README.md

477e642

chore: cleanup

83f9240

test: split

0a75d63

test: gitignore

9158aad

test: wip

dadbbe1

test: wip

4716df1

test: wip

7767628

test: wip

f7e15ae

feat: partial update

8cd7617

test: diff

b183e4c

design docs

77282a9

refactor: remove slop DomainMatchResult.mismatches

38e0cb1

test: aria

055f912

AriPerkkio reviewed Mar 22, 2026

View reviewed changes

hi-ogawa and others added 10 commits March 23, 2026 12:23

docs: Aria -> ARIA

2ad6077

docs: Update docs/guide/snapshot.md

276d481

Co-authored-by: Ari Perkkiö <ari.perkkio@gmail.com>

docs: Ari

03b524b

docs: Update packages/browser/src/client/tester/aria.ts

d14f6aa

Co-authored-by: Ari Perkkiö <ari.perkkio@gmail.com>

docs: Update packages/browser/jest-dom.d.ts

9e26248

Co-authored-by: Ari Perkkiö <ari.perkkio@gmail.com>

Merge remote-tracking branch 'origin/feat-aria-snapshot' into feat-ar…

add1888

…ia-snapshot

docs: Update docs/guide/browser/aria-snapshots.md

dfd000d

Co-authored-by: Ari Perkkiö <ari.perkkio@gmail.com>

docs: Update docs/guide/browser/aria-snapshots.md

0041edb

Co-authored-by: Ari Perkkiö <ari.perkkio@gmail.com>

Merge remote-tracking branch 'origin/feat-aria-snapshot' into feat-ar…

dca26a6

…ia-snapshot

docs: tidy up jsdoc

67949f1

hi-ogawa commented Mar 26, 2026

View reviewed changes

macarie reviewed Mar 26, 2026

View reviewed changes

hi-ogawa added 13 commits March 31, 2026 11:44

Merge branch 'main' into feat-aria-snapshot

7e9ca5c

refactor: add matchDomain

e002f9b

chore: fix merge conflict

a984079

refactor: copy assertMatchResult

7406a75

refactor: pollAssertDomain -> pollMatchDomain

61f464e

refactor: remove assertXxx

a2c6143

refactor: nit

29cce4a

refactor: nit

8145a2f

refactor: nit

8de98d2

refactor: towards custom matcher support

c72c7b1

chore: lint

78abf15

Merge branch 'main' into feat-aria-snapshot

d5c1a28

test: dogfood aria snapshot in packages/ui

9309f1a

hi-ogawa mentioned this pull request Apr 1, 2026

Display aria snapshot on locator element error #10038

Open

4 tasks

test: more dogfooding

6c7314d

sheremet-va reviewed Apr 1, 2026

View reviewed changes


		The same as [`toMatchInlineSnapshot`](#tomatchinlinesnapshot), but expects the same value as [`toThrow`](#tothrow).

		## toMatchAriaSnapshot <Version type="experimental">4.1.1</Version> <Experimental /> {#tomatcharisnapshot}


		See the [ARIA Snapshots guide](/guide/browser/aria-snapshots) for more details.

		## toMatchAriaInlineSnapshot <Version type="experimental">4.1.1</Version> <Experimental /> {#tomatchariainlinesnapshot}

	## toMatchDomainSnapshot <Version type="experimental">4.1.1</Version> <Experimental /> {#tomatchdomainsnapshot}
	## toMatchDomainSnapshot <Version type="experimental">4.1.3</Version> <Experimental /> {#tomatchdomainsnapshot}

	## toMatchDomainInlineSnapshot <Version type="experimental">4.1.1</Version> <Experimental /> {#tomatchdomaininlinesnapshot}
	## toMatchDomainInlineSnapshot <Version type="experimental">4.1.3</Version> <Experimental /> {#tomatchdomaininlinesnapshot}

	## expect.addSnapshotDomain <Version type="experimental">4.1.1</Version> <Experimental /> {#expect-addsnapshotdomain}
	## expect.addSnapshotDomain <Version type="experimental">4.1.3</Version> <Experimental /> {#expect-addsnapshotdomain}


		## 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.

Uh oh!

Conversation

hi-ogawa commented Feb 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

API

Example

TODO

Questions

Follow-up considered

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

Tests

Documentation

Changesets

Uh oh!

netlify bot commented Feb 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for vitest-dev ready!

Uh oh!

AriPerkkio left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hi-ogawa Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sheremet-va Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hi-ogawa commented Feb 15, 2026 •

edited

Loading

netlify bot commented Feb 15, 2026 •

edited

Loading

hi-ogawa Mar 22, 2026 •

edited

Loading

sheremet-va Mar 26, 2026 •

edited

Loading