React Testing Library Best Practices

Comprehensive testing guide for React components using Testing Library, designed for AI agents and LLMs. Contains 43 rules across 9 categories, prioritized by impact to guide test writing and code review.

When to Apply

Reference these guidelines when:

• Writing new component tests with React Testing Library

• Selecting queries (getByRole, getByLabelText, etc.)

• Handling async operations in tests (findBy, waitFor)

• Simulating user interactions (userEvent)

• Reviewing tests for anti-patterns and implementation detail testing

Rule Categories by Priority

Priority Category Impact Prefix

1 Query Selection CRITICAL query-

2 Async Handling CRITICAL async-

3 Common Anti-Patterns CRITICAL anti-

4 User Interaction HIGH user-

5 Assertions HIGH assert-

6 Component Setup MEDIUM setup-

7 Test Structure MEDIUM struct-

8 Debugging LOW-MEDIUM debug-

9 Accessibility Testing LOW a11y-

Quick Reference

1. Query Selection (CRITICAL)

• query-prefer-role

• Prefer getByRole over other queries

• query-avoid-testid

• Avoid getByTestId as primary query

• query-use-screen

• Use screen for queries

• query-label-text-forms

• Use getByLabelText for form fields

• query-role-name-option

• Use name option with getByRole

• query-get-vs-query

• Use getBy for present, queryBy for absent

• query-within-scope

• Use within() to scope queries

2. Async Handling (CRITICAL)

• async-findby-over-waitfor

• Use findBy instead of waitFor + getBy

• async-await-findby

• Always await findBy queries

• async-single-assertion-waitfor

• Single assertion in waitFor

• async-no-side-effects-waitfor

• Avoid side effects in waitFor

• async-waitfor-disappear

• Use waitForElementToBeRemoved

3. Common Anti-Patterns (CRITICAL)

• anti-unnecessary-act

• Avoid unnecessary act() wrapping

• anti-manual-cleanup

• Remove manual cleanup calls

• anti-implementation-details

• Avoid testing implementation details

• anti-empty-waitfor

• Avoid empty waitFor callbacks

• anti-container-queries

• Avoid using container for queries

• anti-redundant-roles

• Avoid adding redundant ARIA roles

4. User Interaction (HIGH)

• user-prefer-userevent

• Use userEvent over fireEvent

• user-setup-before-render

• Setup userEvent before render

• user-await-interactions

• Always await userEvent interactions

• user-keyboard-for-special-keys

• Use keyboard() for special keys

• user-clear-before-type

• Use clear() before retyping

5. Assertions (HIGH)

• assert-jest-dom-matchers

• Use jest-dom matchers

• assert-visible-over-in-document

• Use toBeVisible() for visibility

• assert-text-content

• Use toHaveTextContent() for text

• assert-have-value

• Use toHaveValue() for inputs

• assert-accessible-description

• Use toHaveAccessibleDescription()

6. Component Setup (MEDIUM)

• setup-wrapper-providers

• Use wrapper option for providers

• setup-custom-render

• Create custom render with providers

• setup-mock-modules

• Mock modules at module level

• setup-fake-timers

• Configure userEvent with fake timers

• setup-render-hook

• Use renderHook for testing hooks

7. Test Structure (MEDIUM)

• struct-arrange-act-assert

• Follow Arrange-Act-Assert pattern

• struct-one-behavior-per-test

• Test one behavior per test

• struct-descriptive-names

• Use descriptive test names

• struct-avoid-beforeeach-render

• Avoid render() in beforeEach

8. Debugging (LOW-MEDIUM)

• debug-screen-debug

• Use screen.debug() to inspect DOM

• debug-logroles

• Use logRoles to find available roles

• debug-testing-playground

• Use Testing Playground for queries

9. Accessibility Testing (LOW)

• a11y-role-queries-verify

• Role queries verify accessibility

• a11y-verify-focus

• Test focus management

• a11y-test-aria-states

• Test ARIA states and properties

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels

• Rule template - Template for adding new rules

Reference Files

File Description

references/_sections.md Category definitions and ordering

assets/templates/_template.md Template for new rules

metadata.json Version and reference information