argent-test-ui-flow

プラットフォーム非依存

物理 iPhone（kind: "device"）では、まず argent-ios-device-interact を読み込みます。ほかの操作を行う前に launch-app を実行してください。アプリがバックグラウンドにあると、describe は失敗します。

iOS と Android では操作ツール名が同じです（gesture-tap、gesture-swipe、describe、screenshot、launch-app など）。ツールサーバーは、渡された udid に応じて自動で振り分けます（UUID 形式なら iOS、adb のシリアルなら Android）。

テストの前に、テスト対象のデバイスを決めてください。 list-devices を呼び出し、<device_selection_rule> に従います。プラットフォームを問わず、起動中のデバイスを優先してください。

プラットフォームを選択すると、以降はプラットフォームごとのセットアップスキルに従います。

プラットフォーム	セットアップスキル	デバイスの確認方法
iOS	argent-ios-simulator-setup	list-devices → 起動済みのデバイスがない場合は、udid を指定して boot-device
Android	argent-android-emulator-setup	list-devices → 使用可能なデバイスがない場合は、avdName を指定して boot-device

1. ワークフロー

すべてのインタラクションは argent MCP ツールを介して行います。開始前に、シミュレーター／エミュレーターの準備ができていることを確認してください。

表示される UI を変更する実装タスクでは、このワークフローをビジュアル受け入れテストの手順としても使用できます。

1. ベースラインのスクリーンショット：screenshot を呼び出して、現在の UI の状態を確認します。ビジュアル回帰比較や UI 変更の検証では、編集前に可能であれば scale: 1.0、includeImageInContext: false を指定してベースラインを取得し、返された path を保持してください。
2. 対象を見つける：タップする前に、探索ツールを使って要素の座標を取得します。
   • React Native アプリ：debugger-component-tree を使用します。このツールはコンポーネント名と（タップ位置：x,y）の座標を返します。どちらのプラットフォームでも、RN アプリではこのツールを優先してください。使用するには、argent-react-native-app-workflow スキルを解決してセットアップします。Android では、Metro にデバイスから接続できるように adb -s <serial> reverse tcp:8081 tcp:8081 も実行する必要があります。
   • 標準のアプリ画面とアプリ内モーダル：describe を使用します。iOS では AX ツリーが返されます（AX が空の場合は native-devtools にフォールバックします）。Android では、同じ DescribeNode 形式の uiautomator ツリーが返されます。
   • 権限プロンプト／システムモーダルオーバーレイ：まず describe を試してください。オーバーレイが安定して公開されない場合に限り、screenshot にフォールバックします。アプリが独自の権限ダイアログを表示した場合は、ここで応答してください。それがテスト対象の実際のフローです。プロンプトをフローから除外する（起動前に権限を許可／拒否する、ユーザーがすでに拒否した権限を再度有効にする、またはダイアログを再表示させるためにリセットする）には、ダイアログを操作するのではなく、セットアップ時に argent-settings-permissions スキルを使用してください。
   • フォールバック：screenshot を使って目的のコンポーネントの位置を推定し、操作の直後に必ず確認します。
3. 操作する：操作（gesture-tap、gesture-swipe、keyboard、button など）を実行します。スクリーンショットが自動的に返されます。
4. 検証する：返されたスクリーンショットで、期待した結果を確認します。読み込み中または遷移中の状態が表示されている場合は、推測した待ち時間を使うよりも、await-ui-element で状態が落ち着くまで待機することを優先してください（期待する要素が visible、またはスピナーが hidden）。ただし、画面に存在することが分かっているか、以前の describe で確認した、信頼できるセレクター（text／identifier／role）を使用してください。推測したセレクターではタイムアウトします。それ以外の場合は、短い固定時間だけ待機します。検証する内容に応じて証拠を選択してください。
   • ビジュアル（レイアウト、余白、色、タイポグラフィ、画像／アイコンの描画、クリッピング、はみ出し、テキストの描画）：ステップ 1 で取得したベースラインとの比較に screenshot-diff を優先してください。自動スクリーンショットでは見逃す可能性のある、ピクセル上の変化を検出できます。安定したベースラインがない場合に限り、自動スクリーンショットを目視で確認してください。
   • 構造（ナビゲーション状態、要素の有無、アクセシビリティラベル／値、選択状態、階層、ルート）：describe、debugger-component-tree、または native-describe-screen で検証します。
   • ランタイム／ログ／ネットワーク（コンソールエラー、API 呼び出し、永続化、タイミング）：view-network-logs、debugger-log-registry、debugger-evaluate、または対象を絞ったテストで検証します。デバッガーに接続できない場合、debugger-log-registry はログファイルを返さず、{ status: "not_connected", reason, guidance } を返します。これはアプリについての証拠ではありません。案内に従って再接続し、再度検証してください。
   • 複合：該当する分類ごとに証拠を収集します。
   • 総合的な判定を報告します。期待される動作、観測された動作、使用した証拠、および要求されたビジュアル差分の確認を妨げる要因を記載してください。
5. 繰り返す：フローの各ステップについて繰り返します。

2. テンプレート

Goal: Test [feature name]

Steps:
1. Classify expected result: visual / structural / runtime-log-network / mixed → choose evidence
2. [Navigate / tap / type to reach stable comparable starting point] → verify auto-screenshot
3. screenshot { scale: 1.0, includeImageInContext: false } → save baseline path when visual or mixed evidence needs diffing
4. [Perform the action to test] → verify auto-screenshot
5. Use screenshot-diff when requested or when comparable images add useful visual evidence
6. Report: pass / fail with combined visual, structural, runtime/log/network evidence as applicable

3. 例

ログインフロー

1. screenshot → see login screen
2. gesture-tap { x: 0.5, y: 0.4 }  → tap email field
3. keyboard { text: "[email protected]" }
4. gesture-tap { x: 0.5, y: 0.55 } → tap password field
5. keyboard { text: "{{secret:APP_PASSWORD}}" }
6. gesture-tap { x: 0.5, y: 0.7 }  → tap Login button
7. screenshot → verify home screen appeared

認証情報： 平文の認証情報は絶対に入力せず、keyboard では {{secret:<NAME>}} プレースホルダーを使用してください。値はサーバー側で解決されるため、エージェントのコンテキストに入りません。値は ARGENT_SECRET_<NAME> 環境変数、または Argent のシークレットファイル（プロジェクト内の .argent/secrets.env、~/.argent/secrets.env、プロジェクトの .env / .env.local にある ARGENT_SECRET_ 接頭辞付きキー）から取得されます。名前が定義されていない場合、エラーには利用可能な名前と確認したすべてのパスが表示されます。シークレットを会話に貼り付けるのではなく、ユーザーにそれらのファイルのいずれかへ追加するよう依頼してください（追加するとすぐに適用されます）。認証情報を捏造したり、シークレットの値をレポートや保存ファイルに出力したりしないでください。

スクロールとナビゲーション

1. screenshot → see list at top
2. gesture-swipe { fromY: 0.7, toY: 0.3 } → scroll down
3. gesture-tap item at visible position → verify auto-screenshot
4. screenshot → verify detail view opened
5. button { button: "back" }
6. screenshot → verify returned to list

視覚的な動作確認

1. Classify expected result as visual or mixed.
2. Navigate to the stable starting state.
3. screenshot { scale: 1.0, includeImageInContext: false } → save baseline path.
4. describe / debugger-component-tree → find the control and use its returned tap coordinates.
5. gesture-tap → perform the visual behavior under test.
6. screenshot-diff { baselinePath, captureCurrent: true, udid, outputDir } → inspect visible change or stability.
7. describe / debugger-component-tree → verify selected state, label, route, or attributes if relevant.
8. Report combined verdict from expected behavior, visual inspection, diff summary, and structural evidence.

読み込みスピナーを待つ

1. gesture-tap { x: 0.5, y: 0.7 } → trigger an action that fetches data
2. screenshot → loading spinner is showing
3. await-ui-element { condition: hidden, selector: { text: "Loading" } } → block until the fetch finishes and the spinner disappears; its result carries the screenshot and element tree, so verify the fetched content rendered from it

---

4. 復旧パターン

• 画面が遷移中、または読み込み中の場合：固定時間をむやみに待つのではなく、await-ui-element で対象要素が visible になるまで、またはスピナー／プレースホルダーが hidden になるまで待機し、落ち着いてから再確認します。遷移を確実に示す要素がない場合に限り、固定時間待機してから screenshot にフォールバックします。
• タップが対象を外した場合：検出ツール（describe / debugger-component-tree）を再実行し、新しい座標で一度だけ再試行します。
• 権限ダイアログまたはモーダルが表示されている場合：まず describe を再実行します。オーバーレイを確実に検出できない場合に限り、スクリーンショットに基づくナビゲーションを続け、閉じたらすぐに describe / debugger-component-tree に戻します。
• 同じ座標でタップが2回失敗した場合：停止して再検出し、要素が見つからなければ報告します。
• 保存済みの e2e テストが e2e-execute のリプレイ中に失敗した場合（上記のライブテスト手順とは異なります）：argent-create-e2e のリプレイ失敗の診断に従ってください。失敗を分類し、実際の画面を確認し、根拠のある最小単位を修正してから、e2e テスト全体を再実行します。

ヒント

• ポーリングせず、UI の状態変化を待ちます。 画面が先に変化する必要がある手順では、screenshot を固定時間の待機を挟んで繰り返し呼び出すのではなく、await-ui-element を使って要素が visible / hidden になるか、指定した text を含むまで待機します。argent-device-interact の await-ui-element セクションを参照してください。
• コンテキストメニューを開くための長押し（800ms）は、gesture-custom を使用します。
• 明確に報告します：何を期待していたか、何が見えたか、判定結果を伝えます。
• 権限モーダル：まず describe を試します。フォールバックとしてのみ screenshot を使い、表示されているボタンを一度に1つだけタップして、続行する前に返されたスクリーンショットで確認します。
• リプレイ用に記録します：テストしたフローを繰り返す可能性がある場合は、argent-create-e2e スキルを使って .yaml スクリプトとして記録します。これにより、後から手順を手動で1つずつ実行し直す代わりに、e2e-execute を1回呼び出すだけでシーケンス全体を再生できます。

関連スキル

スキル	使用する場面
argent-device-interact	タップ、スワイプ、入力のためのツール使用（iOS + Android）
argent-screenshot-diff	ビジュアルリグレッションと変更前後のスクリーンショット比較
argent-ios-simulator-setup	iOS シミュレーターの起動と接続
argent-android-emulator-setup	Android エミュレーターの起動と接続
argent-react-native-app-workflow	アプリの起動、Metro、ビルドの問題
argent-metro-debugger	コンソールログ、JS の評価、コンポーネントの検査
argent-create-e2e	再生可能な e2e テストとしてテストシーケンスを記録