How to assert Playwright ARIA snapshots

ARIA snapshots let a Playwright test check the accessibility tree that browsers expose to assistive technology. They are useful when a page or component must keep the same roles, accessible names, landmarks, and heading structure while visual styling continues to change.

Playwright can compare the full page body or a scoped locator against a YAML snapshot. A scoped locator keeps the diff small enough to review when a heading, link, or button name changes.

Use ARIA snapshots for stable semantic regions rather than feeds, counters, or timestamps that change on every run. Pair them with ordinary Playwright assertions for exact behavior checks, because a snapshot can show that a button exists without proving the click flow works.

1. Open an existing Playwright project.

   $ cd ~/projects/playwright-demo

2. Create tests/home.spec.ts with an ARIA snapshot assertion.

   import { test, expect } from '@playwright/test';
   
   test('home page exposes accessible structure', async ({ page }) => {
     await page.setContent(`
       <main>
         <h1>Playwright fixture ready</h1>
         <nav aria-label="Primary">
           <a href="/docs">Docs</a>
         </nav>
         <button>Subscribe</button>
       </main>
     `);
   
     await expect(page.locator('body')).toMatchAriaSnapshot(`
       - main:
         - heading "Playwright fixture ready" [level=1]
         - navigation "Primary":
           - link "Docs":
             - /url: /docs
         - button "Subscribe"
     `);
   });

   The body locator keeps the assertion focused on the rendered semantic page structure. Use a smaller landmark or component locator when the application shell changes often.

3. Run the test in Chromium.

   $ npx playwright test tests/home.spec.ts --project=chromium --reporter=line
   
   Running 1 test using 1 worker
   
   [1/1] [chromium] › tests/home.spec.ts:3:5 › home page exposes accessible structure
     1 passed (1.3s)

4. Change the temporary fixture button text from Subscribe to Join.

   Leave the expected snapshot at button "Subscribe" so the next run proves the assertion fails on an accessible-name change.

5. Run the test again and review the ARIA snapshot diff.

   $ npx playwright test tests/home.spec.ts --project=chromium --reporter=line
   
   Running 1 test using 1 worker
   
   [1/1] [chromium] › tests/home.spec.ts:3:5 › home page exposes accessible structure
     1) [chromium] › tests/home.spec.ts:3:5 › home page exposes accessible structure
   
       Error: expect(locator).toMatchAriaSnapshot(expected) failed
   
       Locator: locator('body')
       Timeout: 5000ms
       - Expected  - 1
       + Received  + 1
   
         - main:
           - heading "Playwright fixture ready" [level=1]
           - navigation "Primary":
             - link "Docs":
               - /url: /docs
       -   - button "Subscribe"
       +   - button "Join"
   
   ##### snipped #####
   
     1 failed

6. Restore the temporary fixture button text to Subscribe.
7. Run the test again to confirm the accessible tree matches the snapshot.

   $ npx playwright test tests/home.spec.ts --project=chromium --reporter=line
   
   Running 1 test using 1 worker
   
   [1/1] [chromium] › tests/home.spec.ts:3:5 › home page exposes accessible structure
     1 passed (1.5s)