はじめに
Takazudoの個人的なフロントエンドテスト戦略ガイド（AI支援開発向け）
Takazudoの個人的な開発ノートです。公式のテストドキュメントではありません。 個人的な参照とAI支援コーディングのために書かれています。
このサイトはAI支援開発のためのフロントエンドテスト戦略を扱っています。AIコーディングエージェントと一緒に作業する際に適切なテストアプローチを選択すること -- ユニットテストで十分な場合、ブラウザレベルの検証が必要な場合、そしてパスしたテストが実際に重要なことを検証していないという誤った確信の一般的な罠を避ける方法に焦点を当てています。
このサイトで扱う内容
ここに記載されている主要なトピックは、すべて実際の本番プロジェクトから抽出されたパターンに基づいています：
テストレベル -- ユニットテストからAIベース視覚検証までの6段階エスカレーションラダー。各レベルはカバレッジが増加し、ブラインドスポットが減少します
判断ガイド -- 変更内容に基づいてどのテストレベルを使用するか、テストをどこで・いつ実行するか（実行ティア）、間違ったレベルが選択された場合の一般的な失敗パターン、AIエージェントに必要な振る舞い、そしてリポジトリの種類ごとに開始スイートを選ぶためのアーキタイプ・プレイブック
ツールパターン -- プロジェクトの形ではなく特定のツールや実装技法を軸に構成されたページ：Vitest、Playwright、ビジュアルリグレッション、コンテナ内ブラウザ検証、cargo-nextest
プロジェクトレシピ -- 単一のツールではなくリポジトリやプロジェクトの形を軸に構成されたページ：バックエンド、Tauri、remark/rehypeプラグイン、ビルド済みサイトの整合性
CI運用 -- CI・デプロイ・リリースをまたいでスイートを実行する：環境ティア別テスト、スモークテスト、定期再試験、ブランチ戦略、公開、ランナーサイジング
テスト完全性 -- テストが偽る様々な形 -- フレイク、偽グリーン、自己一致、フィクスチャの罠 -- と、それを防ぐ規律
ツールリファレンス -- 各テストレベルのツールとコマンドのクイックルックアップ
Note
このガイドは主にフロントエンドに焦点を当てています。著者の強みがフロントエンド開発にあるためです。バックエンドテストは補足的なトピックとして扱っています -- 具体的には、フロントエンドとバックエンドが適切に分離され、それぞれ独立してテストできる場合に現れるパターンです。
核心的なインサイト
AI支援テストにおいて最も重要な概念はテストレベルのエスカレーションです。AIエージェントがバグを修正して解決済みと宣言する際、その修正の信頼性は検証に使用したテスト手法に依存します。ユニットテストはロジックの正しさを確認できますが、ユーザーが実際に画面上で結果を見られるかどうかは確認できません。「ロジック的に正しい」と「視覚的に正しい」の間のギャップが、誤った確信の最も一般的な原因です。
テストは繰り返すのではなく、エスカレーションすべきです。下位レベルのテストがパスしても問題が解消しない場合は、次のレベルに進みます：
レベル1 -- ユニット/ロジックテスト（vitest、jest）
レベル2 -- DOMベースのコンポーネントテスト（jsdom、Testing Library）
レベル3 -- ビルド出力検証（ビルドされたファイルを読む）
レベル4 -- E2Eブラウザテスト（Playwright、headless browser）
レベル5 -- 決定論的 + 視覚的検証（verify-ui + headless browser）
レベル6 -- AIベース視覚検証
レベル6は、既定で登っていくラダーの自然な最上段ではありません -- レベル4もレベル5もアサーションに到達できない稀なケース（canvasベースのエディタ、自由描画、多層合成など）のための最終手段のエスケープハッチです。非決定論的であり、CIゲートに組み込むべきではありません。
第2の軸: レベル vs ティア
上記のレベルが答えるのはテストが何を見られるかです。別の問いはどこで・いつ実行されるか -- すなわち実行ティア（内側のループ、PR CI、夜間スケジュール、ローカルの重量級レーン）です。ピクセルレベルのレベル5スペックは、実GPUが必要ならスケジュール実行のみに限定することもできますし、すべてのPRで実行することもできます。一方、単純なレベル1のユニットテストはほぼ常に内側のループとPRゲートに置かれます。「PR CIには重すぎる」はティアの問題であり、より低いレベルに落とす理由にはなりません。詳細は実行ティアを参照してください。
このガイドの使い方
まず判断ガイドで、現在のタスクに適したテストレベルを判断します
テストレベルセクションで各レベルの詳細を確認します
パターンカテゴリ -- ツールパターン、プロジェクトレシピ、CI運用、テスト完全性 -- で本番環境で検証済みの設定を参照します
ツールリファレンスをクイックルックアップ用に開いておきます