03 ARIA snapshots

Goal

Strengthen a search flow with toMatchAriaSnapshot and know when a snapshot beats a single text assert.

Read first

• ARIA snapshots
• Locators

Snapshot vs text

toHaveText / toContainText check one node's text. toMatchAriaSnapshot checks the accessible structure of a region (roles, names, hierarchy). Use snapshots when structure matters; use text asserts when a single string is enough.

Example: search results and empty state

From search.spec.ts:

test('search for "Twisters" movie', async ({ page }) => {
  await page.goto('');
  await searchForMovie(page, 'twisters');

  await expect(page).toHaveURL(/searchTerm=twisters/);

  await expect(page.getByRole('main')).toMatchAriaSnapshot(`
    - heading "Twisters" [level=1]
  `);
});

test('search for non-existent-movie', async ({ page }) => {
  await page.goto('');
  await searchForMovie(page, 'non-existent-movie');

  await expect(page.getByRole('main')).toMatchAriaSnapshot(`
    - heading "Sorry!"
    - heading /There were no results for/
    - link "Home":
      - button "Home"
  `);
});

Run the file on a clone:

npx playwright test tests/logged-out/search.spec.ts --project=chromium

When not to snapshot

• Huge volatile trees (ads, clocks, recommendations): narrow the locator first.
• Values that change every run without a regex: prefer /pattern/ in the YAML snapshot.
• Pure navigation checks: toHaveURL is enough.

Done when

npx playwright test tests/logged-out/search.spec.ts --project=chromium

passes, and you can explain when to prefer toMatchAriaSnapshot over a single text assert.

Extra practice: Exercise 02 — ARIA snapshot.

Key takeaways

• You can explain snapshot vs text assert in one sentence.
• search.spec.ts passes on your clone.
• You know how to update a snapshot deliberately after a real UI change.

Next: 04 Debugging.