1. 为什么React测试的选型会决定项目体验先说个我自己的经历。去年在某团队接手一个中后台项目测试代码有三千多个用例看上去覆盖率挺漂亮但每次跑全量测试要十五分钟以上而且随便改动一个公共组件就会连带挂掉百来个无关用例。整个团队后来对测试的态度从必须写变成了能躲就躲新来的同学写用例完全靠复制粘贴断言逻辑都看不懂。后来我们花了两周时间把测试框架整体换了一遍跑全量测试的时间从十五分钟降到了两分多钟用例数量少了三分之一但有效覆盖反而更高了。这两周的差别核心根本不是某个框架好不好用而是选型这件事从一开始就决定了后面所有测试代码的形态。在React生态里大家说的单元测试框架通常指的是四样东西的组合测试运行器Test Runner负责发现用例、执行用例、输出报告代表是Jest和Vitest断言库Assertion Library负责判断实际结果是否符合预期Jest自带Vitest也自带组件挂载与查询工具Renderer Query API负责把React组件渲染到DOM上并查找元素做交互代表是React Testing LibraryRTL和Enzymemock工具负责替换掉网络请求、子组件、时间函数等外部依赖这四个层面各自选型组合起来才叫框架选型。很多人张口就说我们用Jest做单测其实他只用到了运行器和断言库组件渲染用的还是RTL这是三套东西不是一套。这篇内容就是围绕这四个层面的选型和落地展开的适合刚接手React项目测试体系、想把现有测试从能跑提升到好用的开发者参考。2. 四个主流框架的横向对比别被维护者弃坑吓住2.1 Jest和Vitest运行器层面的核心差异Jest是React测试事实上的标准facebook内部维护文档完善生态成熟遇到问题搜索引擎基本都能找到答案。但Jest有几个历史包袱默认跑在Node环境里对ESM的支持一直不彻底使用了它自己那套模块解析和沙箱机制所以配置起来会有一堆transform相关的规则。Vitest是Vite生态下的测试框架底层利用Vite的transform能力不需要单独配置Babel就能直接处理TSX、ES Modules启动速度和热更新比Jest快一个量级。更重要的是Vitest对ESM的处理是原生支持不会再遇到Jest那套module.ts转CommonJS再转回来的绕路问题。用一个直观的例子说明差异。Jest里你写了一个ESM包直接import会被报错得靠transformIgnorePatterns反复调试Vitest直接把esbuild接进来jsx、ts、tsx全部开箱即用。如果你本身是Vite驱动的项目尤其是Vite 5以上版本Vitest是更省心的选择。但如果项目是CRACreate React App生成的还停在webpack构建体系里硬上Vitest反而不划算因为它基于Vite和webpack的项目会存在重复构建的体系冲突这种情况下老老实实用Jest更稳。2.2 React Testing Library和Enzyme组件测试的两种理念Enzyme当年是Airbnb主导的React组件测试工具它允许你访问组件实例的内部状态、手动调用生命周期方法、通过find查DOM节点。听起来能力很强但它测试的是组件怎么实现而不是组件做了什么。比如一个按钮点击后弹出弹窗Enzyme的写法经常是检查handleClick是否被调用、state是否改变而不是检查弹窗是否真的出现在屏幕里。React Testing Library遵循的哲学正好相反测试用户能看到和交互的东西而不是测试组件的内部实现。它不提供组件实例层面的查询只让你通过角色、文本、标签等面向用户的方式去查DOM。一个RTL测试不会因为你在重构时把state改成useReducer而失败只要页面行为对用户来说没变测试就是绿的。我个人的建议非常直接新项目一律用RTL老的Enzyme测试也不要大规模迁移新增用例全部用RTL写慢慢替换。理由后面第三部分会详细展开。2.3 实测对比表下面这张表是我基于同一个组件Demo在三个框架组合下跑出的实测数据组件是一个带异步加载的表单页面包含45个用例对比项Jest RTLVitest RTLJest Enzyme首次安装配置耗时20分钟8分钟25分钟45个用例执行耗时12.6秒3.1秒18.9秒TS类型推断准确度中需额外配置高原生支持低需大量anyDebug定位难度中报错栈清晰低报错直接指向源码高内部封装多维护方状态维护稳定active社区活跃已停止维护or仅维护模式Enzyme现在基本已经处于冻结状态了Airbnb也放弃维护新项目如果选Enzyme是在给自己造技术债。Jest和Vitest的选择取决于构建体系RTL是组件测试层的必选项。3. 落地一套可跑的测试配置把最常见的一组坑提前踩完3.1 以Vitest RTL为例的完整配置流程如果你像我一样在一个中后台项目里从零搭建测试环境推荐一个能跑通的最小配置路线。先装依赖npm i -D vitest testing-library/react testing-library/jest-dom testing-library/user-event jsdom然后需要在vite.config.ts或vitest.config.ts里加一个test字段以下是一份比较完整的配置import { defineConfig } from vitest/config; import react from vitejs/plugin-react; export default defineConfig({ plugins: [react()], test: { environment: jsdom, globals: true, setupFiles: [./src/test/setup.ts], include: [src/**/*.{test,spec}.{ts,tsx}], css: false, coverage: { provider: v8, reporter: [text, json, html], include: [src/**/*.{ts,tsx}], exclude: [src/main.tsx, src/**/*.d.ts, src/test/**] } } });这里的setup.ts文件用来注册jest-dom的匹配器还有一个非常重要的全局清理函数import testing-library/jest-dom/vitest; import { cleanup } from testing-library/react; import { afterEach } from vitest; afterEach(() { cleanup(); });RTL的cleanup会自动卸载渲染出来的组件如果你忘了写这个全局afterEach多个用例之间可能会出现DOM重复、事件监听冲突、甚至找不到元素的假失败。RTL官方文档里写了推荐这么做但很多人照着官方集成文档抄完之后根本不会注意到这个cleanup的全局注册步骤。3.2 三个最容易让你卡住的配置问题第一个是jsdom和Node环境的差异。有些用例跑在Node环境里没问题但一旦涉及DOM操作就会报错因为Node环境没有浏览器那套全局对象。解决办法就是给测试配置environment: jsdom注意Vitest里面还支持per-file覆盖某个特殊用例如果你确定它不需要DOM可以在文件顶部写// vitest-environment node单独指定。第二个是CSS和静态资源的处理。在Jest时代import一个.less文件几乎必然需要moduleNameMapper来mock成空对象否则跑起来就报错。Vitest里有css: false配置项来跳过CSS处理但注意如果你的组件里有import图片、SVG、字体文件的逻辑有可能仍然报错这个时候需要在test里配置alias或手动mock。最简单的方案是建一个mock文件处理静态资源然后在setup.ts里注册进去。第三个是transformIgnorePatterns。这个主要是Jest用户会遇到的Vitest基本没有这个问题。Jest默认把node_modules里的包都忽略掉如果你引用的某个依赖是ESM格式的很多组件库已经切到ESM-only了在Jest的Node环境里面会直接爆SyntaxError。解决办法是在transformIgnorePatterns里把这个包的名字排除掉例如{ transformIgnorePatterns: [node_modules/(?!react-dnd|dnd-kit)/] }注意这个正则是排除node_modules里除了这几个包之外的所有内容的反向匹配写法网上很多文章会把括号里的名单写反。3.3 从CRA/Jest迁移到Vitest的注意点如果已经有一个Jest测试体系我不建议一把梭全量重写。迁移可以采用双轨并行先新建vitest.config.ts确保Vite本身的构建不受影响然后逐个目录迁移用例把Jest里jest.mock的部分逐步替换成vi.mock全局的jest.fn()改成vi.fn()断言库的expect(...).toBe()语法不变Vitest的断言API跟Jest是基本兼容的。不过有一个小坑容易踩Vitest里vi.mock的语法比Jest严格它默认不会提升mock所以在import之前声明mock时有坑。习惯上写在文件顶部的vi.mock(node_modules包名, () ({ ... }))正常工作但如果你在某个describe块内部做条件式mockVitest会直接报错提示你mock只能在顶层使用。Jest反而在这种场景下更宽容所以迁移的时候如果看到vi.mock is not defined或者Cannot use vi.mock outside of a test file要首先检查你是不是把mock写在了describe里。4. 组件测试怎么写才不空转查询、事件与异步的正确姿势4.1 为什么要按用户视角选查询方式RTL的查询API有一大堆getByRole、getByLabelText、getByPlaceholderText、getByText、queryBy、findBy等等。选错了查询方式最直接的后果是测试极其脆弱——你改一行文本或者换一个CSS类名测试就炸了。我推荐一个层级策略优先getByRole它最贴近辅助功能和用户语义而且能顺带校验可访问性。比如按钮就找getByRole(button, { name: 提交 })下拉框就找getByRole(combobox)。其次getByLabelText跟表单控件关联性最强label写对了测试和用户体验双赢。再用getByText和getByPlaceholderText适合非交互性内容的查找比如校验错误提示。注意不到万不得已不要用container.querySelector因为它绕过RTL的查询语义测出来的结果可能和用户感知不符会给重构带来虚假红灯。4.2 事件触发用userEvent不要用fireEventRTL里有两套事件触发方式fireEvent和userEvent。fireEvent是同步的、直接派发事件的userEvent是异步的、模拟真实用户操作的会触发click、dblClick、hover、键盘输入等浏览器合成行为。在绝大部分真实场景里组件对事件的响应不是同步完成的比如点击按钮后有一个setTimeout修改状态、有loading的闪烁、有异步校验。fireEvent直接派发事件会跳过很多浏览器层面的默认行为导致测试里你点了按钮界面状态却迟迟不更新你以为是组件bug其实是触发方式太粗糙。userEvent的调用方式几乎全是异步的import userEvent from testing-library/user-event; import { render, screen, waitFor } from testing-library/react; test(点击提交按钮后显示loading, async () { const user userEvent.setup(); render(SubmitForm /); await user.click(screen.getByRole(button, { name: 提交 })); expect(await screen.findByText(提交中...)).toBeInTheDocument(); });注意userEvent.setup()必须在每个用例里单独调用一次不要抽成公共变量在多个用例之间共享因为它的内部状态可能残留上次操作。我在不少团队代码评审里见过这个反模式用例偶尔挂、但重跑就绿了基本都是这个原因。4.3 异步请求的三种等待姿势写React组件测试最常见的场景就是等待数据加载完成。这有三种写法我按优先级从高到低说明findBy系列查询await screen.findByText(某个异步出现的文案)。最简单直接返回一个Promise轮询直到找到元素或超时。waitFor包裹断言当你要等一个值符合某种条件时比如等待一个按钮变成可点await waitFor(() { expect(screen.getByRole(button, { name: 提交 })).toBeEnabled(); });waitForElementToBeRemoved等一个元素消失时用的。比如等待loading spinner消失表达语义特别优雅await waitForElementToBeRemoved(() screen.queryByTestId(loading-spinner));尽量用findBy因为代码量最少。waitFor适合做多个断言组合。waitForElementToBeRemoved适合处理轮播图loading、全局遮罩消失这类场景不少展示型的组件库比如弹窗、Table骨架屏都需要这种等待。5. Mock、异步与定时器最容易翻车的三个环节5.1 慎用子组件mock默认让它真实渲染很多刚接触RTL的人有一个习惯测试父组件时把子组件mock掉觉得可以隔绝依赖。但RTL的哲学是尽量渲染真实组件树只mock掉跨边界的东西比如请求、路由、状态管理。原因很简单如果你把内部子组件全mock成假节点那测试本质上只覆盖了父组件的拼接逻辑一旦子组件行为变更例如文案变了、交互方式变了父组件测试不会反映出来等于测试处于一种绿但是无效的状态。什么时候才应该mock子组件两个场景某个子组件非常重渲染时依赖浏览器API或第三方SDK不mock掉测试跑不动。子组件渲染会发起真实网络请求图片加载、埋点上报这时候mock掉可以保证测试不发出真实请求。mock子组件的技术很简单vi.mock(./HeavyChart, () ({ default: () divMOCKED_CHART/div }));在测试文件里再断言父组件渲染时包含MOCKED_CHART这个文本以确认父组件正确调用了这个子组件。5.2 fetch请求的四类mock策略React组件内最常见的副作用就是网络请求。mock它有四个层次mock整个fetch函数在测试文件里global.fetch vi.fn()然后针对不同断言场景设定resolve值。这是最底层的mock但容易让代码实现细节比如两段请求之间的顺序暴露在测试里。用MSWMock Service Worker拦截网络MSW在Node和浏览器里都能工作通过Service Worker逻辑拦截真实请求。这种方案最接近真实环境适合集成测试缺点是每个用例都要写对应的handler模板代码比较多。用vitest的vi.mock局部mock某个请求工具模块如果你的项目把请求封装到了utils/request.ts里直接mock这个模块简单直接。依赖注入把请求函数作为prop或context依赖传入组件测试时传mock版本。这个最优雅但改造成本不小。我的建议是中小型组件测试直接用vi.mock模块方案重交互、多接口联动的页面用MSW。不要每一次都mock fetch这样用例和用户感知之间的关联会越来越远。5.3 定时器与动画导致的找不到元素React测试里定时器最大的坑是fake timers和真实异步等待混用。如果你开了fake timers又用了await waitFor(...)你可能会遇到一个死等现象waitFor内部实现也依赖setTimeout来轮询而你把这个setTimeout给fake了轮询永远不执行。Vitest里控制fake timers的API是vi.useFakeTimers(); test(展示倒计时, async () { const user userEvent.setup({ advanceTimers: vi.advanceTimersByTime }); render(Countdown initial{10} /); await user.click(...); vi.advanceTimersByTime(3000); expect(...).toBe(...); });关键一步是advanceTimers: vi.advanceTimersByTime传给userEvent.setup这样userEvent内部触发的行为也能感知fake timers否则事件触发后的任务会一直排队而你手动advance完也看不到变化。另外某些动画库CSS transition、framer-motion动效在jsdom下会真实启动定时器增加测试的不确定性。遇到这类组件建议在测试环境禁掉动画效果比如给Transition组件的duration传0或者提供一个全局的Animation.debug禁用开关。这不是逃避而是测试不必为视觉效果负责只需负责状态变化。6. 覆盖率、执行效率与企业级扩展方向6.1 覆盖率指标该怎么设才有实际约束力覆盖率数字好看不等于测试有效这是很多团队的认知误区。但完全不看覆盖率也不行否则代码review时没人知道哪些代码彻底没跑过。我实践的设置方式分三层指标目标线触发动作statements语句覆盖80%低于则CI失败branches分支覆盖70%新提交需要补充分支用例functions函数覆盖85%新增公共函数必须补充测试lines行覆盖80%与statements近似可合并管理关键是把CI里的覆盖率阈值作为硬性门槛这样才会倒逼开发者写用例。但阈值不能一开始就定到90%否则团队会抓狂然后开始写为了覆盖而覆盖的空转测试甚至把不该测的私有函数也强行导出来测。还有一个高效做法用vitest的coverage.include限定只统计src里的业务代码把测试文件本身、类型声明文件、构建入口全部排除。不然你的覆盖率会被一堆d.ts文件稀释数字很虚。6.2 测试执行效率的实战优化跑单测的速度很大程度上由两个东西决定并发控制和模块加载量。Vitest默认是fork并行执行的每个文件一个进程如果你的测试文件很多但都很小进程启动的开销反而大于测试本身时间这种情况可以通过fileParallelism: true和合理配置maxWorkers来调整并行度。我更推荐的做法是把纯逻辑工具的测试和组件测试分目录放因为纯逻辑测试不需要jsdom环境它们应该跑在node环境里启动开销小一大截。组件测试里最常见的时间杀手其实是CSS和静态资源的处理。如果组件import了三张png图片和两个less文件每次跑测试就多出几百毫秒的解析时间全项目几百个文件累积起来就很客观了。对这类场景css: false只能跳过CSS输出对于图片文件建议配合vite-plugin-ignore-static-import或者直接通过resolve.alias指向一个空文件来加速。还有一招非常实用把setupFiles里的全局操作做得足够轻。有人会在setup.ts里引入配套的UI库的完整样式、setup全局store、初始化多语言资源这些都会拖慢每个测试文件的启动时间。setup里只放必须的东西其他能在用例内按需import的就不要全局引。6.3 单测之外的边界什么时候该上集成测试单元测试负责验证组件自身行为但项目里总有一些跨模块的逻辑链一个流程要经过首页、表单页、结果页三个页面涉及路由传参、store状态更新、接口返回。这些东西靠单测来覆盖成本极高而且每个步骤都要mock测试意义会逐渐变弱。在这种情况下正确的做法不是把单测写成假装是集成测试而是把真正的集成测试放到另一层去比如用Playwright做E2E用MSW Vitest组件业务流做轻量集成测试。很多团队最后的测试分层是这样的单元测试Vitest RTL覆盖每一个独立的组件和工具函数组件交互测试Vitest RTL MSW覆盖组件之间通过store/context协作的场景E2E测试Playwright覆盖核心业务链路数量不求多每个链路一条就够这个分层的关键是不要试图让一层测试覆盖所有风险。单元测试拼命mock换来的是速度快但覆盖不了多个组件真实协作的场景E2E测试真实感最强但跑得慢、维护成本高。两个都做各司其职测试体系才算健康。7. 从这套选型里得到的几点实战体会最后分享几个我自己用了很久的工作习惯不算什么高深技巧但确实能减少踩坑次数。第一写测试的优先级永远先于补测试。开发一个新组件的时候先把能描述用户行为的测试骨架搭出来比如渲染后能看到XXX点击后XXX消失异步加载后XXX出现然后再去实现组件逻辑。这个顺序的好处是你会很自然地想到边界场景而不是等代码写完了再回来凑用例。第二用describe嵌套来组织行为场景而不是按组件方法组织。很多老测试代码是测试某某方法A测试某某方法B看起来清晰但实际上把组件内部实现暴露给了测试用例本身。我更习惯把describe按行为分describe(当用户未登录时)、describe(当用户点击删除按钮)这样阅读测试代码就像在读一份需求文档。第三遇到偶发失败先别急着改代码先怀疑测试环境问题。jsdom下的下拉框事件、动画定时器、事件监听的竞争条件都可能导致偶发失败。我通常会用--sequence.shuffle false跑一遍确认是不是随机顺序导致的然后检查是否有共享变量跨用例泄漏。第四测试代码也是需要code review的。很多团队只review业务代码测试代码全是自己写了直接合。但恰恰测试代码容易藏污纳垢不查结果、catch住异常假装成功、mock过多导致无意义断言。每周花一点时间review测试代码收益率比review业务代码高得多。如果你也在为React项目的测试体系纠结我的建议是别迷信某一个框架、某一个工具先从用户行为可验证这个角度去梳理你手头组件再决定选什么运行器和渲染工具。选型选对了后面每一行测试代码都会写得舒坦很多。