argent-qa-flows

QA 回帰フローを作成する

作成エンジンとして argent-create-flow を読み込みます。レコーダーの構文、セレクター、仕上げ、プラットフォーム固有の例外、修復について、必須の参照先に従ってください。このスキルでは、QA の契約と完了ゲートを追加します。

Vega は以下のすべてに対応しています。launch: { vega: ... }、await:／assert: セレクター、snapshot:、idle はすべて実行できます。未対応なのはタッチディレクティブだけです。Vega はリモート操作されるためです。記録済みの tool: tv-remote ステップで移動し、tool: keyboard で入力してください。これにより、項目 5 で考慮することはありません。D-pad の経路は現在フォーカスがある位置を基準にするため、カーソルが移動したと決めつけず、項目 4 の識別チェックですべての移動をゲートしてください。フォーカスの読み取りとリモート操作によるナビゲーションについては、argent-tv-interact を読んでください。

Apple TV と Android TV は対象外です。 ランナーはそれらの環境でタッチディレクティブを拒否しないため、作成時のガイダンスではなく、ジェスチャー層で失敗します。argent-tv-interact を使い、制限事項を報告してください。

物理 iPhone でも QA フローを実行できますが、ハードウェア上の制限が 3 つあります。再生時に電話が自動バインドされることはないため、device に udid を指定し、CLI では --device を指定して、connected のままにしてください。pinch／rotate ステップはライブツールと同様に失敗するため、アプリ独自のズーム UI を操作してください。フローツリーは describe ツリー（同じ id と role）なので、シミュレーター用に作成したセレクターでは見つからない場合があります。記録する前に、アプリスコープの契約について argent-ios-device-interact を読んでください。

完了の定義

QA フローが完了とみなされるのは、次のすべてを満たす場合のみです。

1. echo: または script: ではない最初のステップが launch: であること。フロー内のセットアップで、決定論的なデータのベースラインを確立します。繰り返し実行してもアーティファクトが蓄積せず、手動でのクリーンアップも不要です。
2. 最初のウォークスルーですべてのアクションとライブの構造チェックを記録していること。記録せずに挿入できるのは、文書化された 3 つの仕上げ項目のみです。
3. すべての要件が、ハードな await:、assert:、またはレビュー済みの snapshot: に対応していること。エコーとスクリーンショットは判定の根拠になりません。否定チェックでは、同じ安定したセレクターが先に可視であることを確認している必要があります。
4. 画面が切り替わるたびに、遷移先の識別確認を行った後、準備完了状態として idle を確認すること。
5. 対象が安定セレクターのルールと座標フォールバックのルールを満たしていること。QA では、実際にラベルのない対象に限り座標を使用します。座標対象がない Vega では該当しません。
6. 同一の YAML を、同じランナーで 2 回実行して成功すること。1 回目はモバイルの Argent サービスを新規起動した状態で開始し、2 回目は直ちに続けて実行します。

1. テストの契約を定義する

アプリに触れる前に、簡潔な表を作成します。最終レポートにもこの表を記載してください。以下を含めます。

• アプリ、プラットフォーム、開始時の状態の名前。
• ユーザー操作の順序。
• 期待される結果、永続化ルール、または不在の主張ごとに 1 行。
• 各行を裏付ける、実行可能で安定した証拠。
• 必要なデータと副作用。

意味的な状態の確認には構造チェックを、ピクセルの確認にはスナップショットを、両方が必要な要件には両方を使います。1 つの動作シナリオにつき、qa-<area>-<behavior> フローを 1 つ作成します。

重要な値を勝手に作り出したり、曖昧さを都合よく弱めたりしないでください。UI で検証できる最も強い解釈を選び、その解釈を報告してください。選択によってテストの意味が変わる場合は、確認してください。

繰り返し実行しても結果が決定的になるようにします。

1. 変更を加えずに、必要なベースラインを調査します。
2. アカウントが変更済みの状態なら、安全なリセットまたはシードのフローを記録します。代わりに、セットアップに安全な正規化処理を含めてもかまいません。
3. セットアップ後のナビゲーションでは、名前を付けたベースラインをエコーし、最初のシナリオ変更を行う前にハードチェックします。assert: を使うか、ベースラインを完全に証明する遷移先の await: を使ってください。
4. 可能であれば、最後にベースラインへ戻します。

フローには、フィクスチャの仕組みが 2 つあります。

• run: は、別途記録されたリセットまたはシードのフローを再生します。
• script: は、要求されたローカルのセットアップまたはクリーンアップを実行します。ウォークスルー内の適切な位置で flow-add-script を使って記録してください。

依頼の範囲外で重要なユーザーデータを作成または削除するクリーンアップを行う場合は、事前に確認してください。

コンパクトな例

チケット：設定で「ダーク」を選択します。「ダーク」が選択され、「ライト」が表示されず、画面がダークモードで描画されることを確認します。

契約行	操作	証拠	状態への影響
サインイン済みのホーム	起動	await: { visible: { id: home-screen } }、続いて await: { idle: true }	既存のアカウント
設定を開く	settings-tabをタップ	await: { visible: { id: settings-screen } }、続いて await: { idle: true }	なし
「ライト」の選択を確認	設定を調べる	assert: { visible: { id: theme-light-selected } }	すでに「ダーク」なら失敗
「ダーク」の選択を確認	theme-dark-optionをタップ	await: { visible: { id: theme-dark-selected } }	テーマが「ダーク」になる
「ライト」が表示されないことを確認	安定した画面を調べる	assert: { hidden: { id: theme-light-selected } }	なし
ダーク表示を確認	安定した画面を調べる	snapshot: settings-dark	なし
基準状態に戻す	theme-light-optionをタップ	await: { visible: { id: theme-light-selected } }	次回の実行はクリーンな状態で始まる

最初に「ライト」を確認することで、後のhiddenチェックで使うセレクターが確立されます。最後に基準状態へ戻すことで、パス2は独立して実行できます。

2. シナリオを記録する

argent-create-flowの開始順序とライブ作成サイクルに従います。各構造的な契約チェックは、該当する状態になった時点で記録します。

スナップショットにはレコーダーで記録する方法がありません。ウォークスルー中に安定した状態を調べ、仕上げの段階で予定していたスナップショットを追加します。直接リカバリーによって状態が変わった場合は、影響を受けた動作を再記録します。リカバリー後のウォークスルーは証明にはなりません。

3. 識別力のある証拠にする

• 状態変更： 新しい状態を確認し、旧状態と両方が一致する可能性がある場合は、旧状態が存在しないことも確認します。
• キャンセル／永続化： コミット境界を越えて確認します。キャンセルまたは保存の後に画面を離れ、再び開いて、保存された状態がキャンセル後は変わらず、保存後は更新されていることを確認します。
• 不在： 画面が表示されていることを確認し、同じ安定したセレクターをvisibleとして記録してから、操作を行い、その後hiddenとして記録します。肯定的な基準状態を強化するためだけに、確立していないhiddenチェックを追加しないでください。コレクションでは、ビューポート内にないことは全体に存在しない証拠にはなりません。固定されたシード位置、件数、空の状態、またはコレクション全体を対象とする別の証拠を使用します。
• オーバーレイ： 作成フローの遮られた対象への対処手順を使用します。
• 繰り返し表示されるコントロール： IDを優先します。それ以外の場合は、安定したコンテナーとともにフロー限定のwithinを使用します。コンテナー内に描画されていることを証明するには、text.inを使用します。
• 動的コンテンツ： 制御された状態または安定したアプリのクロームをアサートします。避けられない動的な値にはアンカー付き構造を使用し、その依存関係を明記します。
• 視覚的な状態： 正しく、安定し、決定的な画面だけをスナップショットにします。全体的な変更には全画面を使用し、単一のコンポーネントにはcropOnを使用します。

受け入れ確認の証拠をwhen:の中に入れないでください。when:は、必須の経路に合流する任意のセットアップにのみ使用します。

4. 完了と監査

作成フローの仕上げとブロッキング監査を完了します。次に：

1. すべての契約行を、実行済みのアクションまたはハードチェックに対応付けます。
2. 画面の変更ごとに1行を設け、ID ゲートと準備完了ゲートの両方を記載したナビゲーションテーブルを作成します。どちらか一方でも欠けている行は、ブロッキング欠陥です。
3. セットアップと終了状態から、すぐに2回目の実行を開始できることを確認します。

アクション	遷移先	ID	準備完了
settings-tab をタップ	Settings	settings-screen が表示されている	idle

この2つは、それぞれ異なる方法で修正します。ID チェックが欠けている場合は、復元した画面上で実行中に記録する必要があります。idle チェックが欠けている場合は、YAML に追加します。これは、await: { idle: true } にはレコーダー形式がなく、argent-create-flow で許可されている3つの仕上げ用挿入のうちの1つであるためです。欠けているアクションやその他の構造チェックは、再度記録してください。

5. 連続 2 回のパスを証明する

最後の編集と監査が終わったら、連続回数をゼロに設定します。

1. 2 回の実行で同じランナーを選びます。ローカルでは flow-execute、CI では argent flow run <name> --platform <platform> を使用します。ランナーを切り替えると連続回数はリセットされます。
2. スナップショットのベースラインをシードし、レビューして固定します。ベースラインの更新はパスとして数えません。
3. モバイルで 1 回目のパスを実行する前に、このフローのデバイス向け Argent サービスを再起動します。ウォーム状態での 2 回のパスは、相関した証拠にすぎません。環境の速度が変わらなかったため、固定の時間マージンで 2 回ともパスする可能性があるからです。stop-all-simulator-servers は devices: [<device>] に範囲を限定します。必ず範囲を指定してください。範囲を指定しない呼び出しはマシン全体を対象とするため、ステップ 7 でこの検証を頻繁に再開するたびに、他のすべてのエージェントのデバイスまで繰り返し停止することになります。flow-execute では MCP 呼び出しを使用するか、スタンドアロンランナーのインストール先から argent run stop-all-simulator-servers --devices <device> を実行します。リセットによってアプリやアカウントのデータを変更してはいけません。Chromium の場合は、ランナーに宣言済みのアプリを起動させ、device は省略します。Vega は再起動可能な Argent サービスを所有しないため、そこでのティアダウンは何もせず、2 回ともウォーム状態での実行になります。
4. ベースライン更新モードを使わず、フローの起動およびセットアップから実行します。ok: true で、すべての受け入れチェックが実行された場合にのみ、パスとして数えます。when: が false の場合にスキップできるのは任意のセットアップだけです。ステップでエラーが発生しても連続回数は進みません。エラーは 2 種類あるため、それぞれの理由を確認してください。実行できなかったもの（idle 中にツリーが読み取れない、run: の対象を解決できないなど）は環境の問題です。修正して再実行してください。launch: の失敗も errored として記録され、アプリについての判定です。アプリがインストールまたは起動できなくなった場合、それこそこのテストで検出すべきリグレッションです。再実行せず、報告してください。
5. 完了前に、パスしたステップの警告をすべて解消します。flow-finish-recording が記録した待機に関する警告も解消してください。ライブ待機とチェックに従ってください。ランナーの警告については、await: { idle: true } は6 種類の異なる警告を出すため、まずどの警告なのか確認してください。2 種類は画面が動いていたことを示します。1 種類は保持中に待機がタイムアウトしたことを示し、より大きな timeout: が必要です。1 種類はツリーが空のままだったことを示します。1 種類は、UI ツリーだけを基準に安定していたことを示します。つまり、階層構造は静止しており、スクリーンショットのペアだけが不足していたため、アプリの描画ではなくキャプチャパスを調査してください。1 種類は、どちらの状態を示す証拠もないままステップが終了したことを示します。画面を確認して原因を明らかにし、前後の受け入れチェックが静止状態ではなく安定した要素を使っていることを確認してください。セレクターなしのジェスチャー（座標指定の tap／long-press／swipe、または on: のない pinch／rotate）は、別の形で警告されます。ツリーソースが利用できず状態が安定しなかったため、ジェスチャーが画面を見ずに送信されたことを示します。緑色の結果が示すのは、ジェスチャーが送信されたことだけです。ツリーソースを復旧させます。通常はアプリを再起動して計測機能を読み込ませてから再実行します。この警告を許容するには、ツリーを提供しないアプリが必要ですが、そのようなアプリではこの契約を満たせません。
6. 同じ YAML を同じランナーで直ちに再実行します。アプリやアカウントのデータを手動でリセットしてはいけません。
7. 失敗、編集、再記録、ベースライン更新、または状態を変更する手動復旧の後は、連続回数をリセットします。argent-create-flow を通じて修正し、再度監査して、新しいサービスでやり直します。

連続回数が 2 に達した場合にのみ完了とします。使用するランナーが利用できない場合は、検証がブロックされていると報告します。製品の動作に問題がある場合は、強力なチェックを維持し、リグレッションとして報告します。緑の結果を得るためにチェックを弱めてはいけません。

使用したランナーと、新しいサービスのセットアップ方法を記録してください。

6. レポート

レポートには、以下を記載します。

• フロー名、パス、プラットフォーム、単独で実行できるコマンド。
• アクションとチェックに対応付けたコントラクト行。
• ナビゲーションテーブル。
• ベースラインのセットアップ、終了状態の復元、許容されるデータ依存関係。
• 両方の合格結果、ランナー、サービスの新規セットアップ、解決済みの警告。
• スナップショットの範囲、レビュー済みベースラインの状態、許容される不一致。
• 座標または生のジェスチャーに関する例外。
• 残っている人手による判断またはブロッカー。