RTL and user-event: test the contract the user sees

The query is the assertion

Testing Library’s guiding principle — tests should resemble how the software is used — is not a slogan; it is encoded in the query API as a priority order, and each step down the order trades away a class of regressions the test can catch. getByRole queries the computed accessibility tree, the same structure assistive technology consumes, and the name option pins the accessible name (resolved from the label, aria-label, aria-labelledby, or text content per the W3C accname algorithm). A role query is therefore two assertions in one: the element exists, and it is exposed to users as the right kind of control with the right name. getByLabelText verifies the label association on form fields — htmlFor, wrapping, or aria-labelledby — which is exactly the binding a screen reader resolves; a visually adjacent but unassociated label passes a getByText check and fails this one. getByText asserts visible content for non-interactive elements. getByTestId asserts nothing except that your test and your markup agree on a string. It is the deliberate escape hatch — a canvas region, a third-party widget whose markup you cannot fix — not the default.

screen queries the whole document. within(node) scopes queries to a subtree — use it both for readability (“the Save button inside this dialog”) and for performance on large DOMs, which matters more than most teams expect (numbers below).

What user-event actually fires

fireEvent.click dispatches exactly one synthetic MouseEvent. A real user click is a sequence: pointerover → pointerenter → pointermove → pointerdown → mousedown → focus → pointerup → mouseup → click — and user-event v14 fires that whole interaction, around nine events with correct ordering, coordinates, and focus side effects. user.type fires keydown → keypress → input → keyup per character: a 20-character string is 80-plus events, each one respecting maxLength, disabled, readonly, and the current selection. fireEvent.change teleports a value into the input wholesale — it never triggers keydown handlers, cannot be constrained by maxLength, and will green-light states a user literally cannot produce. A component that submits on Enter via onKeyDown is untestable with fireEvent.change and trivially tested with await user.type(input, "query{Enter}").

The v14 mechanics matter in code review. const user = userEvent.setup() before render creates an instance bound to one coherent input-device state (keyboard, pointer, clipboard). Every API is async — await user.click(...) — because user-event yields between the events of a sequence so React can flush intermediate state, the way a real browser interleaves event dispatch with rendering. A missing await is not a style issue: the interaction races the assertions that follow it and is a standing source of act warnings and flakes.

// ❌ passes even when the user is blocked:
fireEvent.change(input, { target: { value: "abcdefgh" } }); // ignores maxLength
fireEvent.click(saveButton); // fires on disabled, unfocusable, covered nodes

// ✅ fails the way a user fails:
const user = userEvent.setup();
await user.type(input, "abcdefgh"); // stops at maxLength, fires per-key events
await user.click(saveButton);      // throws on pointer-events: none

The tradeoff is cost and strictness. user-event is slower — more events, await points between them — and it refuses impossible interactions: clicking an element with pointer-events: none throws. That strictness is the point: when user.click throws, a user is also blocked. Reach for fireEvent only for events a user cannot produce directly (a scroll, a custom event from a non-UI source), not as the default.

act() warnings: a symptom, not a target

The warning — “An update to X inside a test was not wrapped in act(…)” — does not mean “sprinkle act until silence”. RTL already wraps render, fireEvent, and every user-event call in act. The warning means a state update fired while no act-aware scope was open: almost always an async operation your test never awaited — a fetch resolving after your last assertion, a timer firing after the test returned, a missing await on a user-event call. The correct fix is to await the user-visible outcome (await screen.findByText(...)) or make the test own its pending work; wrapping arbitrary lines in act() silences the smoke alarm while the update still lands at an uncontrolled time. Teams that globally filter act warnings out of console.error meet them again as CI flakes, and worse: the late update bleeds into the next test, which is how order-dependent failures are born.

The failure-mode inventory from this lesson’s Hook generalizes: a testid-everywhere suite survives refactors and misses broken UX; a fireEvent-only suite stays green while keyboard and constraint handling rot; an act-suppressing suite converts deterministic warnings into probabilistic flakes. All three share one root: the test stopped resembling the user.