testing-patterns

测试模式

使用此技能选择最轻量且有效的测试类型，并采用项目一致的模式编写 Vitest 单元测试、使用 PGlite 的 TRPC 集成测试和 Playwright E2E 测试。

测试层级（优先选择更简单的方式）

1. 单元测试（首选）——覆盖纯函数、解析器和 Effect 服务。
2. TRPC 集成测试——覆盖完整的 TRPC + 数据库行为。
3. E2E 测试——覆盖浏览器和完整用户流程。

何时使用哪种测试

情况	测试类型	操作
纯函数、解析器、工具函数	单元测试	立即编写
带依赖项的 Effect 服务	使用模拟层的单元测试	立即编写
TRPC 过程（数据库逻辑）	TRPC 集成测试	遵循决策流程
面向用户的流程、UI 行为	E2E 测试	遵循决策流程

测试文件位置

代码位置	测试位置
packages/X/src/file.ts	packages/X/src/__tests__/file.test.ts
apps/web-app/src/infrastructure/trpc/routers/X.ts	apps/web-app/src/__tests__/X.test.ts
apps/web-app/src/routes/**	apps/web-app/e2e/feature.e2e.ts

---

决策流程（规范流程）

编写任何测试之前，请按以下顺序执行：

1. 能否进行单元测试？ 立即编写单元测试。
2. 是否需要数据库行为（联接、约束、TRPC + 持久化）？
   • 如果用户明确要求集成测试，直接实现。
   • 否则，询问类似这样的问题：“你希望为此 TRPC/数据库行为编写集成测试吗？”
3. 是否需要验证浏览器/UI 流程？
   • 如果用户明确要求 E2E 覆盖，直接实现。
   • 否则，询问类似这样的问题：“你希望在这里编写 E2E 测试吗？这是维护成本最高的测试类型。”

如果用户已经明确指定测试类型，绝不要再次询问。

单元测试模式

默认使用单元测试。

具体示例请参阅 references/examples.md：

• 基础 Vitest
• 使用 @effect/vitest 和模拟层进行 Effect 测试
• 使用真实服务逻辑并模拟边界的服务层测试

术语说明：“使用真实服务逻辑并模拟边界的服务层测试”是指测试真实的服务实现，同时将外部边界（例如 HTTP、数据库或文件系统客户端）替换为模拟对象。

---

TRPC 集成测试模式

有关是否征求同意并升级测试类型，请遵循上述规范决策流程。

具体的设置和种子数据辅助函数示例，请参阅 references/examples.md。

使用 @project/db/testing 中的种子数据辅助函数，为每种情况准备最低限度的必需状态。

---

E2E 测试模式

有关是否征求同意并升级测试类型，请遵循上述规范决策流程。

具体的 E2E 和身份验证辅助函数示例，请参阅 references/examples.md。

只有在用户未明确要求 E2E 测试时，才提醒其维护成本。

---

命令

bun run test              # Run all unit + TRPC integration tests
bun run test:watch        # Watch mode
bun run test:coverage     # With coverage
bun run test:e2e          # Run E2E tests
bun run test:e2e:ui       # E2E with UI

# Run specific test file (FROM PROJECT ROOT, full path required)
bun run vitest run packages/common/src/__tests__/pagination.test.ts
bun run vitest run apps/web-app/src/__tests__/formatters.test.ts

避免使用以下命令模式：

# These DO NOT work:
bun run test packages/common/src/__tests__/file.test.ts  # script doesn't accept path
cd packages/common && bun run vitest run src/__tests__/file.test.ts  # wrong cwd