React testing

Tests that fail when the feature breaks and pass when it works, whatever the internals look like. Find elements the way a user does, act the way a user does, and wait for what a user would see.

Query by role and name first. If you cannot, the component probably has an accessibility bug.

Mock the edges (network, clock, framework), never your own code.

Versions, source checks, and dates: SOURCES.md.

Procedure

1. Read the component, its existing tests, vitest.config.*, and the setup file. Check the package versions; this skill assumes the stack in SOURCES.md.
2. Pick what the user does and what they should see as a result. That pair is the test.
3. Route by what the test needs, and load only that resource:

writing or fixing a test
      |
      +-- finding an element, asserting present or absent ...... queries.md
      |
      +-- clicking, typing, tabbing, uploading .................. user-events.md
      |
      +-- something appears later, a timer, an act warning ...... async.md
      |
      +-- config, cleanup, providers, hooks, jsdom crashes ...... setup.md
      |
      +-- fetch, vi.mock, next/navigation ...................... network-and-mocks.md
      |
      +-- async page, Server Function, useActionState ........... server-components.md

4. Run the test. Then break the feature on purpose (comment out the handler, return the wrong value) and confirm the test fails. A test that still passes proves nothing.

Where to read

The traps that cost the most time

Review checklist

• Queries use ByRole with name, or ByLabelText/ByText; ByTestId only where no role or text exists
• No role or aria-* added only for the test
• Absence uses queryBy with .not.toBeInTheDocument(); nothing asserts toBeDefined() on a query
• userEvent.setup() per test, and every user-event call is awaited
• Late content uses findBy; waitFor holds one assertion and no side effects; no setTimeout sleeps
• Fake timers under Vitest use shouldAdvanceTime: true and are restored in afterEach
• The setup file imports @testing-library/jest-dom/vitest and calls cleanup (or globals: true)
• The network is mocked with MSW and onUnhandledFrame: 'error'; the failure path has its own test
• No mock of the component, hook, or helper under test
• Assertions check what the user sees or what leaves the component, not internal state
• The test fails when the feature it covers is broken on purpose