browser-smoke

ブラウザーのスモークテスト

既存のブラウザースイートまたは宣言済みのブラウザードライバーを直接実行します。直接ブラウザーを使う分岐では、モデルプレビューを読み込みません。ブラウザーワーカーをディスパッチする前に、shared/references/model-preview.md を使用し、承認済みのスナップショットを1つ正確に選んで、ワーカーへのリクエスト、予約、プライバシー制御、レポートに紐付けます。ネストされた呼び出しでは同じスナップショットを再利用し、ワーカーを追加しません。

変更の影響を受ける可能性のあるルートについて、ブラウザーの証跡を作成します。これは差分に限定した確認です。コードを修正するものでも、リリース QA に代わるものでもありません。

結果

結果：ブラウザーで取得した証跡を含むルート表。

呼び出し元が shared/references/review-evidence.md を使用する場合、必須の観測項目ごとに、ドライバーの実際の出力またはスクリーンショットを保存します。ブラウザースモーク、検証、レビューでは、同じ観測項目の形式を使用します。

{
  "id": "checkout",
  "result": "pass",
  "evidence": [
    {"path": "/absolute/run/checkout.png", "sha256": "<SHA256>"}
  ]
}

id は、準備済みの要件で宣言されている必要があります。result は pass、fail、skipped のいずれかです。各行には、ハッシュ付きの絶対パスを持つアーティファクトが1つ以上必要です。スキップの理由は、ドライバーの出力またはその他の証跡ファイルに記録します。共有行にフィールドを追加してはいけません。共有検証ツールはファイルと宣言された観測結果を確認しますが、ブラウザー操作は繰り返しません。必須の観測項目がスキップされた場合、準備完了とはみなされません。

完了条件：マッピングされたすべてのルートが、理由付きで Pass、Fail、または Skip になっていること。ルートを一つも実行しなかった場合は、必ず SKIP とし、PASS にはしません。

モード

1. パイプラインは、承認済みの実装または検証ワークフローでのデフォルトです。references/pipeline-orchestration.md に従って、所有するローカルサービスを起動します。既存の権限を再利用します。
2. ユーザーがサーバーを明示的に管理する場合、または依頼が観測のみの場合は、手動モードを使用します。利用可能なサーバーを再利用します。認証情報またはデスクトップへのアクセスがない場合、影響を受けるルートのみをブロックします。

ワークフロー

1. ブラウザードライバーを1つ選択する

証拠の要件を満たす場合は、対象プロジェクトで動作しているブラウザースタックを再利用します。既存のブラウザーコマンドはそのまま実行します。ワーカーブランチでは、必要な機能と実際のワーカーのアクセス権に基づいて、承認済みの正確なスナップショットに記載された方式を選択します。

方式	選択する条件
Playwright Test	CIを含め、再現可能な受け入れテストまたは回帰テストのスイートがすでに存在する場合。別のモデルワーカーを介さずに直接実行します。
Playwright CLI with its skill	インストール済みで使用可能な場合、対話的な探索、ロケーターの確認、テストの作成や修正に最初に使用します。Playwright Testの実行とは異なります。
agent-browser	選択したワーカー環境で準備状況の確認に成功した場合に使える、探索の代替手段です。
Playwright MCP	構造化されたツールインターフェースまたはページの確認が必要な場合。すべてのワーカーに読み込まないでください。
Native host browser	認証済みセッション、ネイティブダイアログ、またはホスト機能が必要で、選択したワーカーから利用できる場合。
Raw Playwright library	プロジェクトですでに、必要な証拠の要件を満たす小規模なスクリプトまたはハーネスを使用している場合。

新しいブラウラースタックをインストールしないでください。コマンドやブラウザーバイナリが見つからない場合は、準備上の不足です。別のドライバーを選択する前に、選択した方式、バージョン、不足している機能を記録します。外部Piブラウザールートでは、browser: {mechanism, preflight: {path, sha256}}を選択内容に紐付けます。参照先のファイルには、実際の準備状況を示す証拠が含まれている必要があります。1つのジャーニーでは1つのドライバーを使用します。並行ワーカー間でセッション、ブラウザーコンテキスト、フィクスチャー、アカウントを分離し、この実行で所有するリソースのみを閉じます。

外部Piワーカーは、ホストのブラウザーツールを引き継ぎません。そのプロセスでのナビゲーション、現在の状態の確認、操作、アサーション、コンソール／ネットワークの取得、アーティファクトの出力について、事前確認を行います。ドライバーの手順と、実際に利用できるコマンドを提示してください。読み取り専用の分析モードではブラウザーコマンドを実行できません。既存の権限の範囲内で、明示的に選択されたブラウザーツールポリシーを使用してください。シェルアクセスはサンドボックスではなく、製品の修正を許可するものでもありません。

ビジュアル作業では、モデルの画像対応とドライバーのスクリーンショット取得方法を確認します。リポジトリの内容を送信する前に、Piの画像リーダーまたは添付経路を使って合成画像を読み込み、選択したアダプターを通じて型付きの画像ペイロードを取得します。プレーンテキストでパスや説明を示すだけでは不十分です。ドライバー、ツール、画像、または必要なプライバシー管理の事前確認に失敗した場合は、ルートをブロックしたままにします。

外部のPlaywright CLIまたはagent-browserの準備状況を確認するには、機能チェックを観察した後、共通のbrowser_preflight.pyヘルパーを使用します。navigation、state_inspection、interaction、assertions、evidence_captureの実際の真偽値と、取得したアーティファクトを含むJSONオブジェクトを渡します。

SHARED_DIR="<absolute shared skill directory>";
python3 "$SHARED_DIR/scripts/browser_preflight.py" record \
  --mechanism <playwright-cli-or-agent-browser> --working-dir <project-root> \
  --checks <observed-checks.json> --evidence <captured-artifact> \
  --output <preflight.json>

アーティファクトが複数ある場合は、--evidenceを繰り返し指定します。ヘルパーは過去の観察結果を記録し、ドライバーのバージョンと識別情報を確認しますが、ジャーニーは実行しません。保存された{mechanism, preflight}オブジェクトを、verify --route <browser-route.json> --working-dir <project-root>で検証します。バージョン確認だけでは準備完了を確認できません。画像ペイロードとプライバシーの確認は、別途必要です。

ビジネステストを試行する枠を確保する前に、選択したドライバーを初期化します。実際の準備状況の結果を取得してください。ロックされたデスクトップは環境上のブロッカーであり、テストを実行したことにはなりません。アクセスが回復したら、承認済みの復旧許容範囲内で再開します。計画でサポートされ、許可されている場合にのみ、ヘッドレスのトランスポートを使用します。正確に承認されたフォールバックが適用されない限り、各ジャーニーでは選択したドライバーを使い続けます。ドライバーの復旧によって、元の実行予算が変更されることはありません。

この要件を満たす利用可能なドライバーがない場合は、SKIPで停止し、不足している機能を明記します。

2. 変更されたルートを特定する

明示的に指定された呼び出し元のベースと、承認済みソーススナップショットのベースがある場合は、まずそれらを再利用します。両方がある場合は、解決されたコミットと意図された比較範囲が一致していることを必須とします。不一致または指定されたベースを解決できない場合は、デフォルトを使用する理由ではなく、スコープ上のブロッカーとして扱います。どちらもない場合、PR ではコードホストのターゲットベースを使用します。それ以外のリクエストでは、ローカルの origin/HEAD、コードホストのメタデータ、次に main の順に解決します。選択した ref、解決されたコミット、選択元、指定されたスナップショット参照を、ブラウザーの証拠とともに実行レポートに記録します。ベースのメタデータは共有観測行に含めないでください。観測行のフィールドは id、result、evidence のままにします。リクエストされたブランチをそのベースと比較します。現在のワークツリーを対象とするリクエストでは、PR の差分が利用可能な場合でも、コミット済み、ステージ済み、未ステージの変更を含めます。それらの編集によって承認済みのソース範囲が変わる場合は、新しいスナップショットを準備します。

変更された各ファイルを、それを描画するルートに対応付けます。ディスパッチ前にプロジェクトのルーティングから実際の URL を特定してください。コンポーネント名からルートを推測しないでください。レイアウトや共有スタイルの変更では、少なくともルートページと、直接影響を受ける各ルートが必要です。ブラウザーに表示されるルートがない変更は、その理由とともに SKIP とします。

差分が空の場合は、そこで停止して SKIP とします。空のスコープを合格として報告しないでください。

3. ローカルサーバーに接続する

ポートは次の順に選択します。明示的な --port、有効なプロジェクトの手順、プロジェクトのサーバー設定、環境設定、次に 3000 です。

手動モードでは、選択したポートでリッスンしていることを確認します。リッスンしていない場合は停止して、ポート番号と未テストのルート数を明記し、文書化されたローカルサーバーのコマンドを起動するようユーザーに伝えます。

パイプラインモードでは、references/pipeline-orchestration.md のローカル手順を使用します。起動された実際のポートを記録します。

4. ルートをテストする

まずルートページを開きます。対応付けられたルートをテストする前に、サーバーが描画済みのコンテンツを返すことを確認します。

各ルートについて、新しい状態を取得し、次の点を確認します。

1. ページの見出しまたはタイトルが存在する。
2. 主要なコンテンツが描画される。
3. 目に見えるアプリケーションエラーや、新たなコンソールエラーがフローによって発生しない。
4. 差分がフォームまたはインタラクションに影響する場合、変更されたフォームまたはインタラクションが機能する。

現在のアクセシビリティ状態からターゲットを導きます。自動待機と観測可能なアサーションを備えた、ロール、ラベル、または安定したテスト ID のロケーターを優先します。編集する場合は、保存前にフィールドをクリアして、正確な値を読み戻します。遷移または再読み込みの前に、リクエストとレスポンスを記録します。再読み込み後に保存された値を確認します。サポートされているドライバーを使用して、安定した反復アクションをスクリプト化し、状態が変化するたびにアサーションを行います。視覚的な証拠と失敗の記録としてスクリーンショットを取得します。画像のバイト列をテキストとして返さないでください。

共有スナップショットの場合、必要な各フローを宣言された観測 ID に対応付け、上記の正確な観測行を記述します。ルートテーブルでフローを要約してもかまいませんが、その行の代わりにはなりません。その行は、ID を所有する検証単位のスコープ付きパケットに含めます。観測入力、実行時の ID、または必要なブラウザーコンテキストが変更された場合は、新しい観測が必要です。失敗またはスキップの理由を説明するキャプチャは証拠として保持します。後から再試行に合格しても、その証拠を消去しないでください。

OAuth、メール、支払い、SMS、またはその他の外部アクションでは、既存の明示的な許可を使用します。必要な許可または人間による操作が不足している場合は、手動モードでユーザーに確認します。パイプラインモードでは、影響を受けるルートのみを Skip とし、不足している操作を明記します。

5. 失敗を記録する

失敗ごとに、プロジェクトのテストポリシーに従って、ルート、再現手順、描画されたエラー、スクリーンショット、関連するコンソール出力、ネットワークの失敗、トレースを記録します。元の失敗と、その後の再試行で成功した結果の両方を保持してください。再試行しても、不安定な動作がなかったことにはなりません。独立したルートの確認を続けます。

このスキルの実行中にコードを変更しないでください。結果の報告後、修正の依頼は diagnose または現在進行中の実装ワークフローに引き継ぎます。既存のテストスイートに追加する価値のある、重要で安定したフローが見つかった場合は推奨してください。これらのテストの作成は、許可された実装または検証の範囲に含まれる作業です。

6. 報告する

次の表と結果を返してください。

ルート	ステータス	証拠	備考
/example	合格	描画された状態	主要なアクションが完了

実行したすべてのルートが成功した場合にのみ PASS を使用します。ルートが失敗した場合は FAIL を使用します。一部のルートが成功し、ほかのルートをスキップした場合は PARTIAL を使用します。ルートを一つも実行しなかった場合は SKIP を使用します。

選択したベースと解決済みコミット、テスト対象範囲、サーバー URL、選択したドライバー、コンソールエラー数、人間による確認事項、未テストのルートを明記してください。共有された各観察結果の行と、その証拠へのパスを表とともに返してください。ブラウザーの状態を記録していないルートを、合格したと報告してはいけません。

---

compound-engineering-plugin（MIT）を参考にしています。NOTICE を参照してください。