react-testing-library

# 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`](references/query-prefer-role.md) - Prefer getByRole over other queries - [`query-avoid-testid`](references/query-avoid-testid.md) - Avoid getByTestId as primary query - [`query-use-screen`](references/query-use-screen.md) - Use screen for queries - [`query-label-text-forms`](references/query-label-text-forms.md) - Use getByLabelText for form fields - [`query-role-name-option`](references/query-role-name-option.md) - Use name option with getByRole - [`query-get-vs-query`](references/query-get-vs-query.md) - Use getBy for present, queryBy for absent - [`query-within-scope`](references/query-within-scope.md) - Use within() to scope queries ### 2. Async Handling (CRITICAL) - [`async-findby-over-waitfor`](references/async-findby-over-waitfor.md) - Use findBy instead of waitFor + getBy - [`async-await-findby`](references/async-await-findby.md) - Always await findBy queries - [`async-single-assertion-waitfor`](references/async-single-assertion-waitfor.md) - Single assertion in waitFor - [`async-no-side-effects-waitfor`](references/async-no-side-effects-waitfor.md) - Avoid side effects in waitFor - [`async-waitfor-disappear`](references/async-waitfor-disappear.md) - Use waitForElementToBeRemoved ### 3. Common Anti-Patterns (CRITICAL) - [`anti-unnecessary-act`](references/anti-unnecessary-act.md) - Avoid unnecessary act() wrapping - [`anti-manual-cleanup`](references/anti-manual-cleanup.md) - Remove manual cleanup calls - [`anti-implementation-details`](references/anti-implementation-details.md) - Avoid testing implementation details - [`anti-empty-waitfor`](references/anti-empty-waitfor.md) - Avoid empty waitFor callbacks - [`anti-container-queries`](references/anti-container-queries.md) - Avoid using container for queries - [`anti-redundant-roles`](references/anti-redundant-roles.md) - Avoid adding redundant ARIA roles ### 4. User Interaction (HIGH) - [`user-prefer-userevent`](references/user-prefer-userevent.md) - Use userEvent over fireEvent - [`user-setup-before-render`](references/user-setup-before-render.md) - Setup userEvent before render - [`user-await-interactions`](references/user-await-interactions.md) - Always await userEvent interactions - [`user-keyboard-for-special-keys`](references/user-keyboard-for-special-keys.md) - Use keyboard() for special keys - [`user-clear-before-type`](references/user-clear-before-type.md) - Use clear() before retyping ### 5. Assertions (HIGH) - [`assert-jest-dom-matchers`](references/assert-jest-dom-matchers.md) - Use jest-dom matchers - [`assert-visible-over-in-document`](references/assert-visible-over-in-document.md) - Use toBeVisible() for visibility - [`assert-text-content`](references/assert-text-content.md) - Use toHaveTextContent() for text - [`assert-have-value`](references/assert-have-value.md) - Use toHaveValue() for inputs - [`assert-accessible-description`](references/assert-accessible-description.md) - Use toHaveAccessibleDescription() ### 6. Component Setup (MEDIUM) - [`setup-wrapper-providers`](references/setup-wrapper-providers.md) - Use wrapper option for providers - [`setup-custom-render`](references/setup-custom-render.md) - Create custom render with providers - [`setup-mock-modules`](references/setup-mock-modules.md) - Mock modules at module level - [`setup-fake-timers`](references/setup-fake-timers.md) - Configure userEvent with fake timers - [`setup-render-hook`](references/setup-render-hook.md) - Use renderHook for testing hooks ### 7. Test Structure (MEDIUM) - [`struct-arrange-act-assert`](references/struct-arrange-act-assert.md) - Follow Arrange-Act-Assert pattern - [`struct-one-behavior-per-test`](references/struct-one-behavior-per-test.md) - Test one behavior per test - [`struct-descriptive-names`](references/struct-descriptive-names.md) - Use descriptive test names - [`struct-avoid-beforeeach-render`](references/struct-avoid-beforeeach-render.md) - Avoid render() in beforeEach ### 8. Debugging (LOW-MEDIUM) - [`debug-screen-debug`](references/debug-screen-debug.md) - Use screen.debug() to inspect DOM - [`debug-logroles`](references/debug-logroles.md) - Use logRoles to find available roles - [`debug-testing-playground`](references/debug-testing-playground.md) - Use Testing Playground for queries ### 9. Accessibility Testing (LOW) - [`a11y-role-queries-verify`](references/a11y-role-queries-verify.md) - Role queries verify accessibility - [`a11y-verify-focus`](references/a11y-verify-focus.md) - Test focus management - [`a11y-test-aria-states`](references/a11y-test-aria-states.md) - Test ARIA states and properties ## How to Use Read individual reference files for detailed explanations and code examples: - [Section definitions](references/_sections.md) - Category structure and impact levels - [Rule template](assets/templates/_template.md) - Template for adding new rules ## Reference Files | File | Description | |------|-------------| | [references/_sections.md](references/_sections.md) | Category definitions and ordering | | [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules | | [metadata.json](metadata.json) | Version and reference information |