| name | e2e-test-generator |
| description | テスト仕様書（Excel/Notion）からFlutter integration_testコードを自動生成するスキル。
Page Objectパターン + Key規約に基づき、仕様ステップとコードの対応を示すマッピングレポートも生成する。
「E2Eテストを生成」「テスト仕様からテストコードを作って」「integration_testを生成」などの発言で発動。
|
Flutter E2E テスト自動生成スキル
目的
テスト仕様書（Excel / Notion）を Source of Truth として、Flutter の integration_test コードを自動生成する。
テストコードは「自然言語仕様の Dart へのデコード結果」であり、使い捨ての中間生成物として扱う。
核心思想
「壊れにくくする」のではなく「再生成コストを限りなくゼロにする」
- テスト失敗 → コードがバグっている → コードを直す（テストは正しい）
- 仕様変更 → テストが古い → テストを再生成（仕様が正しい）
- テストコードを手で保守しない。仕様書を更新し、テストを再生成する。
使用タイミング
以下の発言で発動：
- 「E2E テストを生成して」「integration_test を作って」
- 「テスト仕様書からテストコードを生成」
- 「ST-AUTH-001 のテストを生成して」
- 「マッピングレポートを作成」
前提条件
- Flutter プロジェクトであること
- テスト仕様書が存在すること（Excel ファイルまたは Notion ページ）
integration_test/ ディレクトリが使用可能であること
実行フロー
Phase 0: プロジェクト解析（必須・最初に実行）
Step 0-1: プロジェクト構造の確認
1. pubspec.yaml を読み込み、以下を検出：
- flutter_test / integration_test の依存
- 状態管理（riverpod, bloc, provider 等）
- ルーティング（auto_route, go_router 等）
2. lib/ のディレクトリ構造を解析：
- 画面ファイルのパス（lib/ui/, lib/presentation/, lib/features/ 等）
- 既存の Keys クラス（*_keys.dart）
- 既存の integration_test/
3. 結果をユーザーに確認：
「プロジェクト構造を解析しました：
- UI層: lib/ui/{module}/
- 状態管理: Riverpod
- ルーティング: auto_route
- 既存Keys: なし / 3ファイル検出
この認識で合っていますか？」
ここでユーザーの回答を待つ。次のステップに進まない。
Step 0-2: Key 規約の確認
既存の Key 運用を確認し、Key 規約を提案する。
既存の Key を検索：
- `Key('...')` や `ValueKey('...')` のパターン
- 既存の Keys クラス
結果に応じて：
- 既存規約あり → それに従う
- 既存規約なし → 標準規約を提案（references/key-convention.md 参照）
ここでユーザーの回答を待つ。
Step 0-3: カスタムウィジェットの検出
プロジェクト固有のウィジェットパターンを事前に把握する。
1. ラッパーウィジェットの検出:
- CustomTextFormField 等のカスタム入力ウィジェットを検索
- `super.key` の有無を確認（Key 伝播の可否判定）
- Key を受け取れないラッパーには KeyedSubtree での対応が必要
2. 認証フローパターンの判定:
- 直接ログイン画面パターン: アプリ起動 → LoginPage
- AuthWall 経由パターン: アプリ起動 → AuthWall → LoginPage（2段階認証フロー）
- AuthWall がある場合、AuthWall 用の Keys / Page Object も必要
3. テキスト入力ウィジェットの種類判定:
- 生の TextField / TextFormField → tester.enterText() が直接使用可能
- カスタムラッパー（CustomTextFormField 等）→ find.descendant パターンが必要
4. 結果をユーザーに確認：
「カスタムウィジェットを検出しました：
- テキスト入力: CustomTextFormField（super.key あり → 直接 Key 付与可能）
- 認証フロー: AuthWall 経由（2段階）
- ナビゲーション: AutoTabsScaffold + BottomNavigationTabItem
この認識で合っていますか？」
ここでユーザーの回答を待つ。
Phase 1: テスト仕様書の読み取り
Excel の場合
- ユーザーにファイルパスを確認
- Excel ファイルを解析し、以下のカラムを特定：
- 試験項目ID（例:
ST-AUTH-001）
- 試験内容（シナリオの説明）
- 前提条件（ログイン状態、データ等）
- 手順（番号付き操作ステップ）
- 期待結果（番号付き期待値）
- 解析結果をユーザーに表示して確認
Notion の場合
- Notion MCP を使用してページ/データベースを読み取り
- 同様のカラム構造を特定
- 解析結果をユーザーに表示して確認
重要: 手順と期待結果は番号で対応付ける。
「テスト仕様を読み取りました：
ST-AUTH-001: 正常ログイン/ログアウト
- 前提条件: 未ログイン状態
- 手順: 7ステップ
- 期待結果: 7項目
- 対象画面: ログイン画面、ホーム画面、マイページ
この仕様でテストを生成しますか？」
ここでユーザーの回答を待つ。
Phase 2: 画面コード解析 + Key マッピング
Step 2-1: 対象画面の特定
仕様書の手順から、操作対象の画面を推定する。
仕様: 「ログイン画面でメールアドレスを入力」
→ ログイン画面の Dart ファイルを探索
→ lib/ui/auth/login_screen.dart を発見
Step 2-2: 既存 Key の収集
対象画面の Widget ツリーを解析し、既存の Key を収集する。
// 検索対象
Key('...')
ValueKey('...')
const Key('...')
{Screen}Keys.{name} // Keys クラスのパターン
Step 2-3: 不足 Key の特定
仕様書の操作ステップで必要だが、まだ Key が付与されていない要素を特定する。
「以下の要素に Key が不足しています：
画面: LoginScreen (lib/ui/auth/login_screen.dart)
⚠️ メールアドレス入力フィールド → LoginKeys.emailField 推奨
⚠️ パスワード入力フィールド → LoginKeys.passwordField 推奨
✅ ログインボタン → 既存 Key あり
Key を追加しますか？（追加する場合、Keys クラスも生成します）」
ここでユーザーの回答を待つ。
Step 2-4: Key の追加（承認された場合）
{screen}_keys.dart ファイルを生成（または更新）- 対象 Widget に
key: {Screen}Keys.{name} を追加
- 変更差分をユーザーに表示
ラッパーウィジェットの Key 伝播戦略:
Phase 3: テストコード生成
Step 3-1: Page Object の生成
画面ごとに Page Object クラスを生成する。
詳細は references/page-object-pattern.md を参照。
Page Object クラスの命名規則:
- 基本形:
{Screen}PageObject（ウィジェットクラス名との衝突回避）
- 例:
LoginPage ウィジェット → LoginPageObject テストクラス
- 例:
MyPagePage ウィジェット → MyPagePageObject テストクラス
- 例外: ウィジェットクラス名と衝突しない場合は
{Screen}Page でもよい（例: AuthWallPage）
スクロール対応パターン:
- 画面外要素へのアクセスには
scrollUntilVisible を使用する
- マイページのログアウトボタンなど、画面下部の要素が対象
- Page Object 内でスクロール処理をカプセル化する
pumpAndSettle タイムアウト調整:
- API 通信を伴う操作（ログイン等）では
Duration(seconds: 10) 以上を設定
- 認証フロー全体のタイムアウトは
Duration(seconds: 15) を推奨
生成ファイル:
integration_test/page_objects/login_page_object.dart
integration_test/page_objects/home_page.dart
integration_test/page_objects/my_page_page_object.dart
Step 3-2: シナリオテストの生成
仕様書の手順を 1:1 で Dart テストコードに変換する。
詳細は references/test-template.md を参照。
生成ファイル:
integration_test/scenarios/st_auth_001_test.dart
Step 3-3: テストヘルパーの生成（初回のみ）
共通のセットアップ・ティアダウン処理を生成する。
生成ファイル:
integration_test/helpers/test_helper.dart
integration_test/helpers/app_launcher.dart
Phase 4: マッピングレポート生成
仕様ステップとコードの対応表を生成する。
これが人間のレビューポイント。
詳細は references/mapping-report.md を参照。
# マッピングレポート: ST-AUTH-001
| # | 仕様ステップ | 生成アクション | Key | 状態 |
|---|------------|-------------|-----|------|
| 1 | ログイン画面を表示 | pumpAndSettle() | LoginKeys.screen | ✅ Key一致 |
| 2 | メールアドレスを入力 | enterText(LoginKeys.emailField, '...') | LoginKeys.emailField | ✅ Key一致 |
| 3 | パスワードを入力 | enterText(LoginKeys.passwordField, '...') | LoginKeys.passwordField | ✅ Key一致 |
| 4 | ログインボタンをタップ | tap(LoginKeys.loginButton) | LoginKeys.loginButton | ✅ Key一致 |
| 5 | ホーム画面が表示される | expect(find.byKey(HomeKeys.screen)) | HomeKeys.screen | ⚠️ Key推定 |
| 6 | 予約ボタンをタップ | tap(HomeKeys.reserveButton) | HomeKeys.reserveButton | ❌ Key該当なし |
## 判定基準
- ✅ Key一致: Keys クラスに定義済みの Key と完全一致
- ⚠️ Key推定: 画面コードから推定した Key（要確認）
- ❌ Key該当なし: 対応する Key が見つからない（Key 追加が必要）
生成ファイル: integration_test/reports/st_auth_001_mapping.md
Phase 5: 確認と出力
生成物一覧をユーザーに提示する。
「以下のファイルを生成しました：
Keys クラス:
- lib/ui/auth/login_keys.dart (新規)
- lib/ui/home/home_keys.dart (新規)
Page Objects:
- integration_test/page_objects/login_page.dart
- integration_test/page_objects/home_page.dart
テストコード:
- integration_test/scenarios/st_auth_001_test.dart
マッピングレポート:
- integration_test/reports/st_auth_001_mapping.md
マッピングレポートを確認してください。
❌ マークの項目は Key の追加が必要です。
⚠️ マークの項目は Key の妥当性を確認してください。」
ガードレールの分離原則
アサーション（期待結果）
- 仕様書から導出する。コードの実装からは導出しない。
- 仕様書に「ホーム画面が表示される」とあれば、
expect(find.byKey(HomeKeys.screen), findsOneWidget) を生成。
- コードに
Navigator.push(HomeScreen()) があっても、それはアサーションの根拠にしない。
操作手順
- 仕様書 + コードの Key 探索から導出する。
- 仕様書の「メールアドレスを入力」→ コードから
LoginKeys.emailField を探索 → enterText を生成。
再生成ポリシー
| 状況 | 対応 |
|---|
| テスト失敗（コードバグ） | コードを修正する。テストは正しい。 |
| 仕様変更 | テストを再生成する。仕様が正しい。 |
| UI リファクタリング（Key 変更なし） | テストはそのまま動く。 |
| UI リファクタリング（Key 変更あり） | Keys クラスを更新し、テストを再生成。 |
| 新画面追加 | 新しい仕様を書き、テストを生成。 |
ファイル構成規約
project/
├── lib/
│ └── ui/
│ ├── auth/
│ │ ├── login_screen.dart
│ │ └── login_keys.dart ← Keys クラス
│ └── home/
│ ├── home_screen.dart
│ └── home_keys.dart ← Keys クラス
├── integration_test/
│ ├── page_objects/ ← Page Object（画面ごと）
│ │ ├── login_page.dart
│ │ └── home_page.dart
│ ├── scenarios/ ← シナリオテスト（仕様と1:1）
│ │ ├── st_auth_001_test.dart
│ │ └── st_rsv_001_test.dart
│ ├── reports/ ← マッピングレポート
│ │ ├── st_auth_001_mapping.md
│ │ └── st_rsv_001_mapping.md
│ └── helpers/ ← 共通ヘルパー
│ ├── test_helper.dart
│ └── app_launcher.dart
└── test_specs/ ← テスト仕様書（参考配置）
└── 総合試験項目書(Ph1).xlsx
Key 規約
詳細は references/key-convention.md を参照。
クイックリファレンス
| 項目 | 規約 |
|---|
| クラス名 | {Screen}Keys（例: LoginKeys） |
| Key 値 | {screen}_{role}_{name}（例: login_field_email） |
| 対象 | タップ・入力・検証する要素 + 画面自体 |
| ファイル | {screen}_keys.dart（画面と同ディレクトリ） |
Role 一覧
| role | 用途 | 例 |
|---|
screen | 画面自体 | login_screen |
field | テキスト入力 | login_field_email |
button | ボタン | login_button_submit |
text | テキスト表示 | home_text_welcome |
list | リスト | home_list_reservations |
item | リストアイテム | home_item_reservation |
dialog | ダイアログ | login_dialog_error |
icon | アイコン | home_icon_notification |
テスト仕様書の想定構造
Excel カラム構成
| 列 | 内容 | AI での利用 |
|---|
| D: 試験項目ID | ST-AUTH-001 等 | テストファイル名・関数名 |
| E: 試験内容 | シナリオの説明 | テストの description |
| F: 前提条件 | ログイン状態、データ等 | setUp / モック設定 |
| G: 手順 | 番号付き操作ステップ | Page Object 経由の操作コード |
| H: 期待結果 | 番号付き期待値 | アサーション（仕様書由来） |
テストカテゴリ
| カテゴリ | ID 範囲 | 内容 |
|---|
| 認証系 | ST-AUTH-001〜005 | ログイン、生体認証、オートログイン、セッション |
| 予約系 | ST-RSV-001〜004 | 検索、絞り込み、変更、キャンセル |
| 利用系 | ST-USE-001〜002 | 利用開始〜終了、延長、忘れ物 |
| マイページ | ST-MYP-001 | 設定、請求、クーポン |
| ヘルプ | ST-HLP-001 | FAQ検索、緊急連絡 |
注意事項
- 各フェーズでユーザーの確認を待つこと。先走って全生成しない。
- マッピングレポートの ❌ 項目がある場合、テストコード生成前に Key 追加を提案すること。
- アサーションは仕様書のみから導出する。コードの実装を根拠にしない。
- 既存の Widget テストや unit テストには影響を与えない。
- 生成コードは日本語コメント付きで出力する。
実行モード
単独実行（PoC 向け）
1テストケースを順次処理する場合に使用。Phase 0〜5 を1エージェントが逐次実行する。
チーム実行（本番向け）
複数テストケースの一括生成や、品質重視の場合に使用。
PL・PG・QA の3ロールに分割し、Agent Team で並行作業する。
詳細は references/agent-team-workflow.md を参照。
PL（設計）: 仕様読み取り + 設計判断 + 最終レビュー
PG（実装）: コード解析 + Key追加 + テストコード生成
QA（検証）: マッピングレポート生成 + 整合性チェック
参照ドキュメント
references/key-convention.md - Key 規約の詳細references/page-object-pattern.md - Page Object パターンのテンプレートreferences/test-template.md - テストコードテンプレートreferences/mapping-report.md - マッピングレポートのフォーマットreferences/poc-example.md - PoC 実行例（ST-AUTH-001 / ic_card プロジェクト）references/real-project-patterns.md - 実プロジェクトで発見されたパターン集references/agent-team-workflow.md - Agent Team ワークフロー（PL/PG/QA ロール分割）
