e2e-test-generator

Flutter E2E Test Auto-Generation Skill

Purpose

Using test specifications (Excel / Notion) as the Source of Truth, automatically generate Flutter integration_test code. Test code is the "result of decoding natural language specifications into Dart" and is treated as a disposable intermediate artifact.

Core Philosophy

Not "make it hard to break" but "make regeneration cost as close to zero as possible"

Test failure → the code is buggy → fix the code (the test is correct)
Specification change → the test is outdated → regenerate the test (the specification is correct)
Do not maintain test code by hand. Update the specification and regenerate the tests.

When to Use

Triggered by the following statements:

"Generate E2E tests" "Create integration_test"
"Generate test code from the test specification"
"Generate the test for ST-AUTH-001"
"Create a mapping report"

Prerequisites

It must be a Flutter project
A test specification must exist (Excel file or Notion page)
integration_test/ The directory must be available

Execution Flow

Phase 0: Project Analysis (Required, Execute First)

Step 0-1: Check the project structure

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ファイル検出
   この認識で合っていますか？」

Wait for the user's response here. Do not proceed to the next step.

Step 0-2: Check Key conventions

Check the existing Key usage and propose Key conventions.

既存の Key を検索：
- `Key('...')` や `ValueKey('...')` のパターン
- 既存の Keys クラス

結果に応じて：
- 既存規約あり → それに従う
- 既存規約なし → 標準規約を提案（references/key-convention.md 参照）

Wait for the user's response here.

Step 0-3: Detect custom widgets

Understand project-specific widget patterns in advance.

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
   この認識で合っていますか？」

Wait for the user's response here.

Phase 1: Reading the Test Specification

In the case of Excel

Confirm the file path with the user
Parse the Excel file and identify the following columns:
- Test item ID (e.g., ST-AUTH-001）
- Test content (scenario description)
- Preconditions (login state, data, etc.)
- Procedure (numbered operation steps)
- Expected results (numbered expected values)
Display the analysis results to the user for confirmation

In the case of Notion

Use the Notion MCP to read the page/database
Identify a similar column structure
Display the analysis results to the user for confirmation

Important: Associate steps and expected results by number.

「テスト仕様を読み取りました：

ST-AUTH-001: 正常ログイン/ログアウト
- 前提条件: 未ログイン状態
- 手順: 7ステップ
- 期待結果: 7項目
- 対象画面: ログイン画面、ホーム画面、マイページ

この仕様でテストを生成しますか？」

Wait for the user's response here.

Phase 2: Screen Code Analysis + Key Mapping

Step 2-1: Identifying the Target Screen

Estimate the screen to be operated from the steps in the specification.

仕様: 「ログイン画面でメールアドレスを入力」
  → ログイン画面の Dart ファイルを探索
  → lib/ui/auth/login_screen.dart を発見

Step 2-2: Collecting Existing Keys

Analyze the Widget tree of the target screen and collect existing Keys.

// 検索対象
Key('...')
ValueKey('...')
const Key('...')
{Screen}Keys.{name}  // Keys クラスのパターン

Step 2-3: Identifying Missing Keys

Identify elements that are required by the operation steps in the specification but do not yet have Keys assigned.

「以下の要素に Key が不足しています：

画面: LoginScreen (lib/ui/auth/login_screen.dart)
  ⚠️ メールアドレス入力フィールド → LoginKeys.emailField 推奨
  ⚠️ パスワード入力フィールド → LoginKeys.passwordField 推奨
  ✅ ログインボタン → 既存 Key あり

Key を追加しますか？（追加する場合、Keys クラスも生成します）」

Wait for the user's response here.

Step 2-4: Adding Keys (If Approved)

{screen}_keys.dart Generate (or update) the file
Add key: {Screen}Keys.{name} to the target Widget
Show the diff to the user

Key propagation strategy for wrapper widgets:

super.key Directly assign a Key to a wrapper widget that has a

CustomTextFormField(
  key: LoginKeys.driverIdPart1Field,  // super.key があるため直接付与可能
  controller: idPart1Controller,
)

super.key For wrappers that do not have a KeyedSubtree , wrap with
On the Page Object side, use the find.descendant pattern to identify the internal EditableText from the wrapper's Key

Phase 3: Test Code Generation

Step 3-1: Generating Page Objects

Generate a Page Object class for each screen. For details, refer to references/page-object-pattern.md .

Naming convention for Page Object classes:

Basic form: {Screen}PageObject(to avoid collision with the widget class name)
- Example: LoginPage widget → LoginPageObject test class
- Example: MyPagePage widget → MyPagePageObject test class
Exception: If it does not collide with the widget class name, {Screen}Page is also acceptable (e.g., AuthWallPage）

Scroll handling pattern:

Use scrollUntilVisible to access elements outside the screen
Targets elements at the bottom of the screen, such as the logout button on My Page
Encapsulate the scroll handling within the Page Object

pumpAndSettle Timeout adjustment:

For operations involving API communication (such as login), set Duration(seconds: 10) or more
For the timeout of the entire authentication flow, Duration(seconds: 15) is recommended

生成ファイル:
  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: Generating Scenario Tests

Convert the steps in the specification 1:1 into Dart test code. For details, refer to references/test-template.md .

生成ファイル:
  integration_test/scenarios/st_auth_001_test.dart

Step 3-3: Generating Test Helpers (First Time Only)

Generate common setup and teardown processing.

生成ファイル:
  integration_test/helpers/test_helper.dart
  integration_test/helpers/app_launcher.dart

Phase 4: Generating the Mapping Report

Generate a correspondence table between specification steps and code. This is the human review point.

For details, refer to 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 追加が必要）

Generated files: integration_test/reports/st_auth_001_mapping.md

Phase 5: Confirmation and Output

Present the list of generated artifacts to the user.

「以下のファイルを生成しました：

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 の妥当性を確認してください。」

Guardrail Separation Principle

Assertions (Expected Results)

Derive from the specification document. Do not derive from the code implementation.
If the specification document says "the home screen is displayed", generateexpect(find.byKey(HomeKeys.screen), findsOneWidget) .
Even if the code contains Navigator.push(HomeScreen()) , do not use it as the basis for assertions.

Operation Steps

Derive from the specification document + Key search in the code。
Specification document's "enter email address" → search the code for LoginKeys.emailField → generate enterText .

Regeneration Policy

Situation	Response
Test failure (code bug)	Fix the code. The test is correct.
Specification change	Regenerate the test. The specification is correct.
UI refactoring (no Key changes)	The test works as is.
UI refactoring (with Key changes)	Update the Keys class and regenerate the test.
Adding a new screen	Write a new specification and generate a test.

File Structure Conventions

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 Conventions

For details, refer to references/key-convention.md .

Quick Reference

Item	Convention
Class name	`{Screen}Keys`(e.g., `LoginKeys`）
Key value	`{screen}_{role}_{name}`(e.g., `login_field_email`）
Target	Elements to tap, input, and verify + the screen itself
File	`{screen}_keys.dart`(same directory as the screen)

Role List

role	Purpose	Example
`screen`	The screen itself	`login_screen`
`field`	Text input	`login_field_email`
`button`	Button	`login_button_submit`
`text`	Text display	`home_text_welcome`
`list`	List	`home_list_reservations`
`item`	List item	`home_item_reservation`
`dialog`	Dialog	`login_dialog_error`
`icon`	Icon	`home_icon_notification`

Assumed Structure of the Test Specification Document

Excel Column Structure

Column	Content	Use in AI
D: Test item ID	`ST-AUTH-001` , etc.	Test file name / function name
E: Test content	Scenario description	Test description
F: Preconditions	Login state, data, etc.	setUp / mock configuration
G: Steps	Numbered operation steps	Operation code via Page Object
H: Expected results	Numbered expected values	Assertions (derived from the specification document)

Test Categories

Category	ID Range	Content
Authentication	ST-AUTH-001〜005	Login, biometric authentication, auto-login, session
Reservation	ST-RSV-001〜004	Search, filtering, change, cancel
Usage	ST-USE-001〜002	Start to end of use, extension, forgotten items
My Page	ST-MYP-001	Settings, billing, coupons
Help	ST-HLP-001	FAQ search, emergency contact

Notes

Wait for user confirmation at each phase. Do not rush ahead and generate everything at once.
If there are ❌ items in the mapping report, propose adding Keys before generating test code.
Derive assertions only from the specification. Do not base them on the code implementation.
Do not affect existing Widget tests or unit tests.
Output generated code with Japanese comments.

Execution Mode

Standalone execution (for PoC)

Used when processing test cases one at a time. A single agent executes Phases 0–5 sequentially.

Team execution (for production)

Used for batch generation of multiple test cases or when quality is a priority. Split into 3 roles: PL, PG, and QA, and work in parallel with an Agent Team. For details, see references/agent-team-workflow.md .

PL（設計）: 仕様読み取り + 設計判断 + 最終レビュー
PG（実装）: コード解析 + Key追加 + テストコード生成
QA（検証）: マッピングレポート生成 + 整合性チェック

Reference Documents

references/key-convention.md - Details of Key conventions
references/page-object-pattern.md - Templates for the Page Object pattern
references/test-template.md - Test code templates
references/mapping-report.md - Format of the mapping report
references/poc-example.md - PoC execution example (ST-AUTH-001 / ic_card project)
references/real-project-patterns.md - Collection of patterns discovered in real projects
references/agent-team-workflow.md - Agent Team workflow (PL/PG/QA role split)

About this skill

Purpose

Core Philosophy

When to Use

Prerequisites

Execution Flow

Phase 0: Project Analysis (Required, Execute First)

Step 0-1: Check the project structure

Step 0-2: Check Key conventions

Step 0-3: Detect custom widgets

Phase 1: Reading the Test Specification

In the case of Excel

In the case of Notion

Phase 2: Screen Code Analysis + Key Mapping

Step 2-1: Identifying the Target Screen

Step 2-2: Collecting Existing Keys

Step 2-3: Identifying Missing Keys

Step 2-4: Adding Keys (If Approved)

Phase 3: Test Code Generation

Step 3-1: Generating Page Objects

Step 3-2: Generating Scenario Tests

Step 3-3: Generating Test Helpers (First Time Only)

Phase 4: Generating the Mapping Report

Phase 5: Confirmation and Output

Guardrail Separation Principle

Assertions (Expected Results)

Operation Steps

Regeneration Policy

File Structure Conventions

Key Conventions

Quick Reference

Role List

Assumed Structure of the Test Specification Document

Excel Column Structure

Test Categories

Notes

Execution Mode

Standalone execution (for PoC)

Team execution (for production)

Reference Documents