react-testing

React Testing Library

Test React components the way users interact with them.

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

1. fuse-ai-pilot:explore-codebase - Analyze existing test patterns
2. fuse-ai-pilot:research-expert - Verify latest Testing Library docs via Context7/Exa
3. mcp__context7__query-docs - Check userEvent, waitFor patterns

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

When to Use

• Testing React component behavior
• Validating user interactions
• Ensuring accessibility compliance
• Mocking API calls with MSW
• Testing custom hooks
• Testing React 19 features (useActionState, use())

Why React Testing Library

| Feature | Benefit | |---------|---------| | User-centric | Tests what users see | | Accessible queries | Encourages a11y markup | | No implementation details | Resilient to refactoring | | Vitest integration | 10-20x faster than Jest |

Critical Rules

1. Query by role first - getByRole is most accessible
2. Use userEvent, not fireEvent - Realistic interactions
3. waitFor for async - Never setTimeout
4. MSW for API mocking - Don't mock fetch
5. Test behavior, not implementation - No internal state testing

Reference Guide

Concepts

| Topic | Reference | |-------|-----------| | Setup & installation | references/installation.md | | Query priority | references/queries.md | | User interactions | references/user-events.md | | Async patterns | references/async-testing.md | | API mocking | references/msw-setup.md | | React 19 hooks | references/react-19-hooks.md | | Accessibility | references/accessibility-testing.md | | Custom hooks | references/hooks-testing.md | | Vitest config | references/vitest-config.md | | Mocking patterns | references/mocking-patterns.md |

Templates

| Template | Use Case | |----------|----------| | templates/basic-setup.md | Vitest + RTL + MSW config | | templates/component-basic.md | Simple component tests | | templates/component-async.md | Loading/error/success | | templates/form-testing.md | Forms + useActionState | | templates/hook-basic.md | Custom hook tests | | templates/api-integration.md | MSW integration tests | | templates/suspense-testing.md | Suspense + use() | | templates/error-boundary.md | Error boundary tests | | templates/accessibility-audit.md | axe-core a11y audit |

Forbidden Patterns

| Pattern | Reason | Alternative | |---------|--------|-------------| | fireEvent | Not realistic | userEvent | | setTimeout | Flaky | waitFor, findBy | | getByTestId first | Not accessible | getByRole | | Direct fetch mocking | Hard to maintain | MSW | | Empty waitFor | No assertion | Add expect() |

Quick Start

Install

npm install -D vitest @testing-library/react \
  @testing-library/user-event @testing-library/jest-dom \
  jsdom msw

→ See templates/basic-setup.md for complete configuration

Basic Test

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'

test('button click works', async () => {
  const user = userEvent.setup()
  render(<Button onClick={fn}>Click</Button>)

  await user.click(screen.getByRole('button'))

  expect(fn).toHaveBeenCalled()
})

→ See templates/component-basic.md for more examples

Best Practices

Query Priority

1. getByRole - Buttons, headings, inputs
2. getByLabelText - Form inputs
3. getByText - Static text
4. getByTestId - Last resort

Async Pattern

// Preferred: findBy
await screen.findByText('Loaded')

// Alternative: waitFor
await waitFor(() => expect(...).toBeInTheDocument())

→ See templates/component-async.md

userEvent Setup

const user = userEvent.setup()
await user.click(button)
await user.type(input, 'text')

→ See references/user-events.md