# Snapshot Testing Accessibility Trees to Prevent Regressions

A standard visual or DOM snapshot tells you the markup changed; it does not tell you whether assistive technology now hears something different. This page — part of Regression Prevention After Fixes — shows how to capture the computed accessibility tree (the roles, names, and states a screen reader consumes) as a committed snapshot, fail CI when it drifts unexpectedly, and update it cleanly when the change is intentional. The accessibility tree becomes a versioned contract: change it on purpose and update the file, change it by accident and the build stops you.

Baseline controls this page enforces:

• Capture the tree via Playwright page.accessibility.snapshot() or normalized axe results.
• Normalize volatile content before comparison so the diff is meaningful.
• Fail CI on any unexpected structural or naming change.
• Provide a deliberate, reviewed update path for intentional changes.

# Root Cause / Context

DOM snapshots and visual regression tests both miss the layer that matters most for accessibility. A <button> refactored into a <div onClick> can look pixel-identical and produce nearly identical HTML, yet its accessibility-tree node changes from role: button to nothing — a total regression for keyboard and screen-reader users that no pixel diff catches. The computed accessibility tree is the only artifact that reflects what assistive technology actually receives, so it is the right thing to snapshot.

The default snapshot tooling fails here because it is content-agnostic: it cannot tell a meaningful role change from an irrelevant timestamp shift. Naive accessibility-tree snapshots are therefore notoriously flaky, full of false diffs from dynamic names. The fix is a normalization pass that strips volatile content before comparison, leaving a stable contract that only changes when the accessible structure genuinely changes. Pair this with the violation baseline from axe-core and you cover both rule failures and structural drift.

# Configuration

This jest-style test captures the tree, normalizes it, and asserts against a committed snapshot. The normalizer is the load-bearing part: it prunes volatile fields so the snapshot is deterministic.

// a11y-tree.test.js  (run with: node --test, or jest)
import { test, expect } from "@playwright/test";

// Recursively normalize the tree: drop volatile names, keep structure.
function normalize(node) {
  if (!node) return null;
  const clean = { role: node.role };
  if (node.name !== undefined) {
    // Replace digits, ISO dates, and uuid-like ids with placeholders.
    clean.name = node.name
      .replace(/\d{4}-\d{2}-\d{2}T[\d:.Z]+/g, "<date>")
      .replace(/[0-9a-f]{8}-[0-9a-f-]{27}/gi, "<uuid>")
      .replace(/\d+/g, "<n>")
      .trim();
  }
  if (node.checked !== undefined) clean.checked = node.checked;
  if (node.expanded !== undefined) clean.expanded = node.expanded;
  if (node.children) clean.children = node.children.map(normalize);
  return clean;
}

test("checkout accessibility tree is stable", async ({ page }) => {
  await page.goto("http://localhost:3000/checkout");
  await page.waitForLoadState("networkidle"); // wait out hydration
  const tree = await page.accessibility.snapshot(); // computed a11y tree
  const normalized = JSON.stringify(normalize(tree), null, 2);
  // Playwright's toMatchSnapshot writes the file on first run and on -u.
  expect(normalized).toMatchSnapshot("checkout-a11y-tree.json");
});

# Validation

Prove the test catches a real regression. Temporarily downgrade a real button to a clickable div and rerun — the role node disappears and the snapshot diff fails:

# First run writes the committed snapshot.
npx playwright test a11y-tree.test.js

# After breaking the button (button -> div), rerun:
npx playwright test a11y-tree.test.js
#  - role: button        <-- expected
#  + (removed)           <-- received: regression caught
#  1 failed, exit code 1

When a change is intentional — say you renamed a section heading on purpose — regenerate the snapshot deliberately and commit it as part of the same reviewed pull request:

npx playwright test a11y-tree.test.js -u   # -u updates committed snapshots
git add **/__snapshots__/checkout-a11y-tree.json  # review the diff in PR

# Edge Cases & Conditional Guards

• aria-busy and async regions: capture the tree only after aria-busy flips to false, or the snapshot freezes a loading state and diffs on every run.
• Virtualized lists: a tree that depends on scroll position is non-deterministic; snapshot a fixed, scrolled-to-top state or assert only on the stable landmark structure, not every row.
• Locale-dependent names: run the snapshot under a pinned locale; otherwise a CI runner in a different locale produces translated names and false diffs.

# Pipeline Impact

A failing snapshot test exits non-zero and blocks the job, so wire it as a required check exactly as you would the violation gate in Regression Prevention After Fixes. Commit the __snapshots__ directory so the contract travels with the code. Upload the failing diff as a CI artifact so reviewers can read the exact tree change without re-running locally. Because the test is deterministic after normalization, it adds negligible flakiness to the pipeline.

# Common Pitfalls

• Snapshotting without normalization. Raw trees contain timestamps and counts that diff constantly, training the team to ignore failures.
• Updating snapshots in CI automatically. This launders regressions into the baseline; updates must be a human-reviewed commit only.
• Capturing before hydration. A pre-hydration tree is a different, unstable structure — always wait for networkidle.
• Snapshotting the entire page. Huge trees produce unreadable diffs; scope snapshots to critical views or specific landmark subtrees.

# FAQ

Playwright accessibility.snapshot() or axe results — which should I snapshot? Use accessibility.snapshot() when you care about structural roles, names, and states, since it mirrors the assistive-technology tree directly. Snapshot normalized axe results when you specifically want to lock the set of rule violations. Many teams do both, as covered in the parent page.

How do I stop snapshots from becoming flaky over time? Invest in the normalizer. Every false diff is a volatile field that needs a placeholder rule. A well-tuned normalizer makes the snapshot change only when the accessible structure genuinely changes.

Should every page have a tree snapshot? No — snapshot your highest-value, most-regression-prone views (checkout, auth, key forms). Blanket snapshotting every page creates noise and maintenance cost that outweighs the benefit.

# Related

• Regression Prevention After Fixes — the parent strategy combining tree snapshots with violation baselines.
• Automated Remediation & Accessibility Fixing Patterns — the broader section on fixing and locking in accessibility.
• Handling Dynamic ARIA States in Modern JavaScript Frameworks — capturing stable trees from dynamic components.