patrol-e2e-testing

Patrol E2E テストスキル

Flutter プロジェクトで Patrol 4.x を使用して、エンドツーエンド（E2E）テストを設計、実装、実行します。

使用する場面

次のような場合にこのスキルを使用します。

• 新しい画面やユーザーフローに E2E テストカバレッジが必要な場合。
• 機能がネイティブコンポーネント（権限、通知、システムダイアログ、ディープリンク）と連携する場合。
• UI のバグを回帰テストとして記録する場合。
• クロスプラットフォームの動作（Android／iOS／Web）を検証する必要がある場合。
• 新規または既存の Flutter プロジェクトに Patrol をセットアップする場合。

セットアップ

インストールとプロジェクトの初期化については、Patrol の公式ドキュメントに従ってください。 https://patrol.leancode.co/documentation#setup

Patrol の主な規約：

• patrol を開発用依存関係として追加します。
• テストを patrol_test/ に配置します。
• テストファイル名の末尾には _test.dart を付けます。
• patrol test でテストを実行します。

ワークフロー

Patrol テストを実装または更新する際は、次の手順に従ってください。

1. ユーザージャーニーを特定する

機能を次の要素に分解します。

• 操作：タップ、スクロール、入力、画面遷移、ディープリンク。
• 観測可能な結果：表示されるテキスト、画面の変化、有効化されたボタン、ダイアログ。

ルール：

• 主要な（正常系の）ユーザージャーニーごとにテストを 1 つ作成します。
• 重要なエッジケースは個別のテストにします。
• 関連のないフローを 1 つのテストにまとめないでください。

2. Patrol テストを構成する

基本的な Patrol の構成：

import 'package:flutter_test/flutter_test.dart';
import 'package:patrol/patrol.dart';

void main() {
  patrolTest(
    'user can log in successfully',
    ($) async {
      await $.pumpWidgetAndSettle(const MyApp());

      const email = String.fromEnvironment('E2E_EMAIL');
      const password = String.fromEnvironment('E2E_PASSWORD');

      await $(#emailField).enterText(email);
      await $(#passwordField).enterText(password);
      await $(#loginButton).tap();

      await $.waitUntilVisible($(#homeScreenTitle));

      expect($(#homeScreenTitle).text, equals('Welcome'));
    },
  );
}

主な概念：

• testWidgets() の代わりに patrolTest() を使用します。
• $ は Patrol のテスターです。
• $(#keyName) を使用して、Key でウィジェットを検索します。
• 明示的な待機条件（例：waitUntilVisible）を使用します。

3. ネイティブダイアログを扱う

OS レベルの権限ダイアログの場合：

patrolTest('grants camera permission', ($) async {
  await $.pumpWidgetAndSettle(const MyApp());

  await $(#openCameraButton).tap();

  if (await $.native.isPermissionDialogVisible()) {
    await $.native.grantPermission();
  }

  await $.waitUntilVisible($(#cameraPreview));
});

ネイティブ自動化は、機能上必要な場合にのみ使用してください。

4. セレクターと操作のクイックリファレンス

ウィジェットの検索：

$('some text')        // by text
$(TextField)          // by type
$(Icons.arrow_back)   // by icon

タップ：

// Tap a widget containing a specific text label
await $(Container).$('click').tap();

// Tap a container that contains an ElevatedButton
await $(Container).containing(ElevatedButton).tap();

// Tap only the enabled ElevatedButton
await $(ElevatedButton)
    .which<ElevatedButton>(
      (b) => b.enabled,
    )
    .tap();

テキストの入力：

// Enter text into the second TextField on screen
await $(TextField).at(1).enterText('your input');

スクロール：

await $(widget_you_want_to_scroll_to).scrollTo();

ネイティブ操作：

// Grant permission while app is in use
await $.native.grantPermissionWhenInUse();

// Open notification shade and tap a notification by text
await $.native.openNotifications();
await $.native.tapOnNotificationBySelector(
  Selector(textContains: 'text'),
);

5. Patrol テストの実行

すべてのテストを実行します。

patrol test

ライブリロードを有効にして、特定のファイルを実行します（開発モード）。

patrol develop -t integration_test/my_test.dart

特定のファイルを実行します。

patrol test --target patrol_test/login_test.dart

Web で実行します。

patrol test --device chrome

ヘッドレス Web（CI）：

patrol test --device chrome --web-headless true

タグで絞り込みます。

patrol test --tags android

6. 安定化のパターン

不安定なテストは信頼性を損ないます。次のパターンを適用してください。

// AVOID — arbitrary delay
await Future.delayed(Duration(seconds: 3));

// PREFER — explicit wait condition
await $.waitUntilVisible($(#targetWidget));

// For animations, pump until settled
await $.pumpAndSettle();

• 同期手段として Future.delayed を決して使用しないでください。
• UI の状態を待つには、waitUntilVisible または waitUntilExists を使用します。
• CI 環境の処理が遅い場合は、PatrolTesterConfig で settleTimeout を設定します。

出力要件

このスキルを適用すると、次のものが作成されます。

1. 指定された機能をカバーする Patrol テスト。
2. 必要に応じて、本番コードに追加するウィジェットの Key。
3. ローカルで実行する正確な patrol test コマンド。
4. 安定化やタイミングの判断に関する注記。

チェックポイント： コミットする前に、ローカルで patrol test --target <file> を実行してテストが成功することを確認してください。

品質基準

有効な Patrol テストは、次の条件を満たす必要があります。

• 決定的である — 任意の遅延を使用せず、明示的な待機条件を使用します。
• 読みやすい — ユーザージャーニーを説明する明確なテスト名を付けます。
• 最小限でありながら完全である — ユーザージャーニーごとに 1 つのアサーションチェーンを使用します。
• シークレットを安全に扱う — 認証情報は String.fromEnvironment から読み込み、ハードコードしません。
• CI で実行できる — --web-headless true を指定したヘッドレス環境、またはエミュレーターで成功します。