integration-e2e-testing

name	integration-e2e-testing
description	受理済みの振る舞いを観測可能な境界で証明する、最小限の統合/E2Eテストセットを選定・設計する。E2Eテストまたは統合テストの作成・レビュー時に使用。

統合テスト・E2Eテスト設計・実装ルール

参照資料

• references/e2e-design.md — PlaywrightによるE2Eテスト設計原則（候補の性質、選定基準、候補の記録）
• references/e2e-environment-prerequisites.md — service-integration-e2eの環境前提条件（seed data、auth fixture、環境チェックリスト）。fixture-e2eには稼働中のサービスも実データベースも不要

テスト種別と選定

テスト種別	目的	スコープ	外部依存	ファイル形式	実装タイミング
統合	in-processでのコンポーネント間連携を検証	システムの部分的な統合（in-processモジュール。UIコンポーネントではReact/TSのRTL+MSWなど）	モックまたはin-process	*.int.test.ts	実装と並行して作成
fixture-e2e	決定論的フィクスチャを用いてブラウザ上の振る舞いを検証	モックバックエンドまたはフィクスチャ駆動の状態によるUIフロー全体	モック/フィクスチャのみ — ライブサービスなし	*.fixture-e2e.test.ts	UI機能と並行して作成
service-integration-e2e	起動済みスタックだけが露呈できる契約を検証	サービスをまたいだシステム全体	ローカルの実サービスまたはservice-levelスタブ	*.service-e2e.test.ts	必要なサービスが存在してから実行

レーン選択（E2Eのみ）:

• ユーザー向けUIジャーニーのデフォルトレーンは fixture-e2e — 決定論的フィクスチャに対して実ブラウザを動かし、ユニット/統合テストでは検出できないバグ（ボタンが動作しない、状態が更新されない、ナビゲーションが壊れる等）を検出でき、インフラ準備なしにCIで実行できる
• 証明義務がデータ永続化、トランザクション整合性、外部サービス契約などの実サービス間の振る舞いにある場合は service-integration-e2e を選択する

受理済みの証明義務から始め、各義務をその故障を露呈できる最も安価な境界に割り当て、重複するカバレッジを除き、残った個別の故障をすべてカバーする最小のセットを残す。テスト数はその証明義務から決める。ある機能について、特定のレーンにテストが1件もないことも妥当である。

振る舞い優先の原則

候補のエビデンス

統合/E2Eテストの候補は、次の情報を示す:

• 受理済みの振る舞いが指定する境界での観測可能な結果
• 選択したレーンが実行するコンポーネントをまたぐ、実害のある故障
• その故障を再現できる自動テストハーネスまたは制御された環境

単独で観測できる振る舞いはユニット/コンポーネント検証へ振り分ける。制御された環境を利用できない場合は、service-integration-e2eの証明前提として記録する。

候補の振り分け

• ビジネスロジックの正確性、データ整合性、ユーザーが観測できる振る舞い、観測可能なエラーハンドリングは、その境界を必要とする場合に統合/E2Eの候補とする。
• 純粋な実装詳細とデータ変換はユニットテスト、性能に関する主張は性能検証、レイアウトだけの主張はビジュアルまたはUIチェックへ振り分ける。
• 外部契約自体が証明対象である場合は、service-levelスタブまたは制御されたローカルサービスで表現する。

スケルトン仕様

必須スケルトン形式

プロジェクトのテスト対象パターンに一致してコミットされるファイルは、そのテストランナー上で有効なままでなければならない。検出したフレームワークにおける最小のpendingスイート（describeとit.todo、またはその同等物）を用い、テストフレームワークのimportと必須コメントのみを含める。実装タスクがpendingのケースを置き換え、実装と同時にアプリケーションのimport、アサーション、フィクスチャ、モックセットアップを追加する。

各テストに以下の注釈を含めること。

// AC: "[受入条件原文]"
// Behavior: [トリガー] -> [処理] -> [観測可能な結果]
// @lane: integration | fixture-e2e | service-integration-e2e
// @dependency: none | [コンポーネント名] | full-ui (mocked backend) | full-system
// @real-dependency: [コンポーネント名]（任意。テスト境界で非モックのセットアップを指定した場合）
// Primary failure mode: [実装後のテストを必ず失敗させる具体的なリグレッション]
// Proof obligation: [実装後のテストでアサートすべき境界と観測可能な状態]
// Verification items: [義務が満たされたことを示す観測結果]

@lane 選択ルール:

• integration — in-processでのコンポーネント間連携。ブラウザは使用しない（例: React/TSではRTL+MSW、その他の言語ではin-processのモジュール/ハンドラ統合）
• fixture-e2e — モックバックエンドまたはフィクスチャ駆動の状態に対するブラウザレベルのUI検証。@dependencyは通常full-ui (mocked backend)
• service-integration-e2e — 起動済みのローカルサービスまたはスタブに対するブラウザレベルまたはエンドツーエンドの検証。@dependencyはfull-system

Property注釈

// Property: `[検証式]`
// fast-check: fc.property(fc.[arbitrary], (input) => [不変条件])

テストセットの選定

1. 根拠となる成果物またはタスクから、受理済みの振る舞いと記録済みの証明義務を読み取る。
2. 義務ごとに、テストを失敗させるべき実害のある故障と、それを露呈する観測可能な状態を挙げる。
3. 既存テストを検索する。同じ境界を実行し、その故障によって失敗する場合にのみ既存のカバレッジを再利用する。
4. 義務を満たす最も狭いレーンに割り当てる:
   • 単独の実行で振る舞いが露呈する場合はunit/component
   • in-processのコンポーネント契約はintegration
   • バックエンドを決定論的に扱えるブラウザ上の振る舞いはfixture-e2e
   • 永続化、トランザクション、メッセージ、外部契約など、起動済みの境界でのみ故障が露呈するものはservice-integration-e2e
5. 1つのシナリオで複数の義務を証明でき、アサーションと故障の対応が明確なままであれば統合する。セットアップや故障モードが異なる場合は別のシナリオにする。
6. 残った義務をカバーする最小のセットだけを出力する。各スケルトンに、受理済みの振る舞い、主要な故障、証明義務、選択したレーン、モック境界を記録する。

受理済みの振る舞いとリポジトリの証明境界を基準に選定する。プロダクト分析や数値化した価値見積もりは不要である。根拠となる情報源とリポジトリのエビデンスを確認しても、受理済みの振る舞いまたは必要な契約が未確定の場合はエスカレーションする。

実装ルール

Property-Based Test実装

Property注釈がある場合、fast-check必須:

• fc.assert(fc.property(...))形式で記述
• スケルトンの// fast-check:コメントをそのまま実装に反映
• 失敗ケース発見時は具体的なユニットテストとして追加（リグレッション防止）

振る舞い検証の実装

振る舞い記述の検証レベル:

ステップ種別	検証対象	例
トリガー	Arrangeで再現	API障害 -> mockResolvedValue({ ok: false })
処理	中間状態または呼び出し	関数呼び出し、状態変更
観測可能な結果	最終出力の値	戻り値、エラーメッセージ、ログ出力

合格基準: 「観測可能な結果」がテスト対象の戻り値またはモックの呼び出し引数として検証されていれば合格

検証項目の決定ルール

スケルトンの状態	検証項目の決定方法
// Verification items:が列挙されている	列挙された全項目をexpectで実装
// Verification items:がない	Behavior記述の「観測可能な結果」から導出
両方ある	検証項目を優先し、振る舞いは補足として使用

統合テストのモック境界

レビュー対象の主張に最初に合致する行を採用する:

条件	使用する境界
外部アダプター、query、migration、service契約自体がテスト対象	実境界、またはservice-integration-e2eレーンのservice-levelスタブ — モックは自身が代役を務める契約を証明できない
外部APIまたはネットワーク呼び出しがテスト対象でない	モック
テスト対象のコンポーネント間連携	実物のin-processコンポーネント
呼び出し自体がテストの検証対象（例: ログ出力）	検証可能なモック（vi.fn()）
呼び出しもその対象もテスト対象でない	実物、または無視

E2Eテストの実行条件

fixture-e2e:

• UI機能の実装フェーズと並行して実行する
• モックバックエンドまたはフィクスチャ駆動の状態を使用する（@dependency: full-ui (mocked backend)）
• 決定論的なフィクスチャのセットアップを用いてCIで実行する

service-integration-e2e:

• 全コンポーネントが実装され、ローカルスタックが起動した後の最終フェーズでのみ実行する
• ローカルの実サービスまたはservice-levelスタブを通して検証対象コンポーネントを実行する（@dependency: full-system）

レビュー基準

スケルトンと実装の整合性

チェック	不合格条件
Property検証	Property注釈があるのにfast-check未使用
振る舞い検証	「観測可能な結果」に対応するexpectがない
検証項目網羅	列挙された検証項目がexpectに含まれていない
モック境界	統合テストで内部コンポーネントをモック化

実装品質

チェック	不合格条件
AAA構造	Arrange/Act/Assertの区切りが不明確
独立性	テスト間で状態共有、実行順序依存
再現性	日時・乱数に依存し結果が変動

共有mutationに対する経路の同等性

複数の経路が同じmutationに到達する場合 — CLIの経路とHTTPハンドラ、スケジュールジョブと手動トリガー、バッチと単件エンドポイント — 4つの軸で比較する: 検証、分類、リソース上限、およびread / parse / mutation / reportingの順序。

差異を許可できるのは意図を決める出所のみ: 要件、Design Doc、ADR。テストはその判断の下流にある。存在する振る舞いを記録するものなので、許容側の経路をカバーする既存テストはそのbypassを許可するのではなく確認していることになる。差異が許可された後は、テストが決定どおりに振る舞うことを検証する。

許可する出所を持たない差異については、bypassを露呈させるテストを要求する。チェックをスキップする側の経路でmutationを実行し、そのスキップされたチェックが守っていた状態をアサートする。

チェック	不合格条件
検証の同等性	一方の経路が検証する入力を他方が未検証で受け入れており、その差異を許可する要件も契約もない
分類の同等性	同じ失敗が経路によって異なる分類となり、呼び出し側が観測する内容が変わる
リソース上限の同等性	一方の経路がサイズ・件数・タイムアウトの上限を強制し、他方が省いている
操作順序の同等性	read / parse / mutation / reportingの順序が経路間で異なり、検証前にmutationしたり永続化前に報告したりしうる
bypassのカバレッジ	説明のつかない差異について、許容側の経路でmutationを実行するテストがない