In a frontend component test, what does an automated accessibility check such as jest-axe's axe(container) followed by expect(results).toHaveNoViolations() actually do, and what does a passing result prove?

## What the check is actually made of An automated accessibility check is a rule engine, not an oracle. Libraries such as jest-axe (and its Vitest-flavoured equivalent, vitest-axe) are thin wrappers around the axe-core engine: they give you an `axe()` function that takes a DOM node and returns results, plus a matcher, `toHaveNoViolations`, that turns those results into a test failure with a readable message. Each rule is a small deterministic program over the DOM. `image-alt` asks whether an `<img>` exposes alternative text. `label` asks whether a form control is associated with a label. `button-name` asks whether a button ends up with a non-empty accessible name. `aria-valid-attr-value` asks whether an ARIA attribute's value is one the specification allows. Every one of these questions can be answered by inspecting nodes and attributes, which is exactly why they can be automated — and it is also the boundary of what automation can do. ## The shape of the assertion The pattern is always the same three steps: render, run, assert. ```js const { container } = render(<Button>Save</Button>); const results = await axe(container); expect(results).toHaveNoViolations(); ``` Three details matter. First, `axe()` is asynchronous — the engine walks the tree and resolves a promise, so the call must be awaited or the assertion runs against a promise and silently passes. Second, you pass the container, i.e. the DOM subtree the component rendered, not a component instance and not a serialized string; the engine needs real nodes because rules read computed attributes and relationships. Third, the matcher has to be registered with the test framework before it can be used (`expect.extend(toHaveNoViolations)`), typically once in a shared setup file rather than in every test. ## Reading the result object The results carry four buckets, and only one of them fails your test. - `violations` — rules that ran and failed. `toHaveNoViolations` fails on these. - `passes` — rules that ran and succeeded. - `incomplete` — rules that ran but could not decide, usually because the environment lacked the information they needed. The matcher does **not** fail on these. - `inapplicable` — rules with nothing in the markup to check. The `incomplete` bucket is the one people are surprised by. A rule landing there is neither a pass nor a fail; it is the engine saying "a human has to look at this". A green test tells you nothing about anything sitting in that bucket. ## What a green run does and does not claim A green run supports exactly one claim: none of the rules that were enabled and could run found a defect in this markup. It does not claim the component is usable. It cannot tell you whether the alternative text is meaningful, whether the tab order matches the visual order, whether focus is visible, or whether a screen reader announces something a person can act on. Those require human judgment or a real browser, and treating a green suite as proof of accessibility is the single most common misuse of this tool. It is also scoped to *this markup in this environment*. A component test typically renders a fragment into a bare container in a simulated DOM, so page-level rules have nothing meaningful to evaluate and rules that depend on layout or painting cannot resolve real values at all. ## Where it earns its place Because the check costs one assertion, the sensible default is to fold it into the tests you were writing anyway — especially for shared, reusable components, where one missing label is multiplied across every screen that consumes them. It works best as a regression net: once a defect has been found and fixed, the rule stops it from coming back, forever, at no ongoing cost. What it should not become is the whole accessibility strategy. It is one layer among several — static linting of the markup as it is authored, rule checks over rendered DOM in component tests, a real-browser pass for anything involving colour and layout, and manual keyboard and screen-reader review of the flows that matter. Each catches things the others structurally cannot. ## Common mistakes Forgetting `await` is the classic, and it produces a test that can never fail. Asserting on `document.body` instead of the rendered container pulls in unrelated markup left by other tests. Running the check on a component that has not reached its final state — still loading, still empty — checks markup no user ever sees. And disabling a rule to make a red test green, without recording why, converts a real defect into a permanent blind spot.