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 も実行します
空のパッケージ	Turbo/CI が成功するように passWithNoTests を設定します

モード

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. 両方のセットアップがある場合は、2 つのプロジェクトを用意します： unit と integration を --project で選択します。独自の判断で統合テスト用のセットアップ（Testcontainers、テスト DB、compose スタック）やブラウザー用のセットアップを追加しないでください。提案し、承認を待ちます。
4. デフォルトのローカルゲートは単体テストです。 統合テストは別のスクリプト（test:integration）にします。主要なシグナルを担うため、CI では存在する場合に必ず実行します。
5. テストは tests/ 配下に置きます（すべての src/ ファイルの隣には置きません）。package-status.test.ts のような名前ではなく、側面に応じて status.test.ts のように命名します。
6. 単体テストは高速でシグナルが強いものにします — 純粋なロジックとメモリー内で完結するテストを対象にし、Docker を必須としません。コードを書いた後に単体テストを書くことは禁止です。まず失敗モードの一覧を書き、次に一覧内の失敗ごとにテストを 1 つ書いてから、コードを書きます。呼び出しの確認だけを行う、何でもモックするテストは禁止です。
7. 統合テストでは実際の依存関係を使用できます — タイムアウトを長めに設定します。コンテナー／DB を共有する場合は、多くの場合 fileParallelism: false を設定します。
8. 実行スクリプト（通常は defineConfig も）に passWithNoTests を設定し、空のワークスペースがオーケストレーションで失敗しないようにします。
9. vitest と @vitest/* のバージョンを揃えます（モノレポでカタログを使用している場合は、カタログでバージョンを固定します）。

詳細：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 の詳細は、そのリポジトリのモノレポアーキテクチャドキュメントに記載してください。