用途:以用户交互方式测试 React 组件,通过可访问角色与文本查询元素,而非依赖实现细节,使测试在内部重构后仍稳定。
主要能力与模式:
- 使用 render 与 screen 查询,所有查询走 screen,而非从 render 解构。
- 优先 userEvent 而非 fireEvent:const user = userEvent.setup(); await user.type(...)。
- 查询优先级:getByRole > getByLabelText > getByText > getByTestId。
- 异步用 findBy 与 waitFor,如 await screen.findByRole('alert', { name: /success/i })。
- 避免断言内部状态或实例,改为断言可见输出。
- 断言元素不存在时用 queryBy*(返回 null),不要用 getBy*,否则 .not 断言不可靠。
- 自定义 Hook 用 renderHook(() => useMyHook())。
决策:元素当前存在用 getByRole/getByText;异步出现用 findByRole/findByText;不应存在用 queryByRole;用户输入用 userEvent.setup() 后 type/click;无可访问查询时加 aria-label,getByTestId 为最后手段;副作用用 waitFor。
适用场景:从用户视角测试 React 组件、模拟点击输入表单、编写抗重构测试。不适用:纯函数或服务逻辑(用 jest 技能)、多页 E2E 流程(用 Playwright 或 Cypress)。
边界情况:Portal/模态框用 screen 查询;异步状态用 waitFor 包裹断言;Act 警告需确保异步完成,findBy* 自动处理;上下文用 renderWithProviders 包装;Jest 下 RTL 自动 cleanup,不要手动调用。
限制:资料未提供安装命令、版本要求、收费与平台信息。