Also covers testing React 19 features (useActionState, use()), custom hooks, Suspense boundaries, error boundaries, and accessibility audits with axe-core. Provides Vitest configuration and 9 ready-to-copy test templates. This is a testing-methodology skill layered on top of the React skills (react-19, react-state, react-forms) — it doesn't teach those APIs themselves, only how to test components that use them.
React Testing Library
Test React components the way users interact with them.
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Analyze existing test patterns
- fuse-ai-pilot:research-expert - Verify latest Testing Library docs via Context7/Exa
- 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
- Query by role first -
getByRole is most accessible
- Use userEvent, not fireEvent - Realistic interactions
- waitFor for async - Never
setTimeout
- MSW for API mocking - Don't mock fetch
- 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
await user.click(screen.getByRole('button'))
expect(fn).toHaveBeenCalled()
})
→ See templates/component-basic.md for more examples
Best Practices
Query Priority
getByRole - Buttons, headings, inputs
getByLabelText - Form inputs
getByText - Static text
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
1---2name: react-testing3description: Testing Library for React 19 - render, screen, userEvent, waitFor, Suspense. Use when writing tests for React components with Vitest.4versions:5 "@testing-library/react": 16.1.06 "@testing-library/user-event": 14.5.27 vitest: 2.1.88 msw: 2.7.09 react: 1910user-invocable: true11references: 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, references/templates/basic-setup.md, references/templates/component-basic.md, references/templates/component-async.md, references/templates/form-testing.md, references/templates/hook-basic.md, references/templates/api-integration.md, references/templates/suspense-testing.md, references/templates/error-boundary.md, references/templates/accessibility-audit.md12related-skills: react-19, solid-react, react-state, react-forms13metadata:14 source: https://skillmd.com/skills/fusengine/react-testing15---1617<objective>18Tests React 19 components with Testing Library and Vitest: user-centric queries prioritized by accessibility (`getByRole` first, `getByTestId` last resort), `userEvent` for realistic interactions (never `fireEvent`), `findBy`/`waitFor` for async assertions (never `setTimeout`), and MSW for API mocking (never direct fetch mocking).1920Also covers testing React 19 features (`useActionState`, `use()`), custom hooks, Suspense boundaries, error boundaries, and accessibility audits with axe-core. Provides Vitest configuration and 9 ready-to-copy test templates. This is a testing-methodology skill layered on top of the React skills (react-19, react-state, react-forms) — it doesn't teach those APIs themselves, only how to test components that use them.21</objective>2223# React Testing Library2425Test React components the way users interact with them.2627## Agent Workflow (MANDATORY)2829Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:30311. **fuse-ai-pilot:explore-codebase** - Analyze existing test patterns322. **fuse-ai-pilot:research-expert** - Verify latest Testing Library docs via Context7/Exa333. **mcp__context7__query-docs** - Check userEvent, waitFor patterns3435After implementation, run **fuse-ai-pilot:sniper** for validation.3637---3839## Overview4041### When to Use4243- Testing React component behavior44- Validating user interactions45- Ensuring accessibility compliance46- Mocking API calls with MSW47- Testing custom hooks48- Testing React 19 features (useActionState, use())4950### Why React Testing Library5152| Feature | Benefit |53|---------|---------|54| User-centric | Tests what users see |55| Accessible queries | Encourages a11y markup |56| No implementation details | Resilient to refactoring |57| Vitest integration | 10-20x faster than Jest |5859---6061## Critical Rules62631. **Query by role first** - `getByRole` is most accessible642. **Use userEvent, not fireEvent** - Realistic interactions653. **waitFor for async** - Never `setTimeout`664. **MSW for API mocking** - Don't mock fetch675. **Test behavior, not implementation** - No internal state testing6869---7071## Reference Guide7273### Concepts7475| Topic | Reference |76|-------|-----------|77| Setup & installation | `references/installation.md` |78| Query priority | `references/queries.md` |79| User interactions | `references/user-events.md` |80| Async patterns | `references/async-testing.md` |81| API mocking | `references/msw-setup.md` |82| React 19 hooks | `references/react-19-hooks.md` |83| Accessibility | `references/accessibility-testing.md` |84| Custom hooks | `references/hooks-testing.md` |85| Vitest config | `references/vitest-config.md` |86| Mocking patterns | `references/mocking-patterns.md` |8788### Templates8990| Template | Use Case |91|----------|----------|92| `templates/basic-setup.md` | Vitest + RTL + MSW config |93| `templates/component-basic.md` | Simple component tests |94| `templates/component-async.md` | Loading/error/success |95| `templates/form-testing.md` | Forms + useActionState |96| `templates/hook-basic.md` | Custom hook tests |97| `templates/api-integration.md` | MSW integration tests |98| `templates/suspense-testing.md` | Suspense + use() |99| `templates/error-boundary.md` | Error boundary tests |100| `templates/accessibility-audit.md` | axe-core a11y audit |101102---103104## Forbidden Patterns105106| Pattern | Reason | Alternative |107|---------|--------|-------------|108| `fireEvent` | Not realistic | `userEvent` |109| `setTimeout` | Flaky | `waitFor`, `findBy` |110| `getByTestId` first | Not accessible | `getByRole` |111| Direct fetch mocking | Hard to maintain | MSW |112| Empty `waitFor` | No assertion | Add `expect()` |113114---115116## Quick Start117118### Install119120```bash121npm install -D vitest @testing-library/react \122 @testing-library/user-event @testing-library/jest-dom \123 jsdom msw124```125126→ See `templates/basic-setup.md` for complete configuration127128### Basic Test129130```typescript131import { render, screen } from '@testing-library/react'132import userEvent from '@testing-library/user-event'133134test('button click works', async () => {135 const user = userEvent.setup()136 render(<Button onClick={fn}>Click</Button>)137138 await user.click(screen.getByRole('button'))139140 expect(fn).toHaveBeenCalled()141})142```143144→ See `templates/component-basic.md` for more examples145146---147148## Best Practices149150### Query Priority1511521. `getByRole` - Buttons, headings, inputs1532. `getByLabelText` - Form inputs1543. `getByText` - Static text1554. `getByTestId` - Last resort156157### Async Pattern158159```typescript160// Preferred: findBy161await screen.findByText('Loaded')162163// Alternative: waitFor164await waitFor(() => expect(...).toBeInTheDocument())165```166167→ See `templates/component-async.md`168169### userEvent Setup170171```typescript172const user = userEvent.setup()173await user.click(button)174await user.type(input, 'text')175```176177→ See `references/user-events.md`