integration-e2e-testing

統合テストとE2Eテストの原則

参考資料

E2Eテストの設計：UI仕様に基づくE2Eテスト候補の選定については、references/e2e-design.md を参照してください。

テスト種別の定義と標準予算

テスト種別	目的	範囲	外部依存関係	入力設計ドキュメントごとの標準予算	実装時期
統合テスト	プロセス内でのコンポーネント間の連携を検証する	システムの一部を統合する（プロセス内モジュール。UIコンポーネントの場合は、React/TS向けのRTL+MSWなど、フレームワークのプロセス内レンダラー）	モックまたはプロセス内	最大3件	実装と並行して作成
fixture-e2e	決定論的なフィクスチャを使い、ブラウザー上でのUIの挙動を検証する	バックエンドをモック化した、またはフィクスチャ駆動の状態でのUI全体のフロー	モック／フィクスチャのみ — 実サービスなし	最大3件	UI機能と並行して作成
service-integration-e2e	実行中のローカルスタックに対する重要なユーザージャーニーを検証する	サービスをまたぐシステム全体	実際に稼働するローカルサービスまたはスタブ	最大1〜2件	検証対象と必要なサービスが実行可能になった最初のタスクで作成

レーンの選択（E2Eのみ）：

• ユーザー向けUIジャーニーのデフォルトレーンは fixture-e2e です。決定論的なフィクスチャを使って実際のブラウザーで実行し、ユニットテストや統合テストでは見逃す不具合（ボタンを押しても何も起きない、状態が更新されない、ナビゲーションが壊れているなど）を検出できます。また、インフラのセットアップなしでCI上で実行できます。
• ジャーニーの正しさが、データの永続化、トランザクションの一貫性、外部サービスとの契約など、安全に偽装できない実際のサービス間の挙動に依存する場合に限り、service-integration-e2e を追加します。

1つの入力設計ドキュメントを予算の適用範囲とします。そのドキュメント内のすべての受け入れ条件（AC）と候補に対して、各レーンの予算を一度ずつ適用してください。2つのE2Eレーンの予算は独立しています。あるジャーニーにfixture-e2eがあっても、service-integration-e2eの予算は消費されず、その逆も同様です。上記の数値は適用される標準予算として扱ってください。選択したテストでは受け入れ済みの要件や固有の故障モードを検証できない場合に限り、予算を超過できます。その例外と、テストを統合しても検証できない理由を記録してください。

挙動優先の原則

含める項目（ROIが高いもの）

• コンポーネント間で観測できるビジネス状態の遷移
• データの整合性と永続化の挙動
• ユーザーに見える機能の完全性
• エラー処理の挙動（ユーザーが目にするもの、体験すること）

他のテスト種別に振り分ける項目

• 計算やデータ変換のルール → それらを担うロジックのユニットテストで検証します
• 外部サービスとの接続 → 契約テスト／インターフェーステストで検証します
• パフォーマンス指標 → 専用の負荷テストで検証します
• 実装の詳細 → 代わりに観測可能な挙動を検証します
• UIのレイアウトの詳細 → 代わりに情報が利用できることを検証します

原則：テスト ＝ 隔離されたCI環境で検証可能な、ユーザーが観測できる挙動

ROI 計算

ROI は、同じテスト種別内で候補を順位付けするために使用します（インテグレーション候補同士、E2E 候補同士）。インテグレーションと E2E の予算は個別に選択するため、種別をまたいだ比較は不要です。

各候補について、ROI の各入力値を決める前に、その根拠となる証拠を記録します。該当する場合は、承認済み PRD、確認済みの要件コンテキスト、受け入れ済みの契約または法的義務、ユーザーが確認したテスト価値のコンテキスト、Design Doc の境界、および既存テストの証拠を使用します。値がない場合は 0 ではなく unknown とし、推論は観察された証拠ではありません。

ROI によって候補の順位、レーンのしきい値、または予算の選択が変わる可能性があり、test_value_context でまだ提供されていない場合は、正確に不足しているプロダクト入力と、その判断への影響を提示します。その単一の入力を受け取った後、提供された事実を適用し、残りの値はすべて判断に関連する unknown として保持し、数値スコアは未設定のままにします。Defect Detection は、証明境界と既存テストにおけるリポジトリの証拠に基づいて判断します。ROI の前に候補が除外される場合、予約済みジャーニースロットの対象候補が 1 つだけの場合、またはしきい値のない予算に残った候補がすべて収まる場合は、選択が変わらないため、その unknown を not_decision_relevant として記録し、数値スコアは未設定のままにします。

不明値の優先順位

値の入力を受け取った後も、判断に関連する unknown が残る候補については、受け入れ済みの法的または契約上の義務、確認済みのユーザーまたはビジネス成果との明示的なつながり、独自の Defect Detection の証拠、レーンの所有コストの低さ、ソース AC の順序の順に判断します。通常のレーン予算内で、受け入れ済みの義務と確認済みの成果境界を証明できる最小限の候補セットを選択します。数値のレーンしきい値は、すべてのスコアが確定している候補に適用します。影響を受ける候補の選択判断には、この証拠の優先順位を適用します。不明な入力、確認した証拠、および選択への影響を記録します。

確定した数値入力には、0、5、10 のいずれかのみを使用します。Legal Requirement はブール値です。適用される法的、規制上、契約上、または監査上の義務がないことを、適用される根拠資料を確認して判断した場合は false とし、確認した資料を記録します。

入力	スケール
Business Value	0 = ユーザーまたはビジネスの成果がない；5 = 意味はあるが重要ではない成果；10 = 中核的、収益、安全性、またはデータ整合性に関わる成果
User Frequency	0 = 到達不能／旧式；5 = 一部のユーザーまたは実行で定期的に発生；10 = 主要なジャーニーまたは実行経路
Legal Requirement	適用される受け入れ済みの法的、規制上、契約上、または監査上の要件がある場合に限り true；それ以外は false
Defect Detection	0 = 既存の証明と重複；5 = 独自の分岐／状態をカバー；10 = 重大な境界またはサービス間の障害を独自に検出

ROI Score = Business Value × User Frequency + Legal Requirement × 10 + Defect Detection
              (range: 0–120)

ROI Score が高いほど、同じテスト種別内での優先度が高くなります。スコアが同じ場合は、Legal Requirement（true を先）、Defect Detection、Business Value、User Frequency の順に値が高い候補を優先し、最後にソース AC の順序で決めます。正規化や上限設定は行わず、ランキングには未加工のスコアを直接使用します。重複排除は候補を完全に取り除く別の手順であり、スコアは変更しません。

レーン別の ROI しきい値

2 つの E2E レーンでは、所有コストが異なるため、それぞれ独立した標準しきい値を適用します。

レーン	ROI しきい値	理由
fixture-e2e	ROI ≥ 20（予約枠を超える場合）	ハーネスがあればコストはインテグレーションテストと同程度です。十分な数が揃っている場合に、シグナルの低いテストで MAX 3 を埋めないよう、下限を設けています
service-integration-e2e	ROI > 50（予約枠を超える場合）	ライブサービスのセットアップ、状態のクリーンアップ、失敗の診断には相応の所有コストがかかります。他の方法では価値を実証できないユーザージャーニーに限って予約します

予約枠のルール（以下の「複数ステップのユーザージャーニーの定義」を参照）は各レーンに適用され、しきい値より優先されます（予約候補は ROI スコアにかかわらず選出されます）。予約枠を超えて下限未満の候補を選出するのは、承認済みの要件、または未対応の明確な失敗モードによって例外が正当化される場合に限ります。価値の低いテストで水増しするのではなく、予算にはあえて空きを残してください。しきい値または予算の例外は、その例外を含むスケルトンに記録してください。

ROI の計算例

シナリオ	BV	頻度	法的要件	不具合	ROI スコア	テストタイプ	選定結果
コアとなるチェックアウトの UI フロー	10	10	true	10	120	fixture-e2e	選定（予約枠：ユーザー向けの複数ステップのジャーニーで、フィクスチャを使ってブラウザレベルで検証）
ライブの決済サービスを使ったコアとなるチェックアウト	10	10	true	10	120	service-integration-e2e	選定（ROI しきい値を上回る、実サービスの正確性を検証）
閉じるボタンによる UI 状態の更新	5	10	false	5	55	fixture-e2e	選定（fixture-e2e の予算 3 件中 2 位）
決済エラーメッセージの表示	5	5	false	5	30	fixture-e2e	選定（fixture-e2e の予算 3 件中 3 位）
任意のフィルター切り替え	5	5	false	0	25	fixture-e2e	重複排除時に除外（既存の検証と重複）
実際の決済プロバイダーを使った決済の再試行	5	5	false	5	30	service-integration-e2e	ROI しきい値未満（30 < 50）のため、選定されない
DB の永続化チェック	10	5	false	10	60	インテグレーション	選定（3 件中 1 位）
純粋なデータ変換	5	5	false	5	30	ユニット	選定されない（ユニットテストに回す）

複数ステップのユーザージャーニーの定義

候補が複数ステップのユーザージャーニーに該当するには、以下のすべてを満たす必要があります。

1. ユーザーの目標を達成するまでに、2 つ以上の異なる操作境界を順番に通過すること。境界の定義はシステムの種類によって異なります。
   • Web：異なるルート／ページ
   • モバイルネイティブ：異なる画面／ビュー
   • CLI：異なるコマンドの実行、または対話形式のプロンプト
   • API：トランザクションを構成する異なる API 呼び出し（例：作成 → 確認 → 確定）
2. ステップ間で状態が引き継がれること。つまり、あるステップで生成されたデータや実行された操作が、次のステップで受け付けられる内容または表示される内容に影響すること
3. ジャーニーに完了地点があること。つまり、ユーザーまたは呼び出し元が到達する最終状態があること（例：確認ページ、保存済みレコード、API の成功レスポンス、完了したワークフロー）

ユーザー向けとサービス内部のジャーニー

複数ステップのジャーニーは、予約枠の対象となるかどうかに応じて分類されます。

分類	条件	予約枠の対象	例
ユーザー向け	人間のユーザーが、UI、CLI、または直接の API 操作を通じて各ステップを直接開始し、結果を確認する	対象 — デフォルトでは fixture-e2e の予約枠を使用します。ジャーニーの正しさが実際のサービス間動作に依存する場合に限り、service-integration-e2e の予約枠を追加します	Web チェックアウトフロー、CLI セットアップウィザード、モバイルのオンボーディング
サービス内部	ユーザーが直接操作することなく、バックエンドサービスが各ステップを開始する	予約枠の対象外 — 統合テストを使用します。システム全体の検証が妥当な場合は、通常の ROI > 50 の経路を通じた service-integration-e2e も引き続き有効です	非同期ジョブパイプライン、サービス間サガ、スケジュールされたバッチ処理

この分類は、予約枠のルールと E2E ギャップチェックにのみ適用されます。それ以外の選択には、上記のレーン固有の ROI ルールが適用されます。

E2E テスト候補と E2E ギャップ検出の評価には、この定義を使用してください。

テストスケルトンの仕様

必須コメントパターン

各テストには、以下の注釈を必ず含めてください。

AC: [Original acceptance criteria text]
Behavior: [Trigger] → [Process] → [Observable Result]
@category: core-functionality | integration | edge-case | fixture-e2e | service-integration-e2e
@lane: integration | fixture-e2e | service-integration-e2e
@dependency: none | [component names] | full-system
@complexity: low | medium | high
ROI: [score]

@lane の選択ルール：

• integration — プロセス内でのコンポーネント間の相互作用。ブラウザーは使用しません（例：React/TS では RTL+MSW、任意の言語ではプロセス内でのモジュール／ハンドラー統合）
• fixture-e2e — モックバックエンド／フィクスチャ駆動の状態を使った、ブラウザーレベルの UI 検証
• service-integration-e2e — 稼働中のローカルサービスまたはスタブを対象とする、ブラウザーレベルまたはエンドツーエンドの検証

これらの注釈を囲むには、プロジェクトのコメント構文を使用してください（例：C 系言語では //、Python/Ruby/Shell では #）。

検証項目（任意）

検証ポイントを明示的に列挙する必要がある場合：

Verification items:
- [Item 1]
- [Item 2]

EARS 形式の対応付け

EARS キーワード	テストの種類	生成方法
When	イベント駆動	イベントを発生させる → 結果を検証する
While	状態条件	状態を設定する → 動作を検証する
If-then	分岐網羅	両方の条件分岐を検証する
（なし）	基本機能	直接呼び出す → 結果を検証する

テストファイルの命名規則

• 統合テスト：*.int.test.* または *.integration.test.*
• fixture-e2e テスト：*.fixture.e2e.test.*（または tests/e2e/fixture/ 配下に整理）
• service-integration-e2e テスト：*.service.e2e.test.*（または tests/e2e/service/ 配下に整理）

適切なファイル拡張子は、プロジェクトのテストランナーまたはフレームワークによって決まります。すでに単一の *.e2e.test.* 規則を使用しているリポジトリでは、各ファイルのヘッダーに @lane: を宣言していれば、その規則を引き続き使用できます。ルーティングと予算計上の基準となるのは、レーンの注釈です。

レビュー基準

スケルトンと実装の一貫性

チェック項目	失敗条件
動作の検証	実装されたテストに「観測可能な結果」へのアサーションがない
検証項目の網羅性	列挙された項目すべてがアサーションで網羅されていない
モックの境界	統合テストで内部コンポーネントがモックされている

共有ミューテーションにおけるルートの同等性

複数のルートが同じミューテーションに到達する場合は、検証、分類、リソース上限、および読み取り／解析／ミューテーション／報告の順序を比較してください。各差異には、権威ある要件、設計上の契約、または明示的なテスト上の主張が必要です。それらがない場合は、バイパスまたは一貫性のない結果を明らかにするテストを必須としてください。