vitest

Vitest

Vitest に関連する作業（テストの作成・実行、設定、モック／スナップショット、カバレッジ、ブラウザモード、プロジェクト／プール、レポーター、Jest／Vitest 3／Vitest 4 からの移行）では、このスキルを使用してください。

スナップショット：[email protected]（2026-10-01）。バージョンが異なる場合は、source-map.md から更新してください。

ワークフロー

1. ローカルの Vitest 環境を確認します。
   • パッケージのバージョン：vitest と、バージョンをそろえた @vitest/*（スナップショットは 5.0.3）。Node は ^22.12 || ^24 || >=26。Vite のピア依存関係は ^6.4 || ^7 || ^8（必須。Yarn では vite を明示的に記載する必要があります）。
   • 設定：専用の vitest.config.*（vite.config を完全に上書き）と、Vite 設定内の test: {} のどちらかを確認します。設定は親ディレクトリから検索されません。
   • スクリプト：CI では vitest run を推奨します。プロジェクトで Vitest を使用している場合、Bun のテストランナーである bun test は使用せず、bun run test ／ bunx vitest を使用してください。
   • 環境：node（デフォルト）、jsdom ／ happy-dom、または Browser Mode プロジェクトのいずれかを確認します。
   • 成果物：プロジェクトのルートにある .vitest/（gitignore に追加してください）。
2. 日常的な使用方法については、まず usage-guide.md に従ってください。
3. バージョンに差異がある場合、または作業がブラウザ／カバレッジ／移行に関する場合は、ドキュメントを更新してください。source-map.md から始めてください。
4. 詳細については、以下を参照してください。
   • 設定、CLI、テスト API、環境、セットアップ：config-cli-api.md。
   • vi のモック、vi.when、タイマー、環境変数のスタブ、スナップショット：mocking-snapshots.md。
   • カバレッジ、ブラウザモード、プロジェクト、プール、レポーター、ベンチ：coverage-browser-projects.md。
   • Jest ／ Vitest 3 → 4 ／ 4 → 5：migration.md。
5. Vitest 5.x の API を優先してください（デフォルトで extends: true の projects、maxWorkers、ブラウザプロバイダーファクトリー、テストコンテキストのフィクスチャとしての bench、vi.when）。@vitest/* パッケージは vitest と同じバージョンにしてください。
6. 必要最小限のコマンド（vitest run path -t "name"、カバレッジ、またはブラウザプロジェクト）で検証してください。プール／分離／キャッシュの調整を行う場合に限り、vitest doctor を使用してください。

基本的な判断基準

• Vitest は Vite を基盤とするテストランナーで、Jest 互換の API を備えています。Bun に組み込まれた bun test ではありません。
• CI ／フックでは、必ず vitest run（または --run）を使用してください。通常の vitest はウォッチモードになり、CI／非 TTY によって実行モードが強制されない限り、非対話環境では終了しません。
• globals: true を設定していない限り、vitest からインポートしてください。エージェントがコードを明確に把握できるよう、明示的なインポートを推奨します。
• vi.mock ／ vi.unmock ／ vi.hoisted は巻き上げられるため、トップレベルに記述する必要があります。入れ子にするとエラーになります。ファクトリーから、巻き上げられていないローカル変数を参照することはできません。
• clearMocks のデフォルトは true です（各テストの前に呼び出し履歴がクリアされ、実装は保持されます）。モックを共有する並行テストでは、clearMocks: false が必要になる場合があります。
• 並行テストとスナップショット／アサーションを併用する場合は、グローバルな expect ではなく、テストコールバックから取得するコンテキストの expect を使用してください。
• resolves ／ rejects ／ toMatchFileSnapshot ／ expect.poll は、必ず await してください。非同期アサーションを待機しないと、テストは失敗します。
• デフォルトのプールは forks です。ネイティブアドオンで問題が発生する場合は、threads よりもこちらを推奨します。
• 専用の vitest.config.* は vite.config のオプションを無視します。Vite のプラグイン／エイリアスを拡張する場合は、mergeConfig を使用してください。
• インラインの test.projects はルート設定を継承し（デフォルトは extends: true）、Vite サーバーを共有することがあります。ファイル／ディレクトリ形式のプロジェクトは継承しません。
• プロジェクトでのカバレッジ設定はルートのみです。coverage.include を明示的に設定してください。パターンはプロジェクトのルートからの相対パスに対して照合されます（contains はありません）。
• Browser Mode は environment: 'jsdom' ではありません。browser.enabled とプロバイダーパッケージを使用してください。ロケーターはデフォルトで完全一致です。
• bench はトップレベルからインポートできません。*.bench.* ファイル内で { bench } フィクスチャを使用してください。
• Vite はテストを変換しますが、型チェックは行いません。必要に応じて typecheck またはプロジェクトの tsc を別途使用してください。

検証

リポジトリで定義されているコマンドを優先してください。Vitest に関する重要な作業では、関連する範囲をカバーしてください。

• bunx vitest --version を実行し、@vitest/* のバージョンが揃っていることを確認します。
• vitest run <file> -t "<name>"（または :line フィルター）で対象を絞って実行します。完全な名前では > を使います（-t 'suite > test'）。
• スナップショットの更新には、意図的に -u または watch モードの u のみを使い、差分を確認します。
• カバレッジのしきい値やレポートが重要な場合は、vitest run --coverage を実行します。
• ブラウザープロジェクト：UI／コンポーネントのテストを変更した場合は、ヘッドレス Chromium でスモークテストを実行します。
• 移行：workspace、文字列形式のブラウザープロバイダー、poolOptions、test(name, fn, options)、ネストされた vi.mock、トップレベルの bench インポート、test.sequential、browser.api が残っていないことを確認します。

実行したチェック、実行しなかったチェック、および残っている Vitest のバージョンに関する前提を報告してください。