Assert with accessibility — aria snapshots and a11y matchers

You already locate elements by role ARIA (getByRole('button', { name: 'Add to cart' })). That's a great first step, but there are more accessibility-first assertions.

1. toMatchAriaSnapshot — locks down the structure of an entire region in one assertion.
2. Dedicated a11y guards — focused checks that fail with a clear message when the accessibility contract regresses, instead of a generic "couldn't locate" timeout somewhere downstream.

Snapshot the whole structure with toMatchAriaSnapshot

For a region of the page, toMatchAriaSnapshot captures the entire accessibility tree in a YAML-like format. It's the closest thing Playwright offers to a "structure regression test". It doesn't break on CSS tweaks, but it does fail when meaningful structure changes (a heading disappears, an element is renamed, the order shifts).

Snapshots can be strict (exact text) or flexible. The next exercise is about picking the right level of strictness for each item.

await expect(
  page.getByRole("region", { name: "Newsletter form" }),
).toMatchAriaSnapshot(`
  - heading [level=2]
  - paragraph
  - button "Submit"
  - button "Undo"
`);

Per-element accessibility matchers

For one element at a time, four matchers are available.

toHaveAccessibleDescription is the per-element matcher that does the most honest work: you almost never locate by description, so asserting the helper text tied via aria-describedby actually tests something the locator didn't already enforce.

await expect(
  page.getByRole("textbox", { name: "Email" }),
).toHaveAccessibleDescription("We'll never share your email.");

const container = page.getByTestId('accessible-description-exercise');
await container.getByRole('button', { name: 'Validate' }).click();
await expect(
  container.getByLabel('Email address')
).toHaveAccessibleDescription('Please enter your email address.');

The failure-message angle

One of the strongest argument for toHaveAccessibleName and toHaveRole is the how your tests fail when a11y regresses.

Imagine an icon-only × close button.

<button aria-label="Close">×</button>

Your functional tests use page.getByRole("button", { name: "Close" }).click() to dismiss a dialog. Someone deletes the aria-label in a refactor. The button still works visually but its accessible name silently changes from "Close" to "×".

Every functional test that relies on the role + name locator now times out with a generic "element not found" and you have to dig to figure out why. A single dedicated a11y test, located by something stable (a test id or a positional locator) and asserting toHaveAccessibleName, fails in one line with the exact diff:

Expected: "Close"
Received: "×"

Same regression. Different diagnosis. The dedicated guard is the toHaveAccessibleName use case that isn't a duplicate of your locator. It's not next to your click; it's a focused regression test for the a11y contract itself.

These matchers are auto-retrying like every other web-first assertion, so the patterns from the previous lesson — .not, expect.soft, custom messages, configurable timeouts — all apply unchanged.

When to reach for which

So, when should you reach for which. Honestly, I'm primarily using the user-first locators paired with occasional toMatchAriaSnapshot. The other assertions do have their place in though, when accessibility plays a bit role in your product.

if (isMobile) test.skip();