In a React Testing Library test, screen.getByRole('button', { name: 'Save' }) throws even though the Save control is visibly rendered and clickable in the browser. What markup causes that, and why is the failing query often a real defect rather than a test problem?

## What the query is actually asking `getByRole('button', { name: 'Save' })` asks: is there an element exposed to assistive technology as a button, whose accessible name is "Save"? That is a different question from "is there something on screen a mouse can click", and the gap between the two is exactly where this failure lives. ## Cause 1: no role The most common cause is a control that is not a control. ```javascript // no role: exposed as generic content '<div class="btn" onclick="save()">Save</div>' // role button, keyboard operable, focusable '<button type="button">Save</button>' ``` A `<div>` with a click handler has no implicit role, so no role query will ever find it. The test failure is the cheapest possible signal that the control is unreachable by keyboard and invisible to assistive technology. A rarer variant: the element *has* a role, but the wrong one, because someone wrote `role="link"` on something that behaves like a button, or a component library renders an `<a>` where the design says button. Then `getByRole('link', { name: 'Save' })` succeeds and the button query fails — and the query has just documented a semantic mismatch. ## Cause 2: hidden from the accessibility tree `ByRole` queries ignore elements excluded from the accessibility tree. Exclusion comes from `aria-hidden="true"`, `display: none`, `visibility: hidden` or the `hidden` attribute — **on the element or on any ancestor**. The ancestor case is the one that burns people: a wrapper with `aria-hidden="true"` (often added to a decorative shell, or left behind by a modal/overlay implementation) removes everything under it. The query accepts `hidden: true` to include hidden elements, but reaching for that is almost always the wrong move in a test that then goes on to click the element. If the control is hidden from assistive technology, a user of that technology cannot press it, and a test that presses it anyway is asserting a behaviour some users do not have. A related trap in JSDOM-based environments: styles that come from a real stylesheet are not applied, so an element hidden only by an external CSS class may still be visible to the query, while inline `style="display:none"` is honoured. That is a reason to be careful about drawing visibility conclusions from a component test alone. ## Cause 3: the name does not match If the role query succeeds without a `name` but fails with it, the problem is naming. Two mechanics matter for the test author. First, **a string `name` matches the full, normalised accessible name**, not a substring. `{ name: 'Save' }` will not find a control named "Save changes"; `{ name: /save/i }` will. Whitespace is normalised (trimmed and collapsed) before comparison, so line breaks in JSX are not the culprit. Second, **the accessible name may not be the visible text**. An icon-only button typically has no name at all until someone labels it. A button whose label was set from a different source can be announced as something other than what is drawn on screen — which is also a voice-control defect, since the user says the words they can see. How the name is computed from the markup is the accessibility layer's subject; what matters here is the testing consequence: a role query is only as good as the name the component exposes, and a mismatch is a finding, not an inconvenience. ## Reading the failure The error output is designed for this. A failed `ByRole` query prints the rendered DOM and enumerates the roles that *were* present, with the accessible name of each. That usually answers the question in one read: no button role at all (cause 1), the button is missing from the list entirely (cause 2), or the button is listed with a different name (cause 3). ## Why the fix belongs in the component The tempting fixes — add a `data-testid`, switch to `container.querySelector('.btn')`, pass `hidden: true` — all make the test green while leaving the product broken. The role query is the only routine check most teams run that touches the accessibility tree at all, so silencing it removes the signal. The right sequence is: read the printed roles, decide whether the markup or the query is wrong, and change the markup when the answer is "a real user could not find this either". Reserve the escape hatches for elements that genuinely have no user-facing identity.