react-testing-library

React Testing Library 最佳实践

涵盖 9 个类别的 43 条规则，用于使用 Testing Library 测试 React 组件，并按影响排序，以指导编写测试和代码审查。

范围

本技能负责 React 组件和钩子的测试机制。对于与框架无关的问题——行为应在哪个层级测试、覆盖率数字的含义、如何选择测试数据、如何消除不稳定测试——请使用 testing-expert。

适用场景

• 使用 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 - 在 getByRole 中使用 name 选项
• 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. 断言（HIGH）

• assert-dom-matchers - 使用 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 选项配置提供程序
• setup-custom-render - 创建包含提供程序的自定义 render
• setup-mock-modules - 在模块级别模拟模块
• setup-fake-timers - 使用虚假计时器配置 userEvent
• setup-render-hook - 使用 renderHook 测试钩子

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 状态和属性

使用方法

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

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

参考文件

文件	说明
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板