Playwright accessibility snapshot and axe-core attribute reporting mismatch

Question

Goal: Verify that Playwright's page.accessibility.snapshot() reports the same ARIA attributes that axe‑core evaluates when auditing a page, specifically attributes like aria-describedby and aria-details that are currently omitted from the snapshot.
Constraint: The snapshot API is experimental and deliberately excludes certain ARIA relations, while axe‑core reads the DOM directly, causing divergent results and making cross‑browser accessibility assertions unreliable without additional normalization.
Unresolved: Whether Playwright should extend the snapshot to include omitted attributes and provide a unified, browser‑normalized accessibility tree, or leave this work to user‑land libraries.
Should Playwright augment accessibility.snapshot() to include omitted ARIA attributes? Should it supply a normalization layer for cross‑browser differences? Or should users handle discrepancies with external tools?

Tasadduq Burney · Answer

Answer
Playwright should not extend accessibility.snapshot() to include omitted ARIA attributes such as aria-describedby or aria-details. The snapshot is intended to reflect the browser's accessibility tree (name, role, state, value, description). Adding raw DOM attributes would blur that purpose and introduce browser‑specific inconsistencies. For attribute‑level audits, use axe‑core directly; combine the two tools when you need both tree‑level and rule‑based validation.
Confirmed facts

Playwright's accessibility.snapshot() returns a JSON representation of the computed accessibility tree (name, role, value, description, etc.) and deliberately excludes raw ARIA attributes that are not mapped to accessibility properties.
axe‑core evaluates the full DOM (including shadow DOM when configured) and can report violations based on attributes that do not affect the accessibility tree, leading to apparent mismatches.
The discrepancy is most noticeable with custom components, elements inside shadow roots, or when axe‑core is tuned to check attributes that are not exposed in the accessibility tree.

Likely explanation
The mismatch arises because the two tools operate at different layers: snapshot = accessibility‑tree layer; axe‑core = DOM‑attribute layer. Extending the snapshot to include omitted attributes would require Playwright to duplicate axe‑core’s attribute inspection, which is outside its scope and would increase maintenance burden without providing a normalized cross‑browser tree.
Steps to diagnose and resolve the mismatch for this case

Create a test page that contains an element with an ARIA attribute that is not reflected in the accessibility tree, e.g., <img src='x' aria-describedby='desc'> where the described element is hidden or not part of the tree.
Run Playwright snapshot:
const snapshot = await page.accessibility.snapshot();
Capture the JSON output.

Run axe‑core on the same page (using axe-cli or import { axe } from '@axe-core/playwright'):
const results = await axe.run(page);

Compare the snapshot’s attributes (if any) with the violations reported by axe. You will see that the snapshot lacks the aria-describedby entry while axe may flag a missing or misused attribute.
If you need to assert on the attribute value, use axe‑core’s rule results directly; otherwise, rely on the snapshot for tree‑level checks (name, role, state).

Missing diagnostic detail
If you are testing inside a shadow DOM or an iframe, please confirm whether you are scoping the accessibility snapshot to that boundary (e.g., passing root option) because the recommendation may change if the snapshot omits elements that axe‑core can see.

Playwright accessibility snapshot and axe-core attribute reporting mismatch

1 answer

Answer

Confirmed facts

Likely explanation

Steps to diagnose and resolve the mismatch for this case

Missing diagnostic detail

Your perspective belongs here.

1 question comment