测试指南

本文档介绍了 IAM 项目中引入的自动化测试体系。我们采用了 Vitest 进行单元和组件测试，以及 Playwright 进行端到端（E2E）测试，并通过 Turborepo 实现了全栈测试的统一编排。

测试架构概览

项目采用分布式测试策略，针对不同层级的代码选用最合适的工具：

层级	工具选型	目标	路径
后端单元/集成测试	Vitest	测试 Hono API 路由、tRPC Logic、Utils	apps/server/src/*.test.ts
前端组件测试	Vitest + RTL	测试 UI 组件渲染与交互逻辑	apps/web/src/**/*.test.tsx
端到端测试 (E2E)	Playwright	模拟真实用户在浏览器中的核心业务链路	apps/web/e2e/*.spec.ts

---

快速开始

运行全路径测试

在项目根目录下，可以通过一个命令运行所有子项目的单元与组件测试：

pnpm test

[!NOTE] 该命令利用 Turborepo 并发执行，且会自动利用缓存。如果代码未变动，测试结果将秒级返回。

运行端到端测试

pnpm test:e2e

[!TIP] Playwright 配置了 webServer 自动启动机制。在运行测试前，它会自动检查并启动本地开发服务器（3000 端口），测试完成后自动关闭，无需手动干扰。

---

详细配置说明

1. 后端测试 (apps/server)

后端使用 Vitest 的 node 环境执行。

• tRPC 集成测试：我们推荐使用 tRPC 的 createCaller 模式。这种模式不需要启动真实的 HTTP 服务，而是直接在进程内调用路由逻辑，执行速度极快且能够深度覆盖权限检查、数据库交互等业务。
• Hono 请求测试：利用 Hono 实例自带的 .request() 方法，可以直接模拟 Fetch API 风格的请求来验证 REST 路由。

2. 前端测试 (apps/web)

前端使用 Vitest 的 jsdom 环境，结合 React Testing Library (RTL)。

• 环境 Mock：我们在 vitest.setup.ts 中配置了常用的浏览器 API Mock（如 matchMedia, ResizeObserver），并集成了 jest-dom 断言库。
• TypeScript 支持：项目已配置项目级类型定义，在 .test.tsx 文件中可直接获得 describe, it, expect 的智能补全。

3. E2E 测试 (Playwright)

• 配置文件：apps/web/playwright.config.ts
• 可视化调试：执行 pnpm test:e2e:ui 可打开 Playwright 的交互式界面，支持断点调试、时光倒流追踪（Trace Viewer）等功能，极大提升 E2E 编写效率。

---

覆盖率统计 (Coverage)

项目接入了 v8 覆盖率引擎。执行以下命令可以查看全栈代码覆盖情况：

pnpm test -- --coverage

运行结束后，您可以分别在 apps/server/coverage 和 apps/web/coverage 目录下找到生成的 HTML 可视化报告。

---

最佳实践与建议

1. 测试文件命名：
   • 单元测试请以 .test.ts 或 .test.tsx 结尾，并与源代码放在同级目录。
   • E2E 测试请统一存放在 apps/web/e2e/ 目录下。
2. 避免过度 Mock：在 tRPC 测试中，建议尽量真实调用底层 Service，仅对外部网络请求或极其复杂的模块进行 Mock。
3. CI 集成：本套指令已适配标准 CI 环境，建议在 GitHub Actions 触发时运行 pnpm test 以保证代码质量。