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