verify

検証

すべての変更には、実際に動かした証拠を添えます。ユニットテストが通っても、CLI が正しい行を出力すること、ロケーターが実際のページでノードを見つけること、エージェントのステップが再生できることの証拠にはなりません。テストベッドとベンチマークがここでのアプリです。これらは、ユーザーと同じ方法でビルド済みパッケージを使います。このスキルは最後だけでなく、作業の各段階で活用してください。変更し、ビルドし、実行し、確認して、繰り返します。

セットアップ

pnpm install --frozen-lockfile
pnpm --filter @e2e-dev/web exec playwright-core install chromium
pnpm build                    # every consumer below runs dist; rebuild after each change

古い dist が、誤った結果を招く最もよくある原因です。実行結果を信頼する前と、ブランチを切り替えた後には必ずビルドし直してください。

検証対象を選ぶ

変更内容	実行するもの	確認できること
Runner、collect、locator、config、sessions、CLI フラグ	テストベッドのテストスイート、または対象をカバーするファイル	決定論的なアプリ上で、ビルド済み CLI がエンドツーエンドで動作すること
レポーター（list、json、markdown、junit）	テストベッドのファイルと test:stress	攻撃的なタイトルも含む、出力とファイルへの書き込み
@e2e-dev/web	テストベッドのファイル、その後にウェブベンチマークの tests/	単純な画面と複雑な画面での実際の Chromium
エージェント（src/agent/）、プロンプト、trace cache	ウェブベンチマークの tests-agent/ による再生、その後に --no-cache --ai-trace	再生が引き続き成功し、ライブのエージェントが引き続き目標に到達すること
@e2e-dev/mobile	シミュレーターまたはエミュレーターでのモバイルベンチマーク	実機での動作。apps/mobile-benchmark を参照
e2e mcp	テストベッド上の e2e MCP サーバー	コーディングエージェントから見たツールの動作
e2e init、パッケージング、スキル	/tmp 配下のスクラッチプロジェクトに展開した tarball	新しいユーザーが npm から取得する内容
ドキュメントページ	pnpm docs:check	リンク、アンカー、例、パッケージマネージャーのタブ、ロゴ
@e2e-dev/github	PR 自体への e2e-github コメント	ユーザーの PR に表示されるコメント

コマンド（アプリのディレクトリから実行します。CLI に直接渡してください。pnpm run <script> -- --flag は -- を転送し、CLI がそのフラグをファイルとして読み込んでしまいます）。

cd apps/testbed && node node_modules/e2e/dist/cli/bin.js run tests/todos.e2e.ts
cd apps/web-benchmark && pnpm run build     # the Next.js app, once per scenario change
cd apps/web-benchmark && node node_modules/e2e/dist/cli/bin.js run tests/<scenario>.e2e.ts
cd apps/web-benchmark && node node_modules/e2e/dist/cli/bin.js run --config e2e.agent.config.ts
pnpm test:testbed && pnpm test:web-benchmark          # the whole gate, as CI runs it
pnpm --filter @e2e-dev/testbed test:scroll            # scroll_to by text, scripted; its own CI step

動作を確実に検証し続ける必要がある場合は、その動作の近くに決定論的なテストを追加してください。たとえば、runner の機能にはテストベッドのページとテストを、複雑な画面にはベンチマークのシナリオを用意します（シナリオの差分は最小限に保ち、仕込まれたバグは決して修正しないでください）。テストは利用側のスキルである skills/e2e に従います。このリポジトリは、その最初の利用者です。

エージェントを実行するには AI_GATEWAY_API_KEY が必要です。ベンチマークのエージェントテストスイートは、CI と同様に、コミット済みの記録を再生し、記録のないステップに限ってモデルを呼び出します。その場でモデル呼び出しが発生するステップがあれば、記録が古くなっています。変更対象がエージェントの場合に限り、--no-cache --ai-trace を付けてライブ実行してください。unbox-ai でトレースを読み取り（main とブランチを compare で比較）、決して直接開かないでください。再記録した項目は、同じ PR でコミットします（AGENTS.md の「Committed recordings」を参照）。

MCP サーバー

.mcp.json は、テストベッド上で e2e mcp を登録します。まず open_session を呼び出し、次に call {tool: "observe"}、locate、screenshot、各種アクション動詞を使います。ベンチマークでは、open_session に config: "../web-benchmark/e2e.config.ts" を渡してください。サーバープロセスは起動時の dist を実行します。ビルドし直した後は、MCP やエンジンの変更を通じて検証する前に、サーバーを再起動してください（Claude Code では /mcp）。複数のセッションを同時に開けます（--max-sessions のデフォルトは 4 です）。すべての呼び出しにセッション ID を渡し、使い終わったら close_session を呼び出してください。

ロケーターの作成（locate は screen.* の呼び出しを出力します）、テスト前の画面の確認、MCP ツール自体の変更の検証、エンジンが動画を記録する場合に操作内容を動画として記録するために使います（ウェブとモバイルの両方で対応しています）。画面の準備ができたら start_recording を呼び出し、ファイルパスを取得するには stop_recording を呼び出してください。

ユーザーのように操作する

• 単体テストのハーネスではなく、ビルド済みの CLI を実行します。出力内容と書き込まれるファイル（.e2e/report.json、.e2e/results/<test>/trace.md 内のトレースページ、.e2e/summary.md 用の --reporter list,markdown）を確認します。
• 失敗時の経路も試します。エラーコードの変更、タイムアウト、ポリシーによる拒否があれば、実際に発生させてユーザーに表示されるメッセージを確認します。
• 副作用を確認します。成果物がドキュメントの記載どおりの場所に作成されること、入力したシークレットが .e2e/ 内のどのファイルにも残らないことを確認します（値を grep -r で検索します）。
• APP_ALREADY_RUNNING は、別のチェックアウトで実行中の処理がアプリのポートを使用していることを意味します。終了するまで待つか、確認を求めてください。自分が起動していないプロセスは決して停止しないでください。
• モバイル：デバイスについては apps/mobile-benchmark/README.md に従います。1 台のデバイスにつき、同時に実行するのは 1 つまでです。

エビデンス

PR では動作を示す必要があります（writing-pr）。メディアを添えて、対象範囲、実行内容、確認した内容を報告します。

• ターミナル出力： CLI 出力の関連行を、フェンス付きの text ブロックに貼り付けます（ANSI エスケープを除去し、パスを短縮します）。これはランナー、CLI、レポーターの変更における主要なエビデンスです。
• 動画： --video を指定すると（動作を確認するには --headed を追加します）、動画を記録できるエンジン上で、すべての試行が .e2e/results/<test>/attempt-<n>/video/ に記録されます。@e2e-dev/web では video.webm、@e2e-dev/mobile では video.mp4 が作成されます。閲覧者が確認できるエンジン、ロケーター、エージェントの変更では動画を添付します。
• 静止画： 動画からフレームを切り出すか（ffmpeg -ss <seconds> -i <video> -frames:v 1 after.png）、ドキュメントのページをスクリーンショットします。
• バグ修正、main とブランチの比較： まず回帰テストを書き、チェックアウトがまだ main と同じ状態のときに実行して、失敗を記録します。すでにコードを変更している場合は、隣に main をビルドします。 git worktree add /tmp/e2e-main origin/main を実行し、その後、そこで pnpm install --frozen-lockfile && pnpm build を実行して、両方で同じコマンドを実行します。
• アップロード： gh pr create|edit --body-file body.md --attach ./after.png --attach ./video.webm （gh 2.99 以降）は各ファイルをアップロードし、本文内の Markdown 画像パスを書き換え、動画をプレーヤーとして追加します。古いバージョンの gh を使っている場合は、ブラウザーでファイルを PR にドラッグするか、メディアがローカルにあることとその理由を記載します。

検証できなかったことがあれば、その旨と妨げになった要因を明記します。エビデンスのない自信たっぷりな主張より、「結論は出ていない」と伝えるほうが適切です。

クリーンアップ

e2e run は起動したアプリを停止します。close_session は MCP セッションのアプリを停止します。作業が終わったら、git worktree remove で /tmp/e2e-main のワークツリーを削除します。