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)~~
- Custom domain snapshot assertion is only available through expect.extend.

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	`f4736ac`
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/69d5d5d00d69f70008db9dae
😎 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.

hi-ogawa · 2026-04-03T09:05:25Z

I finished the follow up of providing domain snapshot API via custom matcher. Internally aria snapshot also goes through the same path. #10041 I like this shape better so I will merge this to here after #10042 merged to main.

EDIT: two are merged via hi-ogawa#5

* refactor: use custom matcher for domain snapshot * test: test toMatchKvSnapshot and toMatchKvInlineSnapshot * test: update exports * refactor: aria snapshot via expect.extend * chore: comment what to do * feat: support `expect.extend(..., { __vitest_poll_takeover__: true })` * test: update * refactor: remove unused * test: update exports * refactor: remove more * test: update * chore: remove types * docs: remove addSnapshotDomain * chore: clean snapshot matcher transition leftovers Co-authored-by: Codex <noreply@openai.com> * chore: unused * docs: update custom snapshot matcher guidance Co-authored-by: Codex <noreply@openai.com> * docs: re-order * docs: jsdoc * refactor: use __vitest_poll_takeover__ per matcher function * refactor: revert expect.extend options * chore: comment * chore: comment --------- Co-authored-by: Codex <noreply@openai.com>

hi-ogawa · 2026-04-07T01:09:56Z

@sheremet-va This is ready yet again.

sheremet-va

I don't think I've seen a multi-line ARIA snapshot - how are they supported?

Otherwise looks good 👍

docs/api/expect.md

sheremet-va · 2026-04-07T19:35:03Z

docs/api/expect.md

+
+- **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).


Inspired or based on?

I simplified the paragraph here and removed the mention.

sheremet-va · 2026-04-07T19:36:34Z

docs/guide/browser/aria-snapshots.md

+On first run, Vitest generates a snapshot file entry:
+
+```yaml
+- form "Log In":


Does it create a separate file or does it have exports[] file? I thought it just follow regular snapshots, but this example makes me doubt it

Good catch. Updated with the explicit file with __snapshots__/basic.test.ts.snap.

docs/guide/snapshot.md

sheremet-va · 2026-04-07T19:41:36Z

packages/snapshot/src/client.ts

+      }
+    }
+
+    // TODO: should `all` mode ignore parse error?


Not certain. Silently hiding parse error isn't good either and users can fix or purge the broken snapshot manually and that decision affects how the snapshot get updated since aria snapshot adjusts based on the template side.

I'll leave this as is and see what will happen. I've updated the comment to mention the decision.

packages/ui/client/components/views/ViewReport.spec.ts

Co-authored-by: Codex <noreply@openai.com>

hi-ogawa · 2026-04-08T04:07:18Z

I don't think I've seen a multi-line ARIA snapshot - how are they supported?

Do you mean multiline text like paragraph? ARIA snapshot normalize white space and new lines, so the generated text is always a single line. For example,

<p>
....anything...
...<br />
...
</p>

should always end up

- paragraph: ...anything but normalized...

Co-authored-by: Codex <noreply@openai.com>

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

chore: todo

15b619d

hi-ogawa requested a review from sheremet-va April 2, 2026 04:42

hi-ogawa mentioned this pull request Apr 2, 2026

refactor: use custom matcher for domain snapshot #10041

Closed

7 tasks

test: update rolldown snapshot

b359adb

hi-ogawa and others added 9 commits April 7, 2026 08:50

Merge branch 'main' into feat-aria-snapshot

eb358c1

wip: move to Snapshots.toMatchDomain(Inline)Snapshot

e9ea61d

docs: update to Snapshots namespace

4b4a0b0

test: refactor utils

1dc0272

test: update exports

6a0db71

chore: revert unneeded

d64264d

test: cleanup comments

3daea9f

test: update snapshot

78553a7

sheremet-va requested changes Apr 7, 2026

View reviewed changes

hi-ogawa mentioned this pull request Apr 8, 2026

Revive browser mode test in packages/ui #10098

Open

hi-ogawa and others added 6 commits April 8, 2026 12:22

Merge branch 'main' into feat-aria-snapshot

1ff071a

fix: this.__vitest_assertion__ -> this.assertion

a60ab07

docs: tweak

6e02739

docs: fix experimental API release markers

0395f71

Co-authored-by: Codex <noreply@openai.com>

docs: not this slop

52dddf7

docs: correct snapshot guide version markers

f87235f

Co-authored-by: Codex <noreply@openai.com>

hi-ogawa and others added 5 commits April 8, 2026 13:12

docs: clarify aria snapshot whitespace normalization

f4736ac

Co-authored-by: Codex <noreply@openai.com>

test: test multiline paragraph

cde768a

chore: tweak comment

d550648

refactor: nit

2517f92

chore: comment

1a2fecb

hi-ogawa requested a review from sheremet-va April 8, 2026 04:44


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

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!

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

Uh oh!

Uh oh!

hi-ogawa commented Apr 7, 2026

Uh oh!

sheremet-va left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sheremet-va Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

hi-ogawa Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

sheremet-va Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

hi-ogawa Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sheremet-va Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

hi-ogawa Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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

Uh oh!

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 commented Apr 3, 2026 •

edited

Loading

hi-ogawa commented Apr 8, 2026 •

edited

Loading