vitest-architecture

Vitest 架构

适用于 Vitest 5 单体仓库（以及单个软件包）的可移植测试规范。 单独使用此技能即可，不依赖其他技能。

**任务：**确定测试存放位置、项目／脚本如何划分、单元测试与集成测试的区别，以及哪些测试值得编写（test-signal.md）。

**不属于此技能的内容：**Vitest API 详情、模拟、快照或最新文档。对于这些内容，优先查阅当前的 Vitest 文档。

如果目标仓库已有测试文档（例如 AGENTS.md），且内容与此处冲突，以仓库为准，除非用户要求迁移以遵循此技能。

技术栈默认设置（核心）

部分	默认设置
运行器	Vitest 5 — 绝不使用 Bun 的 bun test / bun:test
配置	每个工作区使用 vitest.config.ts + 单元／集成项目（而非单体仓库根目录的 Vitest 工作区）
布局	tests/unit/**、tests/integration/**（仅在已有集成测试设置时使用）
默认门禁	本地仅运行单元测试（test / test:watch）；CI 也会在存在 test:integration 时运行
空软件包	使用 passWithNoTests，确保 Turbo／CI 顺利通过

模式

1. 搭建 — 根据 checklist.md + tree.md 为软件包添加 Vitest。仅当软件包已有真实依赖测试，或用户要求时，才添加 integration 项目。
2. 应用 — 将新测试放到合适的项目和文件夹中。优先采用已有的最高层级设置；参见 test-signal.md。
3. 审查 — 对照 rules.md 和 test-signal.md；建议调整测试位置，并标记信号较弱的单元测试。

硬性规则（核心）

1. import { … } from "vitest"（或在适用的覆盖层中使用 @effect/vitest）。绝不使用 bun:test。
2. 每个软件包／应用拥有自己的 Vitest 配置 — vitest.config.ts 列出各项目；不要假设存在根目录聚合配置。
3. 两种设置都存在时使用两个项目：unit 和 integration，通过 --project 选择。绝不擅自添加集成测试设置（Testcontainers、测试数据库、compose 栈）或浏览器设置 — 应先提出建议并等待批准。
4. 默认本地门禁 = 单元测试。 集成测试使用独立脚本（test:integration）。存在该脚本时，CI 必须运行它，因为它承载主要测试信号。
5. 测试放在 tests/ 下（不要散布在每个 src/ 文件旁）。按测试方面命名（status.test.ts），而非 package-status.test.ts。
6. 单元测试 = 快速且高信号 — 测试纯逻辑和内存场景；不依赖 Docker。绝不在代码编写完成后才编写单元测试。先列出失败模式，再为每个列出的失败模式编写一个测试，然后编写代码。不要编写只检查调用情况、模拟一切的测试。
7. 集成测试 = 允许使用真实依赖 — 超时时间较长；共享容器／数据库时，通常设置 fileParallelism: false。
8. 在运行脚本中设置 passWithNoTests（通常也在 defineConfig 中设置），避免空工作区导致编排失败。
9. 确保 vitest 和 @vitest/* 版本一致（单体仓库使用 catalog 时，通过 catalog 固定版本）。

详情：rules.md、tree.md、examples.md。

渐进式展开

需求	阅读
标准目录结构	references/tree.md
规则与反模式	references/rules.md
应编写、删除或移动哪些测试	references/test-signal.md
搭建／审查清单	references/checklist.md
良好与不佳的布局	references/examples.md
可选覆盖层	下方的 扩展

扩展

仅当存在匹配的技术栈（或用户提出要求）时才加载。切勿自行加载扩展来引入其技术栈：

条件	扩展
集成测试中使用 Testcontainers / Docker	with-testcontainers.md
测试中使用 @effect/vitest / Layers	with-effect-testing.md
Elysia Eden treaty(app)	with-elysia-eden.md
React + happy-dom / Testing Library	with-react-happy-dom.md
*.test-d.ts 类型项目	with-typecheck-project.md
Storybook + Vitest 浏览器	with-storybook-browser.md
健康探测 + skipIf 实时测试	with-live-harness.md
包级覆盖率阈值	with-coverage.md

单体仓库说明

如果 Turbo（或类似工具）从仓库根目录编排脚本，根目录的 test / test:integration 应调用各个包的 Vitest 脚本，而不是使用单个根级 Vitest 项目列表。任务图 / transit 相关细节应写在该仓库的单体仓库 架构文档中。