patrol-write-test

プロジェクトの Patrol テストで LeanCode の Modules/System/ApiClients アーキテクチャ（例：patrol_test/modules/ ディレクトリや testApp ラッパー）を使用している場合は、このスキルを基盤とし、内容が異なる場合はそちらが優先される patrol-test-architecture も適用してください。

新しいテストを作成するときの作業順序

1. 既存のテストコードを調べ、再利用できる関数を確認します
2. 既存の関数を調整して、既存の用途と新しいテストの両方に合うかどうかも検討します
3. 必須要素にテストキーがまだ割り当てられていない場合は、割り当てます
4. テストの作成を開始します。既存の関数を再利用し、新しいテスト手順は新しいテストファイルに記述します
5. Patrol のアクションはテストファイルに直接記述し、新しいメソッドは作成しないでください
6. 開発中はこまめにテストを実行してください。テスト全体を書き終えるまで待たず、論理的な手順のまとまりが完了するたびに実行し、早い段階で失敗を検出します
7. テスト全体が成功したら、新しいコードを再利用可能な関数に整理します
8. 整理後にテストを再実行し、引き続き成功することを確認します

Patrol MCP の使い方

Patrol テストを実行する場合：

• patrol-run({ "testFile": "patrol_test/your_test.dart" }) を使用してテストを実行し、完了を待ちます
• セッションが実行中でない場合：指定したテストファイルで新しいセッションを開始します
• セッションがすでに実行中の場合：現在のテストを自動的に再起動します
• patrol-screenshot({ "platform": "android" }) または patrol-screenshot({ "platform": "ios" }) を使用して、テスト失敗のデバッグ用スクリーンショットを撮影します
• patrol-quit({}) を使用して、セッションを正常に終了します
• patrol-status({}) を使用して、現在の状態と直近の出力を確認します
• patrol-native-tree({}) を使用して、ネイティブ操作の記述やテスト対象外のアプリとのやり取りに必要な、現在のネイティブ UI ツリー階層を取得します。

Patrol テストのルール

Patrol API

• Patrol API（$()、.scrollTo()、.tap()、.enterText()、.waitUntilVisible() など）を直接使用するファイルでは、import 'package:patrol/patrol.dart'; を記述してください
• テストアクションを実装する前に、必ず Patrol API を確認してください：
  • コードベース内で既存の Patrol API の使用パターンを検索します
  • 該当するアクションについて、$.platform API を確認します
  • メソッドがコードベース内に見つからない場合は、https://patrol.leancode.co/ を確認します
  • 正しい API メソッドを確認してから実装します
• テストアクションを実装する前に、必ず $.platform のメソッドを確認してください
• flutter_test パッケージは使用しないでください。Patrol API のみを使用してください
• 単一のテストには Patrol MCP サーバーを使用し、すべてのテストには patrol test を使用してください。flutter test コマンドは使用しないでください
• patrolSetUp メソッドや patrolTearDown メソッドを独自に記述しないでください

アクションのルール

• tap、scrollTo、enterText の前後に $.pump、waitUntilVisible、waitUntilExists やその他の待機メソッドを使用しないでください。Patrol が自動的に処理します。これらはテストの最後にのみ使用してください
• ウィジェットを検索するには、キーのみを使用してください
• 絶対に必要な場合を除き、try catch ブロックは記述しないでください
• テストを記述したら、MCP サーバーで実行して動作を確認し、失敗した場合は修正してください
• 要素が見つからずにテストが失敗した場合は、アプリコード内でその要素までスクロールする必要があるか確認し、必要に応じてテストを調整してください

アサーションのルール

• アクションの後にアサーションを記述せず、テストの最後に記述してください
• テストの最後のアサーションには、waitUntilVisible の使用を優先してください
• waitUntilVisible では不十分な場合にのみ、アサーションに expect() を使用してください

ネイティブダイアログの処理

• フロー中に表示されるネイティブダイアログは、必ず処理してください：
  • ダイアログを表示させるアクションの直後に、ただちに処理します
  • ネイティブの権限ダイアログでは、$.platform.mobile.tap よりも $.platform.mobile.grantPermissionWhenInUse を優先してください

テスト用キー

• テストに関係するウィジェットにのみキーを割り当てます

• 既存のウィジェットにのみkeyパラメーターを追加します

• ウィジェットのシグネチャは絶対に変更しません

• 既存のコード構造は絶対にリファクタリングしません

• アプリ内でキーをハードコードしてはいけません。アプリとテストで共有するキーのファイルにあるキーを使用する必要があります

• アプリ内に新しいウィジェットを絶対に作成しません

• ウィジェットに割り当てられていないキーは絶対に作成しません

• 各キーの値が一意であることを必ず確認します

• キーは必ずアルファベット順に並べます

• ウィジェットのコンストラクターの最初のパラメーターとしてキーを追加します

• ウィジェットが一意でない場合（たとえば、リストから生成される場合）は、パラメーター化されたキーを使用します

  • 既存の場合は、必ず enum または DTO をパラメーターとして使用します
  • パラメーター化されたキーには、既存のウィジェットプロパティを使用します
  • アプリ内でパラメーター化されたキーを割り当ててから、キーのファイル内で固定値を使う（またはその逆の）ことは絶対にしません
  • ヘルパーメソッドは絶対に作成せず、代わりにパラメーター化されたキーを使用します
  • 既存の enum または DTO からウィジェットを生成する場合は、必ずその enum または DTO の値をパラメーターとするパラメーター化されたキーを使用します

  個別のキーを使用する場合：

  • ウィジェットがハードコードされていて、コンパイル時に判明している場合
  • ウィジェットに固有で意味のある名前がある場合

  パラメーター化されたキーを使用する場合：

  • ウィジェットが動的データから生成される場合
  • ウィジェットが DTO または enum から生成される場合
  • ウィジェットの数が可変または多い場合
  • ウィジェットがループ内またはリストから生成される場合