snapshot/aria

16 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

ARIA snapshots test accessibility tree instead of HTML

ARIA snapshots test the accessibility structure of pages by asserting against the accessibility tree — the same structure that screen readers and other assistive technologies use. This catches accessibility regressions like missing labels, broken roles, incorrect heading levels. Even if underlying HTML structure changes, assertions don't fail as long as content matches semantically.

toMatchAriaSnapshot() stores snapshot in .snap file

The toMatchAriaSnapshot() matcher stores the snapshot in a .snap file alongside the test file. It creates an entry in a __snapshots__ directory with the accessibility tree representation.

toMatchAriaInlineSnapshot() stores snapshot in test file

The toMatchAriaInlineSnapshot() matcher stores the snapshot directly in the test file as an inline assertion, rather than in a separate .snap file.

expect.element() polls DOM and waits for accessibility tree to stabilize in browser mode

In Browser Mode, expect.element() polls the DOM and waits for the accessibility tree to stabilize before evaluating the result. On each poll, the matcher re-queries the element and re-captures the accessibility tree. The snapshot is considered stable when two consecutive polls produce the same output. If the result does not match an existing snapshot, polling resets and continues to give the DOM time to reach the expected state.

Hand-edited regex patterns survive snapshot updates

When you hand-edit a snapshot to use regex patterns, those patterns survive running --update. Only the literal parts that changed are overwritten. This lets you write flexible assertions that don't break when content changes.

ARIA snapshot format is YAML-like with role, name, and attributes

Each accessible element in an ARIA snapshot is represented as a YAML node: `- role "name" [attribute=value]`. The role is the ARIA role (heading, list, button, etc.). The name is the accessible name when present, using quoted strings for exact matches or /patterns/ for regex. Attributes in brackets are accessibility states and properties like checked, disabled, expanded, level, or pressed.

ARIA snapshots use subset of YAML syntax

ARIA snapshot templates use a subset of YAML syntax. Only scalar values, nested mappings via indentation, and sequences (- item) are supported. Advanced YAML features like anchors, tags, flow collections, and multi-line scalars are not supported. Captured text is also whitespace-normalized — newlines, <br> line breaks, tabs, and repeated whitespace collapse to single spaces.

Content with aria-hidden or display: none excluded from ARIA snapshots

Because ARIA snapshots reflect the browser's accessibility tree, content excluded from that tree does not appear in the snapshot. This includes elements with aria-hidden="true" or display: none.

Text nodes in ARIA snapshots are whitespace-normalized and single-line

Text values in ARIA snapshots are always serialized on a single line after whitespace normalization. Multiple lines, <br> tags, tabs, and repeated spaces all collapse to single spaces.

Child elements in ARIA snapshots nest under parent with indentation

Child elements in ARIA snapshots appear nested under their parent with indentation. If the parent has an accessible name, the snapshot includes it before the nested children.

/url pseudo-attribute for links in ARIA snapshots

Links in ARIA snapshots include a /url pseudo-attribute showing their href value. For example: `- link "Home": - /url: /`

/placeholder pseudo-attribute for textboxes in ARIA snapshots

Textboxes in ARIA snapshots can include a /placeholder pseudo-attribute with their placeholder text. The placeholder only appears when different from the accessible name. When placeholder is the accessible name (no aria-label), it is not duplicated as a pseudo-attribute.

Regex patterns in ARIA snapshots require doubled backslashes when hand-edited

When hand-editing an ARIA snapshot to add a regex pattern, backslashes need to be doubled. For example, to match digits use /item \\d+/ (double backslash) not /item \d+/ (single backslash). This applies to both inline snapshots and .snap files. When Vitest auto-generates or updates snapshots, escaping is handled automatically.

/children: contain (default) partial matching for ARIA snapshot children

By default, ARIA snapshot templates use /children: contain semantics (the default when no /children directive is specified). Templates use contain semantics — extra children in the actual tree are allowed as long as all template children appear as an ordered subsequence. This is useful for focused, resilient tests that don't break when unrelated content is added.

/children: equal exact matching for ARIA snapshot immediate children

The /children: equal directive requires that a node's immediate children match the template exactly — same count, same order, no extra children allowed. The strict matching only applies at the level where /children is placed. Descendants of each child still use the default contain semantics.

/children: deep-equal exact matching for ARIA snapshots at all depths

The /children: deep-equal directive requires strict matching that propagates to all descendants. Every level of nesting must match exactly — same count, same order, no extra nodes at any depth.

Give your agent this brain