finalrun-test-and-fix

FinalRun テスト・修正オーケストレーター

このリポジトリにおける FinalRun のカバレッジについて、生成 → 実行 → 診断 → 修正のエンドツーエンドのループを担当します。finalrun-generate-test や finalrun-use-cli を置き換えることはありません。これらを呼び出します。あなたの役割は、機能のテストを計画し、実行し、失敗した場合は生成されたアーティファクトを読み、バグがアプリのコードとテストのどちらにあるかを判断し、必要最小限の修正を適用して、成功するまで、または正当な理由で続行できなくなるまで再実行することです。

セッションですでに合意済みの計画、受け入れ条件、変更対象ファイルがある場合は、それらを主要な入力として扱ってください。何もない状態から始めないでください。

基本原則

• 調査中に見つかったバグの疑いは仮説であり、修正対象ではありません。 finalrun-generate-test がテスト計画のためにソースコードを読む際、壊れているように見えるコードや受け入れ条件に合わないコードに気づくことがあります。まだ修正しないでください。 仮説として記録し、生成するテストで実際にその処理経路を検証できることを確認してから、FinalRun の実行で仮説を確かめるか、否定してください。テストの実行前にソースコードを修正すると、テストが実際にどの挙動を検出するのかが分からなくなり、本来問題のなかったコードを「修正」してしまうおそれがあります。
• 修正する前に、テストを生成して実行します。 順序は厳守してください。まず finalrun-generate-test を使ってテストを作成または更新し、次に finalrun check をクリーンな状態にしてから、finalrun-use-cli で実行します。アーティファクトを読み、修正を適用するのはその後です。調査で立てた仮説が明白に思えても、テストの実行前にアプリのコードを編集しないでください。
• まずアプリを修正し、テストはその次です。 実行に失敗し、アーティファクトを読んだ後は、アプリが受け入れ条件を満たしていないことをデフォルトの仮説とします。要件が実際に変わった場合、またはアサーションが誤っていた場合に限り、テストを編集してください（たとえば、一時的なトースト／スナックバーを検証している場合や、機能で保証されていない位置関係を厳密に求めている場合など）。成功させるためだけにアサーションを緩めてはいけません。
• アーティファクトを真実の根拠とします。 CLI が出力した result.json、actions/、screenshots/、recording.*、device.log、runner.log を見て診断してください。YAML だけから推測してはいけません。また、CLI が示したアーティファクトを読まずに失敗を要約してはいけません。
• シークレット、認証情報、環境変数の値を決して捏造しないでください。 シェル変数がない場合や .finalrun/env/<env>.yaml のバインディングがない場合に実行が止まったら、正確な変数名とコマンドを示してユーザーに引き継いでください。値をでっち上げてはいけません。
• 成功するか、正当な理由で続行できなくなるまでループを続けてください。 検証エラー、ステップの失敗、実行失敗はタスクの終了ではなく、ループへの入力です。実行が成功するか、実行が本当に不可能な場合（エミュレーター／デバイスが利用できない、必要なシークレットがない、またはユーザーが実行を見送った場合）に限り、停止してください。

ワークフロー

1. 調査して生成する

finalrun-generate-test を呼び出してください。現在のセッションにある計画、受け入れ条件、変更対象ファイル、説明されたユーザーフローを渡し、ステップ 1～4 が既存のコンテキストを基に進められるようにします。このスキルに、YAML の作成ルール、フォルダーのグループ分け、環境ファイルの処理、finalrun check のループを任せてください。

調査中にアプリケーションのソースコードを編集してはいけません。 詳細な調査で、受け入れ条件に照らして疑わしいコードが見つかった場合は、仮説として記録してください（ファイル、行、疑っている内容、検証するテストステップを1行で記載します）。生成するテストで実際にその処理経路がカバーされることを確認し、実行によって仮説を確かめるか、否定できるようにしてください。「すぐに修正しよう」という気持ちは抑えてください。修正はステップ 5 で、実行による証拠が得られてから行います。

変更した範囲について finalrun check がクリーンな状態になってから、ここに戻ってください。

2. 実行

finalrun-use-cli を呼び出して、対象範囲を実行します。コマンドの組み立て方については、そのスキルの指示に従ってください。フラグの意味はそのスキルで定義されています。要点は次のとおりです。

• 実行前に、アプリを再ビルドするか、既存のビルドを使って実行するかをユーザーに確認します。 黙って再ビルドしたり、以前の --app の成果物が最新だと決めつけたりしないでください。ユーザーが再ビルドを選んだ場合は、先にビルドしてから --app <fresh artifact>（Android は .apk、iOS は .app）を渡します。既存のビルドを選んだ場合は、成果物のパスを尋ねるか確認し、それを --app として渡します。
• 反復を速くし、最初の失敗をすぐに把握できるよう、デフォルトでは直前に編集した単一の spec（複数の場合は該当する spec）を対象に finalrun test <selectors> を実行します。 ユーザーがスイート全体の実行を明示的に求めた場合（たとえば、最終承認前に機能全体でリグレッションがないことを確認する場合）を除き、finalrun suite は実行しないでください。
• ワークスペースに複数の .finalrun/env/*.yaml ファイルがある場合は、--env <name> を渡します。
• --app の拡張子から判別できない場合は、--platform を渡します。

CLI が実行成功を示した場合は、その時点で終了してください。レポート URL を含め、エスカレーションしないでください。

3. 失敗のトリアージ

実行が失敗した場合は、CLI が示した成果物を読みます。配置と読み取り順は、finalrun-use-cli の Post-Execution → On failure に定義されています。ここで重複して記載するのではなく、その一覧をそのまま使用してください。ユーザーに何か伝える前に、少なくとも失敗したテストの result.json、失敗したステップに対応する actions/ の項目、およびそのステップのスクリーンショットを読んでください。

4. 失敗の分類

失敗を次のいずれかに分類します。これにより、編集対象がアプリかテストか決まります。

成果物に見られる症状	根本原因	修正対象
actions/ の項目では、エージェントが説明された要素を特定できなかったと示されているが、スクリーンショットには正しい UI がはっきり表示されている	テストの表現が厳しすぎる（位置関係の指定が過剰、ラベルが誤っている）	テスト — ステップの条件を緩め、不要な位置関係の指定を削除します
スクリーンショットで、受け入れ基準に対してアプリの状態が誤っている（フィールドがない、ナビゲーションが誤っている、データが古い）	アプリのバグ	アプリのコード
runner.log または検証出力で未解決の ${variables.*}／${secrets.*}、あるいはプロバイダー API キーの欠落が示されている	環境／バインディング／シークレットを利用できない	どちらでもありません — 引き継ぎます。 エクスポートすべき変数を正確にユーザーに伝えてください。決して推測してはいけません
記録では一時的に表示されて消えているトースト／スナックバーに対して、テストが不安定になる	テストが一時的な UI を検証している	テスト — アサーションを、永続的な結果（更新されたリスト、バッジの件数、変更されたフィールド、遷移後の画面）の確認に置き換えます
device.log にクラッシュが記録されている、または記録がクラッシュダイアログで終了している	アプリのクラッシュ	アプリのコード
result.json の失敗メッセージに expected_state の不一致が報告され、スクリーンショットでもアプリが実際にその状態であることが確認できる	要件が変更された、またはアサーションが誤っている	新しい動作がセッションの受け入れ基準に照らして正しい場合のみ テスト。それ以外は アプリのコード

この表に明確に当てはまらない場合は、デフォルトで アプリのコード を修正します。

5. 修正の適用

• アプリのコードの修正： このリポジトリで直接編集します。修正範囲は限定してください。周辺のコードをリファクタリングしたり、起こりえないシナリオに対する防御的な分岐を追加したりしないでください。
• テスト YAML の修正： 既存のステップや expected_state 項目の表現を少し変更する場合は、YAML をその場で編集します。変更が大がかりな場合（新しいセットアップ手順、新しいエッジケースのカバー、環境バインディングの変更、新しい機能フォルダーなど）は、finalrun-generate-test に戻してください。冪等なセットアップ、許可されたアクションの語彙、位置関係の指定に関するガイダンス、環境ファイルの形式など、そのルールを一貫して適用します。
• アサーションを黙って削除したり、expected_state を - The screen is visible に弱めたり、実行を成功させるために失敗したテストをコメントアウトしたりしてはいけません。

6. 再実行

変更した範囲に対して finalrun check を再実行します。アプリのコードを変更した場合は、再実行の前に再ビルドするかどうかをユーザーに尋ねます。黙って再ビルドしてはいけません。再ビルドの確認が取れたら、新しい --app アーティファクトを渡します。そうでない場合は、既存のビルドパスを再利用します。失敗したときと同じ finalrun test コマンドを再実行します（単一スペックのフェイルファスト経路を維持し、ユーザーから依頼がない限り finalrun suite に切り替えないでください）。グリーンになるまでステップ 3 に戻ります。

7. 停止条件

次の場合にループを停止します。

• 実行がグリーンになった場合。CLI のレポート URL を添えて成功を報告します。
• 実行が本当にブロックされている場合：このホストでデバイス／シミュレーターを利用できない、ユーザーだけが提供できる必須のシークレットがある、またはユーザーが明示的に実行を見送った場合です。その場合は、ユーザーがローカルで実行する正確なコマンドを表示します。該当する場合は --app <path>、--env <name>、--platform も含め、何が妨げになっているのかを具体的に説明します。

ステップが失敗した、検証エラーが表示された、または最初の修正がうまくいかなかったという理由だけで停止してはいけません。これらはループの入力であり、終了条件ではありません。

このスキルが行わないこと

• YAML を一から作成すること、フォルダー構成を決めること、または .finalrun/env/*.yaml のバインディング形式を編集すること → finalrun-generate-test に引き継ぎます。
• CLI フラグ、アーティファクトの配置、ホストの準備状況、プロバイダー／モデルの選択、または finalrun doctor／finalrun runs／finalrun start-server の使い方を説明すること → finalrun-use-cli に引き継ぎます。
• 認証情報を捏造すること、アサーションを黙って緩和すること、またはグリーンの実行なしにタスクを完了扱いにすること（本当にブロックされている場合を除く）。

関連スキルとの連携

このスキルはオーケストレーターです。ループの各回で作業を引き継ぎます。

• YAML テスト、スイート、環境バインディングの作成または更新のみに関する依頼 → finalrun-generate-test
• CLI の実行、検証、またはアーティファクトの確認のみに関する依頼 → finalrun-use-cli
• FinalRun の失敗した実行のデバッグ、機能のエンドツーエンド検証、または UI の変更を FinalRun のテストで完了させることに関する依頼 → このスキルが対応し、他の 2 つのスキルを順番に呼び出します。