Agent skill

react-testing-library-best-practices

React Testing Library best practices for writing maintainable, user-centric tests. Use when writing, reviewing, or refactoring RTL tests. Triggers on test files, testing patterns, getBy/queryBy queries, userEvent, waitFor, and component testing.

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/react-testing-library

SKILL.md

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

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results