用途
React Testing Library 最佳实践是一份面向 React 组件测试的综合指南，专为 AI 智能体和大语言模型设计。它包含跨 9 个类别的 43 条规则，并按影响力排序，用于指导测试编写和代码审查。
何时使用
在以下情况参考这些指南：
- 使用 React Testing Library 编写新的组件测试
- 选择查询方式（getByRole、getByLabelText 等）
- 处理测试中的异步操作（findBy、waitFor）
- 模拟用户交互（userEvent）
- 审查测试中的反模式与实现细节测试
按优先级划分的规则类别
| 优先级 | 类别 | 影响力 | 前缀 |
|---|---|---|---|
| 1 | 查询选择 | CRITICAL | query- |
| 2 | 异步处理 | CRITICAL | async- |
| 3 | 常见反模式 | CRITICAL | anti- |
| 4 | 用户交互 | HIGH | user- |
| 5 | 断言 | HIGH | assert- |
| 6 | 组件初始化 | MEDIUM | setup- |
| 7 | 测试结构 | MEDIUM | struct- |
| 8 | 调试 | LOW-MEDIUM | debug- |
| 9 | 可访问性测试 | LOW | a11y- |
快速参考
1. 查询选择（CRITICAL）
- query-prefer-role - 优先使用 getByRole 而非其他查询
- query-avoid-testid - 避免将 getByTestId 作为主要查询
- query-use-screen - 使用 screen 进行查询
- query-label-text-forms - 表单字段使用 getByLabelText
- query-role-name-option - 在 getByRole 中使用 name 选项
- query-get-vs-query - 元素存在用 getBy，不存在用 queryBy
- query-within-scope - 使用 within() 限定查询范围
2. 异步处理（CRITICAL）
- async-findby-over-waitfor - 使用 findBy 而非 waitFor + getBy
- async-await-findby - 始终 await findBy 查询
- async-single-assertion-waitfor - waitFor 中只放单个断言
- async-no-side-effects-waitfor - 避免在 waitFor 中产生副作用
- async-waitfor-disappear - 使用 waitForElementToBeRemoved
3. 常见反模式（CRITICAL）
- anti-unnecessary-act - 避免不必要的 act() 包裹
- anti-manual-cleanup - 移除手动 cleanup 调用
- anti-implementation-details - 避免测试实现细节
- anti-empty-waitfor - 避免空的 waitFor 回调
- anti-container-queries - 避免使用 container 进行查询
- anti-redundant-roles - 避免添加冗余的 ARIA 角色
4. 用户交互（HIGH）
- user-prefer-userevent - 使用 userEvent 而非 fireEvent
- user-setup-before-render - 在 render 之前设置 userEvent
- user-await-interactions - 始终 await userEvent 交互
- user-keyboard-for-special-keys - 特殊按键使用 keyboard()
- user-clear-before-type - 重新输入前使用 clear()
5. 断言（HIGH）
- 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. 组件初始化（MEDIUM）
- setup-wrapper-providers - 使用 wrapper 选项提供 providers
- setup-custom-render - 创建带 providers 的自定义 render
- setup-mock-modules - 在模块级别 mock 模块
- setup-fake-timers - 使用 fake timers 配置 userEvent
- setup-render-hook - 使用 renderHook 测试 hooks
7. 测试结构（MEDIUM）
- struct-arrange-act-assert - 遵循 Arrange-Act-Assert 模式
- struct-one-behavior-per-test - 每个测试只测试一种行为
- struct-descriptive-names - 使用描述性的测试名称
- struct-avoid-beforeeach-render - 避免在 beforeEach 中 render()
8. 调试（LOW-MEDIUM）
- debug-screen-debug - 使用 screen.debug() 检查 DOM
- debug-logroles - 使用 logRoles 查找可用角色
- debug-testing-playground - 使用 Testing Playground 辅助查询
9. 可访问性测试（LOW）
- a11y-role-queries-verify - 角色查询可验证可访问性
- a11y-verify-focus - 测试焦点管理
- a11y-test-aria-states - 测试 ARIA 状态与属性
如何使用
阅读各个参考文件以获取详细说明和代码示例：
- Section definitions - 类别结构与影响力等级
- Rule template - 添加新规则的模板
参考文件
| 文件 | 描述 |
|---|---|
| references/_sections.md | 类别定义与排序 |
| assets/templates/_template.md | 新规则模板 |
| metadata.json | 版本与参考信息 |