用途：在 template-ts 项目中实现或审查测试工作流时使用，目标是选择最轻量且有效的测试类型，并保持 Vitest 单元测试、TRPC 集成测试（PGlite）与 Playwright E2E 测试的项目一致性。
测试层级（优先简单）：单元测试（首选）覆盖纯函数、解析器和 Effect 服务；TRPC 集成测试覆盖完整 TRPC 与数据库行为；E2E 测试覆盖浏览器与完整用户流程。适用判断：纯函数、解析器、工具直接写单元测试；带依赖的 Effect 服务用 mock 层写单元测试；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。
决策流程：先问能否单元测试，能则立即写；若涉及数据库行为（连接、约束、TRPC 与持久化），用户明确要求集成测试则直接实现，否则询问是否需要集成测试；若涉及浏览器或 UI 流程，用户明确要求 E2E 则直接实现，否则询问是否需要 E2E，并说明它维护成本最高。用户已明确要求的测试类型不要重复询问。
集成测试使用 @project/db/testing 的 seed 辅助函数按用例建立最小状态。示例见 references/examples.md。
命令：bun run test（单元加 TRPC 集成）；bun run test:watch；bun run test:coverage；bun run test:e2e；bun run test:e2e:ui。运行单个文件需在项目根目录使用完整路径，如 bun run vitest run packages/common/src/tests/pagination.test.ts。注意 bun run test 后接路径无效，且不要切换到子目录再执行。