前端单元测试常被后端同事轻视，但现代前端工程的复杂度早已不亚于服务端。本文聚焦前端单元测试：用 Jest 搭配 React Testing Library（RTL）把组件行为稳定地锁进测试用例，覆盖从环境搭建、交互断言到异步 Mock 的完整链路，并与 e2e 测试形成互补。它的投入产出比极高——一次编写，千次回归，是团队规模扩大后性价比最高的质量投资之一。
为什么前端也要写单元测试
一个按钮组件可能在十几个页面被复用，一次 props 改动就可能引发连锁回归。端到端测试虽然贴近真实，但执行慢、定位难。单元测试的价值在于：改完一行代码，几秒内就知道有没有打破现有行为。它不追求覆盖全部路径，而是用最低成本守住“已有功能不退化”这条底线。
测试金字塔：单元测试该测什么
单元测试只关心“组件在给定输入下渲染出什么、对用户交互如何响应”，不关心路由、网络、后端。把数据请求、定时器、第三方 SDK 全部 Mock 掉，才是干净的单元。否则一个用例挂了，你分不清是组件坏了还是接口挂了。
别用单元测试替代 e2e
单元测试快但“近视”，它看不见页面级流程。下面这张表帮你区分三类测试的边界：
| 维度 | 单元测试 | 集成测试 | e2e 测试 |
| 范围 | 单个组件/函数 | 多个组件协作 | 整条用户路径 |
| 速度 | 毫秒级 | 秒级 | 分钟级 |
| 稳定性 | 高（全 Mock） | 中 | 低（依赖环境） |
| 定位成本 | 低 | 中 | 高 |
如果你已经用 Vitest + Playwright 搭起了端到端体系（见本站《前端自动化测试：Vitest 与 Playwright 实战》），本文的 Jest + RTL 正好补上金字塔底层的单元这一环。
环境搭建：Jest + Testing Library 快速起步
React 项目推荐 Jest + @testing-library/react。先用 npm 装好依赖，再写一份最小配置：
# 安装核心依赖
npm install -D jest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom
# jest.config.js
module.exports = {
testEnvironment: 'jsdom',
setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
moduleNameMapper: {
'\\.(css|less)$': 'identity-obj-proxy',
},
};
jest.setup.js 里引入 jest-dom 的匹配器，之后就能直接用 toBeInTheDocument() 这类语义化断言：
// jest.setup.js
import '@testing-library/jest-dom';
第一个组件测试：渲染与断言
写一个最朴素的用例：渲染一个按钮，断言文案存在。RTL 的理念是“从用户视角查询 DOM”，所以优先用 getByRole 而非取 class。
// SubmitButton.jsx
export function SubmitButton({ label, onClick }) {
return <button onClick={onClick}>{label}</button>;
}
// SubmitButton.test.jsx
import { render, screen } from '@testing-library/react';
import { SubmitButton } from './SubmitButton';
test('渲染按钮文案', () => {
render(<SubmitButton label="提交" onClick={() => {}} />);
expect(screen.getByRole('button', { name: '提交' })).toBeInTheDocument();
});
交互测试：用户行为而非实现细节
好的组件测试不关心内部 state 怎么变，只关心“点了之后页面发生了什么”。用 userEvent 模拟真实点击，配合断言回调被调用：
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
test('点击触发 onClick', async () => {
const handle = jest.fn();
render(<SubmitButton label="提交" onClick={handle} />);
await userEvent.click(screen.getByRole('button', { name: '提交' }));
expect(handle).toHaveBeenCalledTimes(1);
});
Mock 异步与依赖：前端测试的关键
组件常需请求接口。单元测试里要把 fetch 替成假数据，再用 waitFor 等异步结果落地。这样既快又稳定：接口挂了测试照样绿，本地断网也能跑。注意别让异步用例“偶发红”——很多 flaky 测试源于忘了 await，或 setTimeout 没被 jest.useFakeTimers 接管，写异步用例时这两点要养成肌肉记忆。
// 用 jest.mock 替换请求模块
jest.mock('../api', () => ({
fetchUser: jest.fn(() => Promise.resolve({ name: 'Agnes' })),
}));
test('加载后展示用户名', async () => {
render(<UserProfile />);
expect(await screen.findByText('Agnes')).toBeInTheDocument();
});
测试状态管理组件
当组件依赖 Pinia、Vuex 或 Redux 这类全局 store 时，测试要先把 store 准备好再挂载。以 Pinia 为例（状态管理实践见《前端状态管理实战：Pinia 进阶与最佳实践》），可以用 setActivePinia 注入一个干净实例：
import { setActivePinia, createPinia } from 'pinia';
beforeEach(() => {
setActivePinia(createPinia());
});
test('计数器加一', () => {
const store = useCounterStore();
store.increment();
expect(store.count).toBe(1);
});
快照测试：双刃剑
toMatchSnapshot 能一键记录组件输出，结构变化时告警。但它容易“假绿”——随便改点东西就更新快照，等于没测。建议只给纯展示组件用，且每次更新快照都要人工 review diff：
test('卡片结构快照稳定', () => {
const { container } = render(<Card title="标题" />);
expect(container.firstChild).toMatchSnapshot();
});
在 CI 中跑测试：守住质量闸门
本地过了不算数，必须进流水线。把测试挂到每次 PR 的 GitHub Actions 上，配合 --ci 关闭 watch 模式，失败就阻断合并（CI 配置详见《GitHub Actions 实战：从自动化构建到部署》）：
# .github/workflows/test.yml
name: test
on: [pull_request]
jobs:
unit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 20 }
- run: npm ci
- run: npx jest --ci --coverage
常见坑与覆盖率误区
新手最容易踩的五个坑，以及对应处置：
| 现象 | 根因 | 处置 |
| 报错 “document is not defined” | 没配 jsdom | testEnvironment 设为 jsdom |
| findBy 超时 | 异步未 await | 用 await findBy* 或 waitFor |
| 点击无效 | 用了 fireEvent 但事件被拦 | 改用 userEvent 模拟真实行为 |
| 覆盖率虚高 | 只测了渲染没测交互 | 补交互与边界用例 |
| 快照永不失败 | 无脑 -u 更新 | review diff 再更新 |
测试文件怎么组织：命名与目录约定
测试文件放哪、叫什么，直接决定团队能否长期维护。社区主流约定是把用例和被测文件就近同目录，用 .test.jsx 或 .spec.tsx 后缀，这样改组件时能一眼看到对应测试，不易遗忘。另一种是把所有测试收进 __tests__/ 目录，适合需要统一 mock setup 的中大型项目。
src/
components/
SubmitButton.jsx
SubmitButton.test.jsx # 就近同目录
__tests__/
utils.test.ts # 或集中放置
无论选哪种，核心目标是“改源码就顺手改测试”的低摩擦体验。配合编辑器的 Jest 插件，保存即跑当前文件，反馈快到可以边写边验证。把公共 mock（如接口、定时器、localStorage）抽进 jest.setup.js 全局注入，既能避免每个用例重复造轮子，也能减少因 mock 写法不一导致的偶发失败。当测试数量过了百，再引入 --testPathPattern 只跑改动相关文件，CI 分钟数才能真正可控。
什么时候不该写单元测试
单元测试不是银弹。纯展示、几乎无逻辑的静态组件，写测试收益很低；频繁变动的 UI 原型阶段，过早加测试反而拖慢迭代；依赖大量浏览器私有 API 的逻辑，Mock 成本可能高于收益。更聪明的做法是：把核心业务规则抽成纯函数单独测，UI 层只测关键交互与边界，其余交给 e2e 兜底。测试要服务交付节奏，而不是反过来被覆盖率指标绑架。
小结
前端单元测试的核心不是“覆盖率数字”，而是用最低成本锁定“行为不退化”。Jest 负责运行与断言，Testing Library 负责以用户视角查询 DOM，两者配合能把组件测试写得既稳定又易读。把它接进 CI，再与端到端测试分层协作，前端质量才有真正的底盘。跨域与接口联调相关问题可参考《前端跨域 CORS 完整指南》，Vue 技术栈实践见《Vue3 + TypeScript 项目实战》。
