React Testing Checklist: 25 Essential Steps

Set up Vitest or Jest with `@testing-library/react` and `@testing-library/jest-dom`. Vitest is preferred for Vite-based projects since it shares your app's transform pipeline, eliminating configuration drift between dev and test environments.

Set `environment: 'jsdom'` (or `happy-dom` for faster execution) in your test config. React components need a DOM to render into. Without this, any test that renders a component will fail with cryptic `document is not defined` errors.

Wrap `@testing-library/react`'s `render` with your app's providers (Router, Theme, QueryClient, Auth). Export this from a `test-utils.ts` file. This prevents every test file from individually assembling the provider tree and keeps tests resilient to provider changes.

Install `msw` (Mock Service Worker) to intercept network requests at the service worker level. MSW mocks work identically in tests and browser dev mode, which means your test mocks can double as development stubs. Define handlers for all critical API endpoints.

Add `test`, `test:watch`, and `test:coverage` scripts. Set coverage thresholds (start with 60% and increase) in your config so CI fails when coverage drops. Focus thresholds on branches and functions rather than raw line coverage.

Use `getByRole`, `getByLabelText`, and `getByText` as primary queries. These mirror how assistive technology and real users find elements. Reserve `data-testid` for cases where no accessible query exists — those cases often indicate an accessibility gap worth fixing.

Use `@testing-library/user-event` for clicks, typing, and keyboard navigation. Unlike `fireEvent`, `userEvent` dispatches the full sequence of browser events (pointerdown, mousedown, focus, click) so your tests catch event handler bugs that `fireEvent` misses.

Every component that fetches data should have tests for all four states. Mock the API to return loading delays, error responses, empty arrays, and populated data. Users encounter all of these states — your tests should too.

Never assert on internal state, hook return values, or component instance methods. Test what the user sees and what side effects occur. If you refactor from useState to useReducer, your tests should still pass without changes. Fragile tests are worse than no tests.

Use `queryByRole` (returns null) instead of `getByRole` (throws) when asserting an element is absent. Verify that modals, tooltips, dropdowns, and error messages appear and disappear based on user actions. Test both the show and hide transitions.

Fill each form field using `userEvent.type`, submit the form, and assert on the result. Test the happy path (valid data submits successfully) and at least two error paths (required field empty, invalid format). Check that error messages appear next to the correct fields.

Trigger each validation rule and verify the correct error message renders. Test blur-triggered validation (field loses focus), submit-triggered validation (form submitted with errors), and that errors clear when the user corrects the input.

Wrap assertions that depend on async state updates in `waitFor` or use `findByRole` (which waits automatically). Never use `setTimeout` or fixed delays in tests — they make tests slow and flaky. If you need `act()` warnings to go away, your component needs a proper loading state.

Verify that submit buttons show a loading indicator and become disabled during API calls. Double-submission bugs are common in production and easy to catch in tests. Assert the button is disabled after click and re-enabled after the response.

If your app uses optimistic UI updates, test that the UI updates immediately on user action, then verify it stays updated on success or rolls back on failure. Mock the API to fail after optimistic update to test the rollback path specifically.

Identify your app's 3-5 most important flows (signup, checkout, search, etc.) and write integration tests that render the full page/route. These tests catch bugs that unit tests miss — broken prop passing between components, incorrect context values, and missing error boundaries.

Wrap components in `MemoryRouter` with an initial route and verify that link clicks and programmatic navigation change the rendered content. Test protected routes by rendering without auth context and verifying the redirect to login.

Create a test component that throws during render and wrap it with your error boundary. Verify the fallback UI appears and includes a recovery mechanism (retry button, link to home). Suppress the expected console.error to keep test output clean.

Don't test context in isolation — test it through components that consume it. Render a consumer component, trigger actions that change context (theme toggle, locale switch), and verify the consumer re-renders with updated values.

Verify that Tab moves focus in logical order, Escape closes modals and returns focus to the trigger, and Enter/Space activates interactive elements. These tests catch accessibility regressions and are easy to automate with `userEvent.tab()` and `userEvent.keyboard()`.

Configure GitHub Actions or your CI system to run the full test suite on every PR. Block merges when tests fail. Fast feedback on PRs catches regressions before they reach main. Use sharding to parallelize if the suite exceeds 5 minutes.

Use Chromatic, Percy, or Playwright's screenshot comparison for components where visual appearance matters (design system, landing pages). Visual tests catch CSS regressions that functional tests can't detect, like broken layouts or wrong colors.

Large snapshot tests always get approved blindly when they fail. Replace them with targeted assertions: check that specific text renders, specific elements have correct attributes, specific ARIA states are set. One precise assertion beats a thousand-line snapshot.

Call `cleanup` after each test (React Testing Library does this automatically in most setups). Reset MSW handlers in `afterEach`. Clear any localStorage or sessionStorage mocks. Test isolation prevents the most common source of flaky tests: shared mutable state.

A flaky test that passes 90% of the time trains your team to re-run CI and ignore failures. Track flaky tests with your CI provider's flaky test detection, and treat fixing them as high priority. Either make the test deterministic or delete it.