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

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

Templates

Forbidden Patterns

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