Testing Library

用户行为导向的轻量级测试工具集

测试工具组件测试用户行为测试可访问性

Testing Library 引导开发者像用户一样查询和交互 DOM，核心理念是测行为不测实现，已成为 React、Vue、Angular、Svelte 组件测试的事实标准实践之一。

Testing Library 用户行为导向测试库技术调研

Testing Library 是一族轻量级测试工具，通过 @testing-library/react、@testing-library/vue 等包，引导开发者像用户一样查询和交互 DOM，而非测试组件内部实现。其核心理念是「测行为不测实现」，已成为 React、Vue、Angular、Svelte 组件测试的事实标准实践之一。

一、基本信息

维度	关键指标 / 描述
技术标签	组件测试 / 用户行为 / 可访问性 / RTL
开发商	Testing Library 开源社区
官方网站	https://testing-library.com/
GitHub	testing-library/react-testing-library 等
许可协议	MIT License
首次发布	2018 年（React Testing Library）
生态成熟度	极高（现代组件测试首选实践）

二、技术定位与简介

Testing Library 不是测试运行器，而是与 Vitest/Jest 配合的 DOM 查询与交互库：

查询优先级：getByRole > getByLabelText > getByText > getByTestId。
用户事件：@testing-library/user-event 模拟真实键盘鼠标。
异步工具：waitFor、findBy* 处理异步 UI。
框架绑定：React、Vue、Angular、Svelte、Preact、Marko。

配合项目 AGENTS 规则：UI 结构、样式、普通点击等展示细节默认不堆单测；Testing Library 应用于有稳定业务规则的交互逻辑测试。

三、快速上手安装说明

1. React + Vitest

pnpm add -D @testing-library/react @testing-library/jest-dom @testing-library/user-event

2. Vue + Vitest

pnpm add -D @testing-library/vue @testing-library/jest-dom @testing-library/user-event

3. React 示例

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { describe, it, expect } from 'vitest'
import LoginForm from './LoginForm'
 
describe('LoginForm', () => {
  it('submits credentials', async () => {
    const user = userEvent.setup()
    const onSubmit = vi.fn()
 
    render(<LoginForm onSubmit={onSubmit} />)
 
    await user.type(screen.getByLabelText(/email/i), '[email protected]')
    await user.type(screen.getByLabelText(/password/i), 'secret')
    await user.click(screen.getByRole('button', { name: /sign in/i }))
 
    expect(onSubmit).toHaveBeenCalledWith({
      email: '[email protected]',
      password: 'secret',
    })
  })
})

4. Vue 示例

import { render, screen } from '@testing-library/vue'
import userEvent from '@testing-library/user-event'
import Counter from './Counter.vue'
 
it('increments count', async () => {
  const user = userEvent.setup()
  render(Counter)
  await user.click(screen.getByRole('button', { name: /increment/i }))
  expect(screen.getByText('Count: 1')).toBeInTheDocument()
})

5. jest-dom 匹配器

// vitest.setup.ts
import '@testing-library/jest-dom/vitest'

四、核心特性

1. 语义化查询

getByRole('button', { name: 'Submit' }) 鼓励可访问性。

2. 查询变体

getBy*：立即，找不到抛错。
queryBy*：找不到返回 null。
findBy*：异步等待出现。

3. user-event

比 fireEvent 更接近真实用户输入序列。

4. within 作用域

在组件子树内查询。

5. waitFor 与 waitForElementToBeRemoved

异步状态与加载态测试。

6. 框架无关核心

@testing-library/dom 共享查询逻辑。

7. eslint-plugin-testing-library

防止错误查询模式。

五、适用场景

1. 黄金适用场景

表单提交、校验、错误提示。
权限可见性、条件渲染（业务规则）。
可访问性角色与标签正确性。
搜索、筛选、分页交互逻辑。
与 MSW 结合的列表加载状态。

2. 局限适用场景（本项目规范）

纯展示组件、营销页、样式细节。
Toast、弹窗纯 UI（除非含业务规则）。
快照大面积 UI 结构。
E2E 全流程（用 Playwright）。

六、技术亮点

1. 引导可访问性

强制使用 role/label，改善产品质量。

2. 抗重构

不依赖 className、内部 state，重构友好。

3. 官方文档优秀

查询优先级指南是行业经典。

4. 全框架覆盖

一套理念跨 React/Vue/Angular。

5. 与 Vitest/Jest 无缝配合

七、核心概念与架构

digraph TL_Architecture {
  rankdir=LR
  node [shape=box, style="rounded,filled", fillcolor="#f0f9ff"]
  Runner [label="Vitest / Jest", fillcolor="#bae6fd"]
  TL [label="Testing Library\n(render/screen)"]
  DOM [label="jsdom / Browser"]
  UserEvent [label="user-event"]
  Component [label="Component Under Test"]
 
  Runner -> TL
  TL -> DOM
  UserEvent -> DOM
  TL -> Component
  Component -> DOM
}

八、技术局限与边界

非 E2E：不覆盖跨页面、真实浏览器差异。
jsdom 局限：布局、CSS 部分行为不准确。
复杂画布/SVG：查询困难，需专项策略。
过度测试 UI：违背库哲学和项目规范。
异步竞态：waitFor 使用不当导致 flaky。
Portal 组件：需 baseElement 或适当容器。

九、生态地图

包	框架
`@testing-library/react`	React
`@testing-library/vue`	Vue
`@testing-library/angular`	Angular
`@testing-library/svelte`	Svelte
`@testing-library/user-event`	交互
`@testing-library/jest-dom`	匹配器

十、生态集成

方向	说明
Vitest	推荐测试运行器（本项目）。
MSW	Mock API 后测加载/错误态。
Playwright	E2E 层复用相似查询理念。
eslint-plugin-testing-library	静态检查查询方式。
Storybook	storybook-addon-interactions 类似交互测试。

十一、开发与工程化

1. 本项目测试位置

apps/tests/ 镜像源码，导入 @/。

2. 查询优先级实践

// 优先
screen.getByRole('button', { name: /submit/i })
// 避免
screen.getByTestId('submit-btn') // 仅最后手段

3. 自定义 Role 组件

确保按钮、链接使用正确语义标签或 role。

十二、性能与安全

避免在单个测试中渲染过大树。
cleanup 通常自动，Vitest 环境默认启用。
测试数据使用 faker，勿用真实 PII。

十三、技术对比

方案	优势	局限	适合
Testing Library	用户行为、抗重构	非 E2E	组件交互逻辑
Enzyme	测实现细节	已停止维护	遗留 React
Vue Test Utils	Vue 专用 API	易测实现	可配合 TL Vue
Playwright	真实浏览器 E2E	较慢	关键路径

十四、最佳实践

遵循查询优先级：role > label > text > testid。
使用 user-event 而非 fireEvent。
异步用 findBy 或 waitFor，避免裸 setTimeout。
不测试内部 state、私有方法、class 名。
按项目规范：仅为稳定业务规则写测试。
与 MSW 组合测 API 驱动 UI 状态机。
启用 eslint-plugin-testing-library。
jest-dom 匹配器提升断言可读性。
避免多个大断言塞入单个 it，拆分场景。
营销页、纯展示组件跳过单测，用 typecheck/build/E2E。

十五、学习与社区资源

官方文档：https://testing-library.com/docs/
查询优先级：https://testing-library.com/docs/queries/about#priority
Common mistakes：https://kentcdodds.com/blog/common-mistakes-with-react-testing-library
user-event：https://testing-library.com/docs/user-event/intro