@real-a11y-dev/testing

TL;DR — Accessibility-tree snapshots, structural assertions, custom expect matchers, and a fluent flow() interaction chain. Works in jsdom (Vitest / Jest) out of the box; add @real-a11y-dev/testing/playwright for real-browser E2E. Reach for this in your test suite — unit and e2e alike.

Headless accessibility audit helpers for Vitest, Jest, and Playwright. No browser required for the core helpers — they work in jsdom.

Install

npm install -D @real-a11y-dev/testing

What's in the box

Area	What it does	Page
Snapshots	Deterministic strings of the a11y tree, heading outline, and tab order — diff-friendly, safe to commit.	Snapshots →
Assertions	assert* functions that throw descriptive errors on broken structure.	Assertions →
Matchers	The same checks as ergonomic expect matchers, plus the a11ySnapshot() serializer. Vitest + Jest.	Matchers →
Flow API	Fluent interaction chains that assert about the tree after each step.	Flow API →
Playwright adapter	Run every helper against a real browser page via attach(page).	Playwright →

New to the idea of snapshotting the accessibility tree? Start with the concept: Accessibility Snapshots.

Which do I reach for?

• Catch regressions in CI → Snapshots (auditSnapshot, outlineSnapshot, tabSequenceSnapshot) committed with toMatchSnapshot(). For headless page-set audits of a deployed site — no test suite — reach for @real-a11y-dev/cli's snapshot / diff instead.
• Assert a specific invariant ("one <h1>", "no unlabeled buttons") → Assertions or, for expect style, Matchers.
• Test an interaction (open a menu, submit a form, dismiss a modal) → Flow API.
• Assert what an interaction changed (options appeared, aria-expanded flipped, focus moved) → capture + a11yDiff or flow().expectChanges.
• Audit a real, rendered page (not jsdom) → Playwright adapter.

See it running

• Vitest + jsdom — examples/testing-vitest/: snapshot tests, the custom matchers, flow() interactions, tab-sequence structure assertions.
• Jest + ts-jest — examples/testing-jest/: the minimal Jest setup for the matchers.
• Playwright E2E — examples/playwright/: a "good fixture" where every assertion passes and a "broken fixture" where each throws — the pattern to keep in CI.
• CI tree-diff bot — the CI Diff Bot recipe runs @real-a11y-dev/cli's real-a11y snapshot (each audited page → one diffable JSON artifact) and real-a11y diff (new / changed / fixed findings) in a PR workflow.