end-to-end-testing

エンドツーエンドテスト

このスキルでは、エンドツーエンド（E2E）テストの作成、実行、レビュー、保守を行う方法を説明します。E2E テストとは、モック化したユニットではなく、実行中のビルドに対して、実際のユーザーやクライアントと同じようにシステム全体を検証する自動チェックです。新しいテストスイートを作成する場合、既存のスイートにテストを追加する場合、不安定な実行や失敗した実行を診断する場合、あるいは他の人が行った E2E の変更を評価する場合に活用してください。

ここで示す規約は、フレームワークに依存しません。E2E スイートは大きく次の 3 つの形式に分かれますが、どの形式にも同じ原則が適用されます。

• ブラウザー駆動の UI（例：Playwright、Cypress、WebdriverIO）— 実行中のウェブアプリに対して実際のブラウザーを操作します。
• デバイス駆動のモバイル UI（例：Maestro、Detox）— シミュレーター、エミュレーター、またはデバイス上で実際のアプリビルドを操作します。
• プロトコル／HTTP レベル（例：実際の REST、GraphQL、または MCP クライアントを操作する Vitest スイート）— 実際のサーバーを起動し、ブラウザーを使わずに、実際のクライアントでエンドポイントを検証します。

コード例では、具体的なテストランナー（通常は Playwright）を使用しています。API はプロジェクトのテストランナーに合わせて読み替えてください。複数のスタックに共通して適用されるのは、本文に記載されている規則です。

このスキルが対象とするのは、実際のビルドに対するシステム全体のチェックである E2E レベルです。依存関係をモック化して 1 つのユニットを分離するチェックは、代わりにユニットレベルに属します。プロジェクトにユニットテスト用のスキルがある場合は、その規約に従ってください。

テストレベルとテストランナーは別のものです。E2E スイートが、プロジェクトで提供されている機能に対応するテストランナー上で実行される場合、ランナー固有の設定ファイル、プロジェクト、プール、レポーター、ブラウザーモードの設定は、その機能の管轄です。一方、テスト対象の操作手順、ロケーターのフォールバック階層、サーバーのライフサイクル、シナリオの網羅性は、引き続きこのスキルの対象です。

このドキュメントに記載されている「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、RFC 2119 に記載されている定義に従って解釈してください。

エンドツーエンドテストの実行

commands.md では、次の内容を説明しています。

• デフォルトのローカル検証実行と、より高速な反復実行
• 意図的な視覚的変更に限ってスナップショットを更新する方法
• ベース URL の環境変数を使用して、開発環境、ローカルの本番ビルド、またはデプロイ済みの環境を対象にする方法

テストスイートの構成

structure.md では、次の内容を説明しています。

• E2E テストを専用ディレクトリに置き、ユニットテストとは別のテストランナー用 glob を設定する方法
• ルートツリーに沿ったディレクトリ構成（デフォルト）と、単一ルートまたは操作手順を中心とするアプリ向けの目的別構成（スモークテスト／ハッピーパス／リグレッション／機能領域）
• テストファイル名、テストケース名、ステップの粒度（複数フェーズのシナリオではステップを使用し、短いアトミックテストでは省略する）

テスト作成の規約

conventions.md では、次の内容を説明しています。

• ロケーター／セレクターのフォールバック階層（まず安定したテスト ID、アクセシブルなコントロールにはロール、文言の検証に限ってテキストを使用）
• 手動で状態を読み取る方法よりも、ネイティブの自動待機アサーションを使い、内部実装ではなく観測可能な契約を検証する方法
• 固定時間のスリープではなくポーリング／条件待ちヘルパーを使用する方法と、固定時間のスリープが禁止される理由
• 各テストケースから独立したセットアップフックとクリーンアップフック

テスト環境とフィクスチャ

test-environment.md では、次の内容を説明しています。

• ファイルごとにクライアント／コンテキストを 1 つ共有し、システムが実際に公開しているクライアントを通して実際のテスト対象システムを操作する方法
• サーバーのライフサイクルを一元管理し、固定時間のスリープではなく準備完了状態をポーリングする方法
• デフォルトで決定論的に実行するルール（外部ネットワークへのライブアクセスを行わない）と、実際にネットワークに依存する操作手順のための手動による例外設定
• テスト間で認証済みセッションを 1 つ再利用し、検証済みデータを返すデータ／API ヘルパーを一元管理する方法

シナリオのカバレッジ

詳しくは、scenario-coverage.md を参照してください。

• シナリオカバレッジの指標（E2E の行カバレッジではなく、アサーションされたユーザージャーニー）と、行カバレッジを採用しなかった理由
• 人が作成したカタログでジャーニーを追加または廃止する方法、テストにシナリオ結合タグまたは領域／優先度／スモークのファセットタグを付与する方法
• 段階的なゲート（まず優先度が must のジャーニーを 100％にする）、正規化された { title, tags, status } の結果形式を基にプロジェクト独自の CI で実装する、カタログとタグの結合方法、サンプルカタログ（assets/scenarios.example.md）