React Testing Library

Agent Workflow (MANDATORY)

TeamCreate

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

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

references/installation.md

references/queries.md

references/user-events.md

references/async-testing.md

references/msw-setup.md

references/react-19-hooks.md

references/accessibility-testing.md

references/hooks-testing.md

references/vitest-config.md

references/mocking-patterns.md

Templates

templates/basic-setup.md

templates/component-basic.md

templates/component-async.md

templates/form-testing.md

templates/hook-basic.md

templates/api-integration.md

templates/suspense-testing.md

templates/error-boundary.md

templates/accessibility-audit.md

Forbidden Patterns

fireEvent

userEvent

setTimeout

waitFor

findBy

getByTestId

getByRole

waitFor

expect()

Quick Start

Install

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

templates/basic-setup.md

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()
})

templates/component-basic.md

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())

templates/component-async.md

userEvent Setup

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

references/user-events.md