Testing Library 技能面向 React 组件测试，提供基于 Testing Library 的查询、交互与异步测试模式。资料标注状态为 Production Ready，最后更新于 2026-02-06，版本为 React Testing Library 16.x、User Event 14.x。
一、用途 用于编写 React 组件测试，强调以无障碍优先的方式查询元素、模拟真实用户交互，并处理异步渲染与网络请求。
二、主要能力
- 查询（Queries）：按优先级推荐 getByRole、getByLabelText、getByPlaceholderText、getByText、getByTestId（仅作最后手段）。查询变体包括 getBy（元素存在，不存在则抛错）、queryBy（可能不存在，返回 null 不抛错）、findBy（异步等待，返回 Promise）、getAllBy、queryAllBy、findAllBy。
- 用户交互（user-event）：资料建议始终使用 userEvent 而非 fireEvent，以模拟真实用户行为。常见事件包括 click、dblClick、tripleClick、type、clear、keyboard（含特殊键与组合键）、tab、selectOptions、hover、unhover、copy、paste。
- 异步测试：findBy 用于等待元素出现（自动重试）；waitFor 用于等待条件成立；waitForElementToBeRemoved 用于等待元素消失。
- MSW 集成：通过 Mock Service Worker 在网络层模拟 API，包含 handlers、server 设置，以及使用 server.use 在单个测试中覆盖处理器。
- 无障碍测试：可结合 jest-axe 检查无障碍违规；资料指出使用 getByRole 本身即隐含无障碍测试。
- 常见测试模式：表单校验、模态框/对话框开关、列表渲染。
- 常用匹配器（jest-dom）：存在性（toBeInTheDocument、toBeVisible、toBeEmptyDOMElement）、状态（toBeEnabled、toBeDisabled、toBeChecked、toBeRequired）、内容（toHaveTextContent、toHaveValue、toHaveAttribute）、样式（toHaveClass、toHaveStyle）、焦点（toHaveFocus）。
- 调试：screen.debug() 打印 DOM，logRoles 列出可用角色。
三、使用方式 安装（Vitest）：pnpm add -D @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom；或使用 Jest：pnpm add -D @testing-library/react @testing-library/user-event @testing-library/jest-dom。 Setup 文件（src/test/setup.ts）导入 '@testing-library/jest-dom/vitest' 与 cleanup，并在 afterEach 中调用 cleanup()。 Vitest 配置（vitest.config.ts）设置 globals: true、environment: 'jsdom'、setupFiles: ['./src/test/setup.ts']。 MSW 需额外安装 pnpm add -D msw，并配置 handlers 与 server，在 beforeAll 中 server.listen({ onUnhandledRequest: 'error' })，afterEach 中 server.resetHandlers()，afterAll 中 server.close()。 无障碍测试需安装 pnpm add -D @axe-core/react，并使用 jest-axe 的 axe 与 toHaveNoViolations。
四、适用场景 适用于 React 组件的单元与集成测试，尤其是需要模拟用户输入、点击、键盘操作，处理异步加载与 API 请求，以及关注无障碍性的测试场景。
五、限制与常见错误 资料列出常见错误：对异步元素使用 getBy（应使用 await findBy）；未 await 用户事件导致竞态；使用 container.querySelector（应改用无障碍查询）。资料未提供其他平台支持、收费或价格信息。
官方文档：https://testing-library.com/docs/react-testing-library/intro