feat: support aria snapshot

[hi-ogawa]

Description

• Closes [Brower Mode] Support aria snapshot matcher #6933

Adds toMatchAriaSnapshot() and toMatchAriaInlineSnapshot() matchers for asserting DOM accessibility trees, inspired by Playwright's aria snapshot feature.

Under the hood, this introduces domain snapshot concept — a generic extension point that lets snapshot matchers delegate comparison to a semantic pipeline (capture → parse → match → render) instead of string ===. This architecture allows:

• error diff and new snapshot to be generated per adapter structure (e.g. aria regex/sublist match normalizes error diff and preserved when updating snapshot)
• poll like retry mechanism, which is important for aria snapshot on browser mode with expect.element.

ARIA is the first shipped adapter. The custom domain adapter API is left as experimental and documented like so.

Quick explaner

// file-backed — snapshot auto-generated on first run
expect(document.querySelector('nav')).toMatchAriaSnapshot()

// inline — editable in source
expect(document.body).toMatchAriaInlineSnapshot(`
  - navigation "Actions":
    - button: Save
    - button: Cancel
`)

// snapshot with regex matches (manually edited)
expect(document.body).toMatchAriaInlineSnapshot(`
  - navigation "Actions":
    - button: /\\d+ likes/
    - button: Cancel       👈 only this snapshot updates when only this text mismatches
`)

// with expect.element (Browser Mode) — retries until DOM matches
await expect.element(page.getByRole('navigation')).toMatchAriaInlineSnapshot(`
  - button: Save
  - button: Cancel
`)

// with expect.poll — retries a callback
await expect.poll(() => document.body).toMatchAriaInlineSnapshot(`
  - heading "Dashboard" [level=1]
`)

Snapshots support hand-edited regex patterns (/pattern/) that survive --update:

- button /User \d+/: Profile # regex preserved on update
- paragraph: You have 7 items # literal overwritten if value changes

Questions

• Should custom snapshot domain API public?
  • I'd keep this as experimental for now. The existence of this API is crucial for its own testability, but not sure about the use case except aria snapshot. I propose documenting aria snapshot properly out of domain snapshot concept to start with. We can still document experimental domain snapshot API but nailing down its API can come later with proper use case in mind.

Follow-up considered

• support "raw file" output like toMatchFileSnapshot
• improve aria matching features (namely merging algorithm. didn't think through but it can do better.)
• migrate internal to use snaphsot domain like mechanism

---

TODO

• design and poc
  • file snapshot
  • inline snapshot
• aria snapshot adapter
• support poll + snapshot via domain model
  • file snapshot
  • inline snapshot
  • expect.element + aria snapshot becomes a special case
    • works except (current) webkit by the same reason as defineHelper. should be fixed on next playwright update, which has better async stack.
• wire up feat: add aria snapshot utilities sheremet-va/ivya#8
• review ai slop
  • aria implementation
  • tests
  • domain snapshot match
  • poll snapshot
  • reduce bloat API
  • credit playwright
• migrate internal to use snaphsot domain (later)
• docs
  • document details on aria matching algorithm. does something more than playwright https://playwright.dev/docs/aria-snapshots#snapshot-matching
• PR summary

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]

✅ Deploy Preview for vitest-dev ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	e25e29b
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/69b3e3bb2f18ec0008dfcc3f
😎 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.