argent-qa-e2e

QA リグレッション e2e テストを作成する

作成エンジンとして argent-create-e2e を読み込みます。レコーダーの構文、セレクター、仕上げ、プラットフォームごとの例外、修復に関する必須のリファレンスに従います。このスキルでは、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 e2e テストを実行できますが、ハードウェア上の制限が 3 つあります。再生時にスマートフォンが自動でバインドされることはないため、device に udid（CLI では --device）を渡し、connected の状態を維持してください。pinch／rotate ステップはライブツールと同様に失敗するため、アプリ独自のズーム UI を操作してください。ランナーのツリーは describe ツリー（id と role は同じ）なので、シミュレーター用に作成したセレクターは実機で一致しない場合があります。記録を始める前に、アプリのスコープに沿った契約について argent-ios-device-interact を読みます。

完了の定義

QA e2e テストは、以下を満たした場合にのみ完了です。

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> e2e テストを 1 つ作成します。

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

繰り返し実行を決定論的にします。

1. 変更を加えずに、必要なベースラインを確認します。
2. アカウントが汚れている場合は、安全なリセットまたはシード用の e2e テストを記録します。あるいは、安全な正規化をセットアップに含めます。
3. セットアップの画面遷移後、名前付きベースラインをエコーし、最初のシナリオで変更を加える前にハードチェックします。assert:、またはベースラインを完全に証明する遷移先の await: を使用します。
4. 可能な場合は、最後にベースラインを復元します。

e2e テストには、フィクスチャを設定する方法が 2 つあります。

• run: は、別途記録されたリセットまたはシード用 e2e テストを再生します。
• script: は、要求されたローカルのセットアップまたはクリーンアップを実行します。ウォークスルーの該当箇所で e2e-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-e2e の開始順序とライブ作成サイクルに従います。各構造的な契約チェックは、その状態が現れた時点で記録します。

スナップショットにはレコーダー形式がありません。ウォークスルー中に安定した状態を検査し、仕上げの段階で計画したスナップショットを追加します。直接の復旧によって状態が変わった場合は、影響を受けた動作を再記録します。復旧後のウォークスルーは証拠になりません。

3. 識別力のある証拠を作る

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

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

4. 完了と監査

create-e2e の仕上げとブロッキング監査を完了します。その後、次の作業を行います。

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

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

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

5. 連続して2回パスすることを証明する

最後の編集と監査の後、連続パス数をゼロに設定します。

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

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

使用したランナーと、新しいサービスの準備方法を記録します。

6. レポート

以下を報告します。

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