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

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