React测试库技能Skill react-testing-library

---

name: react-testing-library description: React Testing Library 最佳实践，用于编写可维护、用户中心的测试。适用于编写、审查或重构 RTL 测试。在测试文件、测试模式、getBy/queryBy 查询、userEvent、waitFor 和组件测试时触发。

React 测试库最佳实践

使用 Testing Library 的 React 组件综合测试指南，专为 AI 代理和 LLM 设计。包含 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 - 始终 await 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 - 在渲染前设置 userEvent
• user-await-interactions - 始终 await 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 选项
• setup-custom-render - 创建带有提供者的自定义 render
• setup-mock-modules - 在模块级别模拟模块
• setup-fake-timers - 使用假计时器配置 userEvent
• setup-render-hook - 使用 renderHook 测试钩子

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

如何使用

阅读个别参考文件以获取详细解释和代码示例：

• Section definitions - 类别结构和影响级别
• Rule template - 添加新规则的模板

参考文件

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