Assert with accessibility — ARIA snapshots and a11y matchers

You already locate elements by ARIA roles (getByRole('button', { name: 'Add to cart' })). That's a great first step, but Playwright also provides accessibility-first assertions.

1. toMatchAriaSnapshot locks down the structure of an entire region in one assertion.
2. Dedicated a11y matchers check a single element and fail with a clear message when its accessibility breaks, instead of a generic "couldn't locate" timeout somewhere else.

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

await expect(page).toMatchAriaSnapshot(`
  - heading /Playwright enables reliable end-to-end/ [level=1]
  - link "Get started":
    - /url: /docs/intro
  - link "Star microsoft/playwright on GitHub":
    - /url: https://github.com/microsoft/playwright
  - link /[\\d]+k\\+ stargazers on GitHub/
`);

Snapshots can be strict (exact text) or flexible. The quickest way to create them is codegen.

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"
`);

Now, sometimes you don't want to maintain these long YAML definitions or even think about them.

For these cases, call toMatchAriaSnapshot() without an inline string and Playwright stores the expected accessibility tree in a .aria.yml file next to the test.

await expect(container.getByLabel("Newsletter form")).toMatchAriaSnapshot();

If you now run npx playwright test with the --update-snapshots flag, Playwright writes and updates the YAML snapshots for you.

$ npx playwright test tests/inline.spec.ts --update-snapshots

Running 1 tests using 1 workers
[chromium] › tests/inline.spec.ts:3:5 › aria-snapshot
A snapshot is generated at tests/inline.spec.ts-snapshots/aria-snapshot-1.aria.yml.
  1 passed (6.8s)

Per-element accessibility matchers

To check one element at a time, there are four matchers.

toHaveAccessibleDescription is the most useful of the four. You almost never locate by description, so asserting the helper text connected via aria-describedby tests something the locator didn't already check.

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

Better failure messages

One of the strongest arguments for toHaveAccessibleName and toHaveRole is 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 looks and works the same, but its accessible name changes from "Close" to "×", which might be read out loud as "multiplication sign".

Every functional test that relies on the role + name locator combination times out with a generic element not found error and you have to dig to figure out what went missing. 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:

await expect(page.getByTestId("close-btn")).toHaveAccessibleName("Close");

// Error shown if the accessible name doesn't match
Expected: "Close";
Received: "×";

It's the same problem, but it comes with a better error message.

Don't use toHaveAccessibleName() to duplicate what's already in your locator definition. Use it as an additional guard.

When to reach for which

Honestly, I primarily use user-first locators paired with an occasional toMatchAriaSnapshot. The other assertions have their place when accessibility plays a big role in your product.

if (isMobile) test.skip();