react-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Testing Library

Test React components the way users interact with them.

以用户与组件交互的方式测试React组件。

Agent Workflow (MANDATORY)

Agent工作流程（强制要求）

Before ANY implementation, use

TeamCreate

to spawn 3 agents:

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.

在进行任何实现之前，使用

TeamCreate

生成3个Agent：

fuse-ai-pilot:explore-codebase - 分析现有测试模式
fuse-ai-pilot:research-expert - 通过Context7/Exa验证最新的Testing Library文档
mcp__context7__query-docs - 检查userEvent、waitFor的使用模式

实现完成后，运行fuse-ai-pilot:sniper进行验证。

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

测试React组件行为
验证用户交互
确保无障碍合规性
使用MSW模拟API调用
测试自定义hooks
测试React 19特性（useActionState、use()）

Why React Testing Library

为什么选择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

特性	优势
以用户为中心	测试用户实际看到的内容
无障碍查询	鼓励编写符合a11y的标记
不关注实现细节	重构时更稳定
与Vitest集成	速度比Jest快10-20倍

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

优先按角色查询 -
```
getByRole
```
是最符合无障碍标准的方式
使用userEvent而非fireEvent - 模拟真实的用户交互
异步操作使用waitFor - 绝对不要使用
```
setTimeout
```
使用MSW模拟API - 不要直接mock fetch
测试行为而非实现 - 不要测试内部状态

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`

主题	参考文档
安装与配置	`references/installation.md`
查询优先级	`references/queries.md`
用户交互	`references/user-events.md`
异步测试模式	`references/async-testing.md`
API模拟	`references/msw-setup.md`
React 19 Hooks	`references/react-19-hooks.md`
无障碍测试	`references/accessibility-testing.md`
自定义Hooks测试	`references/hooks-testing.md`
Vitest配置	`references/vitest-config.md`
模拟模式	`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

模板	使用场景
`templates/basic-setup.md`	Vitest + RTL + MSW配置
`templates/component-basic.md`	简单组件测试
`templates/component-async.md`	加载/错误/成功状态测试
`templates/form-testing.md`	表单 + useActionState测试
`templates/hook-basic.md`	自定义Hook测试
`templates/api-integration.md`	MSW集成测试
`templates/suspense-testing.md`	Suspense + use()测试
`templates/error-boundary.md`	错误边界测试
`templates/accessibility-audit.md`	axe-core无障碍审计

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

模式	原因	替代方案
`fireEvent`	交互不真实	`userEvent`
`setTimeout`	测试不稳定	`waitFor` , `findBy`
优先使用 `getByTestId`	不符合无障碍标准	`getByRole`
直接mock fetch	难以维护	MSW
空的 `waitFor`	没有断言	添加 `expect()`

Quick Start

快速开始

Install

安装

bash

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

bash

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

→ 查看

templates/basic-setup.md

获取完整配置

Basic Test

基础测试示例

typescript

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

typescript

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

查询优先级

```
getByRole
```
- Buttons, headings, inputs
```
getByLabelText
```
- Form inputs
```
getByText
```
- Static text
```
getByTestId
```
- Last resort

```
getByRole
```
- 按钮、标题、输入框
```
getByLabelText
```
- 表单输入框
```
getByText
```
- 静态文本
```
getByTestId
```
- 最后的选择

Async Pattern

异步测试模式

typescript

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

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

→ See

templates/component-async.md

typescript

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

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

→ 查看

templates/component-async.md

userEvent Setup

userEvent配置

typescript

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

→ See

references/user-events.md

typescript

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

→ 查看

references/user-events.md