vitest-v4

Vitest のベストプラクティス

Vitest テストフレームワークのパフォーマンス最適化とベストプラクティスを網羅したガイドです。8 つのカテゴリにわたる 44 のルールを影響度順にまとめており、テストの作成、リファクタリング、コードレビューに役立ちます。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• Vitest のテストを新しく作成するとき
• 不安定なテストや遅いテストをデバッグするとき
• テスト設定を行うとき
• PR でテストコードをレビューするとき
• Jest から Vitest に移行するとき
• CI/CD のテストパフォーマンスを最適化するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	非同期パターン	重大	async-
2	テストのセットアップと分離	重大	setup-
3	モックのパターン	高	mock-
4	パフォーマンス	高	perf-
5	スナップショットテスト	中	snap-
6	環境	中	env-
7	アサーション	低〜中	assert-
8	テストの構成	低	org-

クイックリファレンス

1. 非同期パターン（重大）

• async-await-assertions - 誤検知を防ぐため、非同期アサーションを await する
• async-return-promises - テスト関数から Promise を返す
• async-fake-timers - 時間に依存するコードにはフェイクタイマーを使用する
• async-waitfor-polling - 非同期条件には vi.waitFor を使用する
• async-concurrent-expect - 並行テストではテストコンテキストの expect を使用する
• async-act-wrapper - act の警告を避けるため、ユーザーイベントを await する
• async-error-handling - 非同期エラー処理を適切にテストする

2. テストのセットアップと分離（重大）

• setup-beforeeach-cleanup - afterEach フックで状態をクリーンアップする
• setup-restore-mocks - 各テストの後にモックを復元する
• setup-avoid-shared-state - テスト間で可変状態を共有しない
• setup-beforeall-expensive - コストの高い一度限りのセットアップには beforeAll を使用する
• setup-reset-modules - モジュールの状態をテストするときはモジュールをリセットする
• setup-test-factories - 複雑なテストデータにはテストファクトリーを使用する

3. モックのパターン（高）

• mock-vi-mock-hoisting - vi.mock の巻き上げ動作を理解する
• mock-spyon-vs-mock - 適切に vi.spyOn と vi.mock を使い分ける
• mock-implementation-not-value - 動的なモックには mockImplementation を使用する
• mock-msw-network - ネットワークリクエストのモックには MSW を使用する
• mock-avoid-overmocking - 過剰なモックを避ける
• mock-type-safety - モックの型安全性を維持する
• mock-clear-between-tests - テスト間でモックの状態をクリアする

4. パフォーマンス（高）

• perf-pool-selection - パフォーマンスに適したプールを選択する
• perf-disable-isolation - 安全な場合はテストの分離を無効にする
• perf-happy-dom - 可能な場合は jsdom より happy-dom を使用する
• perf-sharding - CI の並列化にはシャーディングを使用する
• perf-run-mode-ci - CI 環境では run モードを使用する
• perf-bail-fast-fail - CI で早期に失敗させるには bail を使用する

5. スナップショットテスト（中）

• snap-inline-over-file - 小さな値にはファイル形式よりインラインスナップショットを優先する
• snap-avoid-large - 大きなスナップショットを避ける
• snap-stable-serialization - スナップショットのシリアライズを安定させる
• snap-review-updates - コミット前にスナップショットの更新を確認する
• snap-describe-intent - スナップショットテストには内容がわかる名前を付ける

6. 環境（中）

• env-per-file-override - 必要に応じてファイルごとに環境を上書きする
• env-setup-files - グローバル設定にはセットアップファイルを使用する
• env-globals-config - グローバル設定を一貫して構成する
• env-browser-api-mocking - テスト環境で利用できないブラウザー API をモックする

7. アサーション（低〜中）

• assert-specific-matchers - 汎用マッチャーより具体的なマッチャーを使用する
• assert-edge-cases - エッジケースと境界値をテストする
• assert-one-assertion-concept - 1 つのテストにつき 1 つの概念をテストする
• assert-expect-assertions - 非同期テストには expect.assertions を使用する
• assert-toequal-vs-tobe - toBe と toEqual を適切に使い分ける

8. テストの構成（低）

• org-file-colocation - テストファイルをソースファイルと同じ場所に配置します
• org-describe-nesting - 論理的なグループ化に describe ブロックを使用します
• org-test-naming - 説明的なテスト名を付けます
• org-test-skip-only - skip と only を適切に使用します

使用方法

詳細な説明とコード例については、各リファレンスファイルを参照してください。

• セクションの定義 - カテゴリー構造と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート
• async-await-assertions - ルールファイルの例
• mock-vi-mock-hoisting - ルールファイルの例

関連する項目

• アプリの Playwright E2E は対象外です。アドホックなブラウザー自動化については playwright-v1 を参照してください。アプリの E2E の規約は、利用するリポジトリのルールに記載されています
• inject() とデータベースの分離（PGLite、*.spec.ts と *.test.ts）を使用する HTTP アプリのテストは、利用するリポジトリ側の対象です。このスキルだけでなく、プロジェクトの Fastify テストルールに従ってください

関連スキル

• TDD の手法については、test-tdd スキルを参照してください
• MSW を使用した API モックについては、test-msw スキルを参照してください
• TypeScript のテストパターンについては、typescript スキルを参照してください

コンパイル済みの完全版ドキュメント

すべてのルールを展開した完全なガイドについては、references/compiled.md を参照してください