React Testing Library Patterns

Quick Guide: Test React components through user interactions and accessible queries. Use

getByRole

as your primary query. Prefer

userEvent

over

fireEvent

. Use

findBy*

for async content. Test user behavior, not implementation details.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,

import type

, named constants)

(You MUST use the query priority hierarchy:

getByRole

getByLabelText

getByText

getByTestId

(You MUST use

userEvent

fireEvent

(You MUST use

findBy*

waitFor

getBy*

(You MUST test user-visible behavior, NOT implementation details like internal state)

(You MUST use

screen

</critical_requirements>

Auto-detection: React Testing Library, @testing-library/react, render, screen, userEvent, fireEvent, waitFor, findBy, getByRole, getByLabelText, renderHook, within, cleanup, prettyDOM, configure, logRoles, logTestingPlaygroundURL

When to use:

• Testing React component behavior through user interactions
• Verifying accessible element rendering and presence
• Testing form interactions, validation, and submissions
• Testing async component states (loading, error, success)
• Testing custom React hooks with

  renderHook

• Creating custom render functions with providers

When NOT to use:

• E2E testing spanning multiple pages (defer to your E2E testing tool)
• Network request mocking setup (defer to your API mocking solution)
• Testing pure utility functions without React (use unit tests directly)
• Test runner configuration (defer to your test runner skill)

Key patterns covered:

• Query hierarchy and selection strategy
• userEvent vs fireEvent for user simulation
• Async utilities (waitFor, findBy queries)
• Testing hooks with renderHook
• Custom render with providers
• Accessibility testing patterns
• Debug utilities (screen.debug, prettyDOM, logRoles)
• Scoped queries with

  within

• Global configuration options

Detailed Resources:

• For code examples, see

  examples/

  folder:
  • examples/core.md - Query hierarchy examples
  • examples/user-events.md - userEvent patterns
  • examples/async-testing.md - findBy, waitFor, waitForElementToBeRemoved
  • examples/custom-render.md - Custom render with providers
  • examples/hooks.md - renderHook patterns
  • examples/accessibility.md - Accessibility testing patterns
  • examples/scoped-queries.md - within() for scoped queries
  • examples/configuration.md - Global configuration options
• For decision frameworks and anti-patterns, see reference.md

Philosophy

React Testing Library is built on the guiding principle: "The more your tests resemble the way your software is used, the more confidence they can give you."

Core Principles:

1. Test User Behavior, Not Implementation: Query elements the way users find them (by role, label, text), not by test IDs or CSS selectors
2. Accessibility-First Testing: If your test struggles to find an element, your UI likely has accessibility issues
3. No Implementation Details: Avoid testing internal state, refs, or component internals - test what users see and interact with
4. Real DOM Interactions: Render components to a real DOM (jsdom) to catch real integration issues

When to use React Testing Library:

• Integration testing components with their children
• Testing user interaction flows within a component
• Verifying accessibility of interactive elements
• Testing form validation and submission
• Testing conditional rendering based on props/state

When NOT to use:

• Full user journey testing (use E2E tests)
• Testing visual appearance (use visual regression tools)
• Testing network requests directly (test component behavior with mocked responses)
• Testing third-party library behavior (trust the library's tests)

Core Patterns

Pattern 1: Query Priority Hierarchy

Select queries based on accessibility hierarchy. This ensures tests align with how users (including those using assistive technology) interact with your UI.

Query Priority Order

// Priority 1: Accessible to Everyone
getByRole(); // BEST - queries accessibility tree
getByLabelText(); // Form fields - how users navigate forms
getByPlaceholderText(); // When no label (not ideal, but sometimes necessary)
getByText(); // Non-interactive content (divs, spans, paragraphs)
getByDisplayValue(); // Form elements by current value

// Priority 2: Semantic Queries
getByAltText(); // Images, areas, inputs with alt
getByTitle(); // Least reliable - not consistently read by screen readers

// Priority 3: Test IDs (Last Resort)
getByTestId(); // Only when other methods fail

See examples/core.md for complete query examples.

Why this hierarchy: Users interact with your app through visible text, labels, and semantic roles - not through test IDs or CSS classes. Testing this way ensures your app is accessible.

Pattern 2: userEvent Over fireEvent

Use

userEvent

Key Differences

fireEvent

userEvent

change

keyDown

keyPress

keyUp

click

pointerDown

mouseDown

pointerUp

mouseUp

click

Setup Pattern (userEvent v14+)

import userEvent from "@testing-library/user-event";

// Setup BEFORE interactions - creates isolated user session
const user = userEvent.setup();

// Then use throughout test
await user.click(button);
await user.type(input, "Hello");

See examples/user-events.md for complete userEvent examples.

Why userEvent:

fireEvent

userEvent

Pattern 3: Async Utilities

Use

findBy*

waitFor

findBy vs waitFor

// GOOD: findBy for async elements
const button = await screen.findByRole("button", { name: /submit/i });

// BAD: waitFor + getBy for async elements
await waitFor(() => {
  screen.getByRole("button", { name: /submit/i }); // DON'T DO THIS
});

waitFor Best Practices

// GOOD: Single assertion in waitFor
await waitFor(() => {
  expect(screen.getByText(/success/i)).toBeInTheDocument();
});

// BAD: Multiple assertions in waitFor
await waitFor(() => {
  expect(screen.getByText(/success/i)).toBeInTheDocument();
  expect(screen.getByText(/complete/i)).toBeInTheDocument(); // DON'T
});

// BAD: Side effects in waitFor
await waitFor(() => {
  user.click(button); // DON'T - side effects outside waitFor
  expect(result).toBe(true);
});

See examples/async-testing.md for complete async testing examples.

Why this matters:

waitFor

Pattern 4: Testing Hooks with renderHook

Use

renderHook

Basic renderHook Usage

import { renderHook, act } from "@testing-library/react";

const { result } = renderHook(() => useCounter());

// Access current value
expect(result.current.count).toBe(0);

// Update state with act()
act(() => {
  result.current.increment();
});

expect(result.current.count).toBe(1);

With Context Providers

const wrapper = ({ children }: { children: React.ReactNode }) => (
  <ThemeProvider theme="dark">{children}</ThemeProvider>
);

const { result } = renderHook(() => useTheme(), { wrapper });

See examples/hooks.md for complete renderHook examples.

When to use renderHook:

• Testing library hooks you're publishing
• Testing complex hook logic in isolation
• Testing hooks with many edge cases

When to prefer component testing:

• The hook is tightly coupled to UI
• You want to test the hook in realistic context
• The component test is simpler to write

Pattern 5: Custom Render with Providers

Create a custom render function that wraps components with all necessary providers.

Custom Render Setup

// test-utils.tsx
import { render, type RenderOptions } from "@testing-library/react";
import type { ReactElement } from "react";

interface AllProvidersProps {
  children: React.ReactNode;
}

function AllProviders({ children }: AllProvidersProps) {
  // Wrap with your app's providers in correct nesting order
  // return (
  //   <ThemeProvider>
  //     <AuthProvider>
  //       {children}
  //     </AuthProvider>
  //   </ThemeProvider>
  // );
  return <>{children}</>;
}

function customRender(
  ui: ReactElement,
  options?: Omit<RenderOptions, "wrapper">
) {
  return render(ui, { wrapper: AllProviders, ...options });
}

// Re-export everything
export * from "@testing-library/react";
export { customRender as render };

See examples/custom-render.md for complete custom render examples.

Why custom render: Avoids repeating provider boilerplate in every test. Creates a consistent test environment matching your app.

Pattern 6: Accessibility Testing Patterns

Use queries that enforce accessibility. If your test struggles to find an element, your UI likely has accessibility issues.

Role-Based Queries

// GOOD: Tests that element is accessible
screen.getByRole("button", { name: /submit/i });
screen.getByRole("textbox", { name: /email/i });
screen.getByRole("checkbox", { name: /agree to terms/i });
screen.getByRole("combobox", { name: /country/i });

// GOOD: Verify accessible names
expect(screen.getByRole("button", { name: /submit/i })).toBeEnabled();

// BAD: Using test IDs when accessible queries work
screen.getByTestId("submit-button"); // DON'T when getByRole works

logRoles for Debugging

import { logRoles } from "@testing-library/react";

// Log all accessible roles in a container
logRoles(container);

See examples/accessibility.md for complete accessibility testing examples.

Why this matters: Screen readers and assistive technologies use the accessibility tree. Testing with accessible queries ensures your app works for all users.

Pattern 7: Debug Utilities

Use debug utilities to understand what's rendered and troubleshoot failing tests.

screen.debug()

// Debug entire document
screen.debug();

// Debug specific element
screen.debug(screen.getByRole("form"));

// Debug multiple elements
screen.debug(screen.getAllByRole("listitem"));

prettyDOM for Custom Output

import { prettyDOM } from "@testing-library/react";

// Get formatted DOM string (for logging, assertions)
const domString = prettyDOM(element);
console.log(domString);

// Customize output length
const domString = prettyDOM(element, 15000); // Increase from 7000 default

logTestingPlaygroundURL

import { logTestingPlaygroundURL } from "@testing-library/react";

// Logs URL to Testing Playground with current DOM
logTestingPlaygroundURL();
// Visit the URL to get suggested queries

When to use debug:

• Test is failing and you don't understand why
• Element can't be found with expected query
• Need to understand current DOM state

Remove before committing: Debug statements are for development only.

Pattern 8: Scoped Queries with within

Use

within

Basic Usage

import { render, screen, within } from "@testing-library/react";

test("selects item in specific section", () => {
  render(<Dashboard />);

  // Get a specific section
  const sidebar = screen.getByRole("navigation");

  // Query only within that section
  const homeLink = within(sidebar).getByRole("link", { name: /home/i });
  expect(homeLink).toBeInTheDocument();
});

Testing List Items

test("each row has edit button", () => {
  render(<UserTable users={mockUsers} />);

  const rows = screen.getAllByRole("row");

  // Skip header row, check each data row
  rows.slice(1).forEach((row) => {
    const editButton = within(row).getByRole("button", { name: /edit/i });
    expect(editButton).toBeInTheDocument();
  });
});

See examples/scoped-queries.md for complete within() examples.

When to use within:

• Components with repeated structures (tables, lists, cards)
• Multiple sections with similar elements
• Testing specific regions of a page

Pattern 9: Global Configuration

Configure Testing Library defaults for your project using

configure

Configuration Options

import { configure } from "@testing-library/react";

// In test setup file
configure({
  // Custom test ID attribute (default: "data-testid")
  testIdAttribute: "data-test-id",

  // Async utility timeout (default: 1000ms)
  asyncUtilTimeout: 5000,

  // Enable React strict mode warnings in tests
  reactStrictMode: true,
});

userEvent Setup Options

import userEvent from "@testing-library/user-event";

// With fake timers - pass your test runner's timer advance function
const user = userEvent.setup({
  advanceTimers: vi.advanceTimersByTime, // Required when using fake timers
});

// Skip pointer events check (for elements with pointer-events: none)
const user = userEvent.setup({
  pointerEventsCheck: 0, // 0 = never check, 1 = check once, 2 = check per API
});

// Custom delay between events
const user = userEvent.setup({
  delay: null, // null = no delay (faster tests)
});

See examples/configuration.md for complete configuration examples.

When to configure:

• Project uses custom test ID attribute
• Tests need longer async timeouts
• Using fake timers with userEvent

Integration Guide

Test runner setup:

• Import jest-dom matchers in your test setup file for semantic assertions (

  toBeInTheDocument

  ,

  toHaveValue

  , etc.)
• Cleanup happens automatically in modern setups - no manual

  afterEach(cleanup)

  needed

Mocking approach:

• Mock data at the network boundary, not at the component level
• Set up mock responses before rendering, not after

Framework providers:

• Custom render wraps components with your app's providers (see Pattern 5)
• SSR frameworks may need additional DOM configuration

<red_flags>

RED FLAGS

High Priority Issues:

• Using

  getByTestId

  when accessible queries work - Indicates UI may not be accessible, test doesn't reflect user experience
• Using

  waitFor

  to find elements - Use

  findBy*

  instead, produces better error messages and cleaner code
• Using

  fireEvent

  for user interactions - Use

  userEvent

  for realistic event chains
• Multiple assertions in single

  waitFor

  - Causes slow test failures and unpredictable behavior
• Testing internal component state - Test user-visible behavior, not implementation details

Medium Priority Issues:

• Destructuring render return instead of using

  screen

  -

  screen

  provides cleaner, more maintainable code
• Manual

  cleanup

  calls - Modern frameworks handle cleanup automatically
• Wrapping

  render

  or

  fireEvent

  in

  act()

  - They already wrap in

  act

  , double-wrapping is unnecessary
• Using

  querySelector

  or CSS selectors - Use Testing Library queries for accessibility-aligned tests

Common Mistakes:

• Forgetting to

  await

  userEvent methods (all are async in v14+)
• Using

  getBy*

  for elements that appear asynchronously
• Putting side effects inside

  waitFor

  callbacks
• Not setting up userEvent before interactions (

  const user = userEvent.setup()

  )

Gotchas & Edge Cases:

• userEvent.setup()

  must be called before any interactions (v14+ requirement)

• queryBy*

  returns

  null

  for missing elements (use for absence assertions only)

• findBy*

  has default timeout of 1000ms (configurable via options)

• result.current

  in renderHook is a ref - value updates on each access
• Empty

  waitFor(() => {})

  creates fragile timing-dependent tests
• Prefer targeted assertions over snapshots - large snapshots produce noise, false positives, and don't communicate test intent
• Snapshot testing is only appropriate for small, stable components with known output (icons, breadcrumbs)
• Remove

  screen.debug()

  calls before committing - they are for development only

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(You MUST use the query priority hierarchy:

getByRole

getByLabelText

getByText

getByTestId

(You MUST use

userEvent

fireEvent

(You MUST use

findBy*

waitFor

getBy*

(You MUST test user-visible behavior, NOT implementation details like internal state)

(You MUST use

screen

Failure to follow these rules will produce brittle tests that don't reflect real user interactions and miss accessibility issues.

</critical_reminders>