测试指南

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

测试架构概览

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

层级	工具选型	目标	路径
后端单元/集成测试	Vitest	测试 Hono API 路由、tRPC Logic、Utils	`apps/server/src/*.test.ts`
前端组件测试	Vitest + RTL	测试 UI 组件渲染与交互逻辑	`apps/web/src/*/.test.tsx`
认证包测试	Vitest	企微身份、管理员引导、OAuth 默认配置	`packages/auth/src/*.test.ts`
端到端测试 (E2E)	Playwright	模拟真实用户在浏览器中的核心业务链路	`apps/web/e2e/*.spec.ts`

pnpm env:check

该命令检查本地 .dev.vars 是否存在、必填项格式和企业微信配置组是否完整，但不会输出任何密钥值。

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

pnpm test

[!NOTE] 该命令通过 Turborepo 运行已配置 test 脚本的 workspace。@IAM/api 当前没有独立测试脚本，相关集成行为主要由 apps/server 测试覆盖。

pnpm test:e2e

[!TIP] Playwright 会自动启动 apps/web 的 Next.js 服务。需要真实认证后端的用例仍需确保 8787 API 可用，并正确配置 AUTH_UPSTREAM_URL。

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

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

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

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

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

项目接入了 v8 覆盖率引擎。分别执行：

pnpm --filter server test:coverage
pnpm --filter web test:coverage

运行结束后，可分别在 apps/server/coverage 和 apps/web/coverage 查看报告。认证包目前运行 pnpm --filter @IAM/auth test，尚未配置独立 coverage 脚本。

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

已有测试覆盖 Hono 路由、OIDC 负例、数据库 batch、R2 上传、企微登录、认证默认配置、前端登录与 OAuth 客户端表单。上线前仍需优先补：