component-testing

Component Testing (React Testing Library)

Overview

A component test that queries by data-testid or asserts on internal state proves the implementation didn't change, not that the component works for a user. React Testing Library tests must exercise the component the way a user (and a screen reader) does: find things by role/label/text, interact with them, and assert on what actually rendered.

Core principle: Test behavior, not implementation. If a refactor that keeps the same user-facing behavior breaks the test, the test is coupled to the wrong thing.

Rules

• Query priority: byRole first. Prefer getByRole (with { name: ... }) over byLabelText/byText, and both over byTestId. byTestId is a last resort for a node with no accessible role or text — reach for it only when nothing else identifies the element, and treat its presence as a smell worth a follow-up (usually a missing label/role, per accessibility-basics).
• user-event over fireEvent. fireEvent.click fires one DOM event; userEvent.click simulates the real sequence of events a browser produces (focus, pointer, keyboard) and catches bugs fireEvent cannot (e.g. a control that only works because it happens to be focused). Always await userEvent.setup() / await user.click(...).
• Assert on accessible, user-visible output. Check rendered text, roles, aria-* state (aria-expanded, aria-invalid, aria-disabled), and focus — not component internals, prop values, or CSS class names.
• One behavior per test. A test named for the behavior it proves ("shows a validation error when the field is left empty"), not "renders correctly". Multiple assertions are fine as long as they all check the same behavior; a second, unrelated behavior gets its own test.
• No implementation-detail mocking. Mock the network/API boundary (MSW or the API client module), never a child component or a hook's internals just to make the test pass — that tests the mock, not the component.
• Wire it into npm test. New component test files must run under the project's existing npm test script (Vitest/Jest) with no extra flags — a suite that only runs when invoked by hand is not part of the pipeline (see ci-cd-pipeline-authoring).
• TDD still applies (see tdd-workflow): write the test against the intended behavior first, watch it fail, then implement.