react-testing-library

React Testing Library 最佳实践

面向 AI Agent 和大模型的 React 组件 Testing Library 综合测试指南。包含 9 个类别中的 43 条规则，并按影响优先级排序，指导测试编写和代码审查。

适用场景

在以下情况下参考这些指南：

• 使用 React Testing Library 编写新的组件测试
• 选择查询方式（getByRole、getByLabelText 等）
• 处理测试中的异步操作（findBy、waitFor）
• 模拟用户交互（userEvent）
• 审查测试中的反模式和对实现细节的测试

按优先级划分的规则类别

优先级	类别	影响	前缀
1	查询选择	严重	query-
2	异步处理	严重	async-
3	常见反模式	严重	anti-
4	用户交互	高	user-
5	断言	高	assert-
6	组件设置	中	setup-
7	测试结构	中	struct-
8	调试	低至中	debug-
9	无障碍测试	低	a11y-

快速参考

1. 查询选择（严重）

• query-prefer-role - 优先使用 getByRole，而不是其他查询方式
• query-avoid-testid - 避免将 getByTestId 作为主要查询方式
• query-use-screen - 使用 screen 进行查询
• query-label-text-forms - 使用 getByLabelText 查询表单字段
• query-role-name-option - 将 name 选项与 getByRole 搭配使用
• query-get-vs-query - 元素存在时使用 getBy，不存在时使用 queryBy
• query-within-scope - 使用 within() 限定查询范围

2. 异步处理（严重）

• async-findby-over-waitfor - 使用 findBy，而不是 waitFor + getBy
• async-await-findby - 始终等待 findBy 查询完成
• async-single-assertion-waitfor - 在 waitFor 中只进行一次断言
• async-no-side-effects-waitfor - 避免在 waitFor 中产生副作用
• async-waitfor-disappear - 使用 waitForElementToBeRemoved

3. 常见反模式（严重）

• anti-unnecessary-act - 避免不必要地使用 act() 包裹
• anti-manual-cleanup - 移除手动清理调用
• anti-implementation-details - 避免测试实现细节
• anti-empty-waitfor - 避免使用空的 waitFor 回调
• anti-container-queries - 避免使用 container 进行查询
• anti-redundant-roles - 避免添加冗余的 ARIA 角色

4. 用户交互（高）

• user-prefer-userevent - 使用 userEvent，而不是 fireEvent
• user-setup-before-render - 在 render 之前设置 userEvent
• user-await-interactions - 始终等待 userEvent 交互完成
• user-keyboard-for-special-keys - 使用 keyboard() 处理特殊按键
• user-clear-before-type - 重新输入前使用 clear()

5. 断言（高）

• assert-jest-dom-matchers - 使用 jest-dom 匹配器
• assert-visible-over-in-document - 使用 toBeVisible() 检查可见性
• assert-text-content - 使用 toHaveTextContent() 检查文本
• assert-have-value - 使用 toHaveValue() 检查输入值
• assert-accessible-description - 使用 toHaveAccessibleDescription()

6. 组件设置（中）

• setup-wrapper-providers - 使用 wrapper 选项配置 providers
• setup-custom-render - 创建带有 providers 的自定义 render
• setup-mock-modules - 在模块级别模拟模块
• setup-fake-timers - 使用 fake timers 配置 userEvent
• setup-render-hook - 使用 renderHook 测试 hooks

7. 测试结构（中）

• struct-arrange-act-assert - 遵循 Arrange-Act-Assert 模式
• struct-one-behavior-per-test - 每个测试只测试一种行为
• struct-descriptive-names - 使用描述性测试名称
• struct-avoid-beforeeach-render - 避免在 beforeEach 中调用 render()

8. 调试（低至中）

• debug-screen-debug - 使用 screen.debug() 检查 DOM
• debug-logroles - 使用 logRoles 查找可用角色
• debug-testing-playground - 使用 Testing Playground 编写查询

9. 无障碍测试（低）

• a11y-role-queries-verify - 角色查询可验证无障碍性
• a11y-verify-focus - 测试焦点管理
• a11y-test-aria-states - 测试 ARIA 状态和属性

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	说明
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息