Playwright ARIA Snapshots for Testing Accessible Structure

An ARIA snapshot tests the interface users of accessibility APIs receive. It ignores most styling and implementation markup, then represents roles, accessible names, states, text, and hierarchy as a compact YAML tree. That makes it valuable for catching a button turned into generic text, a heading level changed during a redesign, or an expanded control that no longer exposes its state.

The technique is powerful because it is semantic, but it is still only an assertion against a chosen template. A weak partial template can miss important regressions; an enormous whole-page snapshot can create noisy reviews. Scope the contract and decide which details must remain exact.

Read the Accessibility Tree as Public Output

The Playwright ARIA snapshots guide describes nodes using role, accessible name, supported attributes, and indentation for hierarchy. Those values come from HTML semantics and calculated accessibility properties. They are not a serialized DOM and should not be used to assert class names or visual layout.

Ask what a user must be able to discover and operate. A disclosure needs a button with a name and expanded state, plus a correctly related region. A dialog needs a dialog role, an accessible name, and reachable controls. Encode that output rather than every incidental text node.

Start With a Scoped Semantic Contract

Scope the assertion to a landmark or component. This keeps unrelated banners, experiments, and account data out of the snapshot and makes a failure readable.

import { test, expect } from '@playwright/test'

test('billing disclosure exposes its state and controls', async ({ page }) => {
  await page.goto('/settings/billing')
  await page.getByRole('button', { name: 'Payment details' }).click()

  const billing = page.getByRole('region', { name: 'Payment details' })
  await expect(billing).toMatchAriaSnapshot(`
    - heading "Payment details" [level=2]
    - paragraph: Card ending in 4242
    - button "Replace card"
    - button "Remove card"
  `)
})

The opening interaction matters. Snapshot the expanded state after the user action, not whatever transient structure happened to exist during hydration. Add a focused assertion on the disclosure button when its expanded state is part of the contract.

Match Roles, Names, and States Deliberately

A node may include a role, quoted accessible name, and attributes such as checked, disabled, expanded, invalid, level, pressed, or selected. Omitted details are not asserted. That flexibility is useful, but omission must be intentional.

test('filter controls expose selected and expanded state', async ({ page }) => {
  await page.goto('/issues')
  await page.getByRole('button', { name: 'Filters' }).click()

  await expect(page.getByRole('form', { name: 'Issue filters' })).toMatchAriaSnapshot(`
    - button "Filters" [expanded=true]
    - checkbox "Assigned to me" [checked=true]
    - combobox "Status" [expanded=false]
    - button "Apply filters"
  `)
})

If a button's accessible name is essential, include it. A template containing only - button proves almost nothing about whether a screen-reader user can identify the control. Conversely, omit a generated issue count or match it with a regular expression when exact data is outside the semantic contract.

Assert Semantic Transitions, Not Only Resting Structure

Interactive components often expose their most important semantics during change. Snapshot a disclosure before and after activation when expanded state and region visibility are requirements. For a validation flow, assert the textbox becomes invalid, the error text enters the tree, and the corrected submission removes that state. For a tab set, verify the selected tab and associated panel change together.

Keep each transition small enough that the failure names the action responsible. One giant snapshot after a long wizard can reveal a final difference without showing where semantics first diverged. Focused before-and-after contracts also prevent a component from passing merely because it eventually reached a plausible tree through the wrong interaction.

ARIA snapshots do not report keyboard focus order by themselves. Pair a transition snapshot with toBeFocused, keyboard input, and observable activation. A dialog can have a perfect role and name while focus remains behind it; a menu can expose correct items but ignore arrow keys. Structural and behavioral evidence answer different accessibility risks.

Choose Partial or Exact Children by Risk

By default, a template can match a subset of children in order. This is helpful for a large region where only key landmarks matter. Use /children: equal when the direct child list and order must match exactly, or deep-equal when nested completeness is also required.

test('primary navigation has the approved destinations', async ({ page }) => {
  await page.goto('/dashboard')

  await expect(page.getByRole('navigation', { name: 'Primary' }))
    .toMatchAriaSnapshot(`
      - list:
        - /children: equal
        - listitem:
          - link "Dashboard"
        - listitem:
          - link "Projects"
        - listitem:
          - link "Reports"
    `)
})

Strict children are valuable when an extra destructive link or a missing destination is a regression. They are costly for feeds, tables, and personalized menus whose items legitimately vary. Prefer a smaller scoped contract over making dynamic content exact and constantly updating it.

Use Regular Expressions Only for Defined Variability

ARIA templates support regular expressions for accessible names and text. A heading such as Issues 12 can be matched while allowing the count to change. Keep the invariant visible in the pattern and anchor it when accidental extra text matters.

A regex like /.*/ defeats the purpose. If all content is irrelevant, assert the role and stable state instead. If the value matters, seed deterministic data and use the exact name. Regular expressions should represent a documented variable, not make a failing snapshot quiet.

Store Large Contracts in Named Files

Inline templates work well for compact components because the expected structure sits beside the scenario. Larger, stable contracts can live in named .aria.yml snapshot files by passing a name option. This keeps the test readable while preserving a reviewable semantic artifact.

Do not split only because the template is inconvenient. A large snapshot may signal that the assertion scope is too broad. First ask whether separate navigation, dialog, form, and table contracts would produce clearer failures and ownership.

When product semantics intentionally change, generate candidate updates with the Playwright snapshot workflow and review the diff. Snapshot updates are code changes. A removed name, changed heading level, or newly disabled control deserves the same scrutiny as a changed assertion.

Layer Snapshots With Focused Accessibility Tests

An ARIA snapshot can verify structure, but it does not prove keyboard order, focus visibility, activation behavior, live-region timing, color contrast, zoom reflow, touch target size, or understandable error recovery. Pair it with direct interaction tests and an accessibility rule engine.

import AxeBuilder from '@axe-core/playwright'
import { test, expect } from '@playwright/test'

test('account dialog has semantic and rule coverage', async ({ page }) => {
  await page.goto('/account')
  await page.getByRole('button', { name: 'Close account' }).click()

  const dialog = page.getByRole('dialog', { name: 'Close account' })
  await expect(dialog).toMatchAriaSnapshot(`
    - heading "Close account" [level=2]
    - paragraph: This action cannot be undone.
    - textbox "Type CLOSE to continue"
    - button "Cancel"
    - button "Close account" [disabled]
  `)

  const scan = await new AxeBuilder({ page }).include('[role="dialog"]').analyze()
  expect(scan.violations).toEqual([])
})

Automated tools detect only some accessibility problems. Manual keyboard and screen-reader assessment, zoom checks, and inclusive user testing remain necessary for meaningful confidence.

Diagnose Semantic Diffs at the Source

When a role disappears, inspect whether a semantic HTML element was replaced, an ARIA attribute became invalid, or the target is hidden from the accessibility tree. When a name changes, trace its accessible-name sources: text content, label, aria-label, or aria-labelledby. When hierarchy moves, inspect DOM ownership and landmark nesting rather than immediately updating indentation.

If a snapshot is flaky, identify the changing semantic input. Async loading may temporarily expose a progressbar, personalized content may alter names, or an animation may toggle hidden state. Wait for the intended user state or narrow the scope. Do not respond with a broad partial template that discards the very attributes under test.

If only one browser project differs, investigate whether the application renders different markup or whether browser accessibility mappings differ. Capture locator.ariaSnapshot() as diagnostic text and compare the computed tree before changing the shared expectation.

Use the ARIA Snapshot Checklist

• Reach a deterministic user state before taking the semantic snapshot.
• Scope to the landmark, form, dialog, navigation, or component under test.
• Include accessible names and states that users rely on.
• Use partial matching only for details outside the contract.
• Apply exact child matching where completeness and order are requirements.
• Reserve regex patterns for defined dynamic values.
• Review snapshot changes as semantic product changes.
• Pair snapshots with keyboard tests, focus checks, rule scans, and manual assessment.
• Diagnose role and name changes from computed accessibility sources.

Make Semantics a Maintained Interface

Choose one important component, capture its accessible structure, and turn that output into a concise contract. Keep essential roles, names, states, and hierarchy explicit; leave volatile content out by design. Review every update for user impact and layer the snapshot with behavioral and rule-based accessibility coverage. That approach makes semantic regressions visible without pretending a stored tree is a complete accessibility program.