Vitest 单元测试搭建

解决什么问题

多数团队在引入单元测试时卡在第一步:不是不想写测试,而是测试环境本身搭不起来。不同项目的技术栈差异很大——Cloudflare Workers 需要专用的 pool 来跑绑定变量,React 组件测试依赖 jsdom 与 Testing Library,Node/Hono API 又是另一套环境。手动拼配置往往要花半天时间,还要处理 describe is not defined、document is not defined 这类环境报错,最后还可能在 CI 和本地跑出不同结果。

核心能力

这个技能扮演测试基础设施工程师的角色,按检测到的项目类型产出可运行的测试设施:

• 类型检测:读取 package.json、tsconfig.json、wrangler.toml 等文件,将项目归类为 Cloudflare Workers、React(Vite)、React(SSR/TanStack Start)、Node/Hono API 或库
• 配置生成:生成匹配的 vitest.config.ts;若项目已有 Vite 配置则直接扩展,不重复建文件
• 示例测试:针对项目中真实存在的源码写一份测试,放到源码旁边而非独立的 __tests__ 目录,装完即可运行
• 脚本接入:合并(而非覆盖)test、test:run、test:coverage、test:ui 脚本
• 首次验证:运行测试确认通过,失败时自动诊断修复,确保设置完成时测试就能绿

关键步骤

1. 检测项目类型与包管理器,生成对应的依赖清单
2. 按类型生成配置:Workers 用 defineWorkersConfig 指向 wrangler.toml,React 用 jsdom 加 setup 文件,API 与库用 node 环境
3. 生成 src/test/setup.ts,React 项目导入 @testing-library/jest-dom/vitest 注册匹配器
4. 在覆盖测试文件的 tsconfig.json 中添加 "types": ["vitest/globals"]
5. 基于真实源码生成示例测试:Hono 路由用 app.request() 断言,React 组件用 render + userEvent,工具函数直接断言返回值

适用边界

它解决的是"怎么把测试跑起来",而不是"该测什么"。测试策略仍需人工判断,示例测试针对具体项目源码生成,不提供通用的假模块。多 tsconfig 项目要注意把配置加到正确那份。