e2e

e2e：エージェント型エンドツーエンドテスト

e2e は、エージェントの目標と厳密なステップを組み合わせた UI テストを実行します。agent.act は 1 つの目標を実行し、agent.assert、agent.waitFor、agent.extract は画面を判定します。screen、app、browser、expect は正確な操作と確認を行います。UI ターゲットには、ブラウザー用の @e2e-dev/web、または iOS シミュレーター、Android エミュレーター、接続済みのスマートフォン用の @e2e-dev/mobile を使います。

まずはこちら：作業に合ったリファレンスを選ぶ

何かを始める前に、依頼に合ったリファレンスを 1 つ読んでください。それぞれ単独で読める内容になっています。別のトピックへの言及がある場合は、補足情報への案内です。npx e2e guide <topic> を実行すると、インストール済みパッケージのリファレンスが表示されます。このコピーと異なる場合は、そちらを優先してください。 以下の「ルール」と「フィードバック」のセクションも適用されます。

次のような作業の場合	トピック	読むもの
プロジェクトへの e2e の追加、e2e.config.ts の作成、設定ファイルからのアプリの起動、モデルへのサインイン、モバイルターゲットのセットアップ	setup	references/setup.md
実行中のアプリの確認、UI の変更のチェック、スクリーンショットや動画の撮影、ロケーターの試用、またはテストを書きながらのフローの確認（e2e mcp を使用）	mcp	references/mcp.md
テストの作成や修正：フィクスチャ、ロケーター、操作、マッチャー、サインインセッション、browser フィクスチャ、API のみのテスト	writing-tests	references/writing-tests.md
agent.* ステップの追加、モデルの選択、コスト削減、予算、リプレイキャッシュ	agent	references/agent.md
テストの実行：CLI フラグ、CI、レポーター、トレースページ、スクリプト用の report.json、終了コード	running	references/running.md
実行失敗への対処：エラーコードと修正方法、--headed、--debug、--ai-trace	debugging	references/debugging.md
テストファイルを使わずに目標に向けてアプリを調べる：e2e explore、その予算と判定結果	explore	references/explore.md
アプリやブランチ全体のバグバッシュ、QA、バグ探しを依頼された場合	bug-bash	references/bug-bash.md

リファレンスに記載されていない内容については、完全なドキュメントがインストール済みの e2e パッケージの docs/ ディレクトリにあります（単一パッケージのプロジェクトでは node_modules/e2e/docs）。たとえば、/reference/cli は docs/reference/cli.mdx にあります。Vite、Next.js、Astro、Angular、Expo、SwiftUI、Jetpack Compose、Kotlin Multiplatform、Flutter、.NET MAUI の完全なプロジェクトは https://github.com/tester-army/e2e/tree/main/examples にあります。

クイックスタート

Web ターゲットとモデルを 1 つずつ設定した構成、および 1 つの目標を実行して結果を固定するテスト：

// e2e.config.ts
import type { E2EConfig } from 'e2e';
import { web } from '@e2e-dev/web';
import { gateway } from 'ai';

export default {
  targets: [
    {
      engine: web(),
      app: {
        url: 'http://127.0.0.1:3000',
        command: { executable: 'pnpm', args: ['dev'], log: '.e2e/logs/app.log' },
      },
    },
  ],
  // The model behind every agent.* step: an AI SDK instance; gateway() from 'ai' reads AI_GATEWAY_API_KEY or a Vercel OIDC token.
  agents: {
    default: {
      model: gateway('openai/gpt-6-luna-fast'),
      system: 'You are a thorough QA agent. Verify every outcome on screen.',
    },
  },
} satisfies E2EConfig;

// tests/billing.e2e.ts
import { test } from '@e2e-dev/web';
import { expect } from 'e2e';

test('a member upgrades to Pro', async ({ app, agent, screen, browser }) => {
  await app.open('/settings/billing');
  await agent.act('upgrade the workspace to the Pro plan');
  await expect(screen.getByRole('status')).toContainText('Pro');
  await expect(browser).toHaveURL('/settings/billing');
});

ワークフロー：テストの作成

1. 既存の設定を確認します。e2e.config.ts、.mts、.js、または .mjs、tests の glob（デフォルトは tests/**/*.e2e.ts）、package.json の e2e を確認してください。何もない場合、ユーザーが e2e をリクエストしているときは setup に従ってください（Rules を参照）。
2. e2e mcp サーバー（トピック mcp）に接続した状態で、フローを進めながらテストを書きます。進めた後に記憶を頼りに書くのではありません。後から書くと、名前や手順を間違えるたびに、実行のたびに失敗します。open_session の前に tests/<feature>.e2e.ts を作成し、対象画面からテストを開始します（手順 3）。セッションで進めるたびに、各手順をファイルに追加します。act の目標は、その経路を進む前に記述し、その経路のアクションはテストに含めません。screen の行には、アクションが出力した Test line: をそのままコピーします。結果が表示されたら、locate して expect を追加します。テストを書き終えたら、画面の確認は終了です。サーバーがない場合は、コンポーネントまたは --headed での実行から、アプリが描画するアクセシブルな名前を確認します。
3. 手順とは、agent.act の目標または screen の行です。agent.act でフローを進め、呼び出しごとに原子的な目標を 1 つだけ指定し、それぞれの結果を直後に expect または agent.assert で固定します。目標が 3 つあるテストでは、3 回呼び出します。各再実行では前の手順にも時間がかかるため、テストは対象画面から開始します。ブラウザーの場合は、サインインフォームの代わりに保存済みセッションを使用して、その画面のパスで app.open を実行します。デバイスの場合は device.openLink を使用し、データはアプリの API から取得します（トピック writing-tests）。正確な値は screen で確認します。セットアップテストのサインインフォーム、特定の文字列を受け取る必要があるフィールド、1 つの数値でなければならない件数などが該当します。
4. 作業中のテストだけを実行します。 npx e2e run tests/<feature>.e2e.ts:<line> を実行します。<line> は test( が始まる行です。下記の「修正中にテストを再実行する」のフラグを指定してください。エージェントの手順には、設定内のモデルと、そのプロバイダーの認証（保存済みのサブスクリプションログイン、API キー）が必要です。ローカルのエンドポイントでは不要な場合があります。エージェントの手順がないテストにはモデルは必要ありません。
5. 失敗したら、実行で記録された内容をもとに修正します（次のセクションを参照）。

ワークフロー：失敗したテストの修正

実行では、失敗するまでのすべての画面をすでに確認しています。記録された内容をもとに修正してください。画面を確認するためだけに、MCP でフローを最初からやり直してはいけません。

1. ターミナルの失敗ブロックを読みます。失敗した行とそのコードフレーム、メッセージ（アサーションの expected と observed）、画面の場所（❯ at：ウェブ上の URL、デバイス上のアプリ名と画面タイトル）、失敗したロケーターに最も近いノード（❯ on screen）を確認します。次に、指定されたトレースページ（❯ trace .e2e/results/<test>/trace.md）を読みます。各手順の実行内容、アプリのログ、エージェントのターン、そして失敗時の画面をノードごとに 1 行で示した ## Screen at failure が記録されています（トピック debugging）。
2. 証拠で確認できる行は、失敗した行だけでなくすべて修正します。失敗時の画面から、同じ画面のほかの行に必要な名前も確認できます。ロケーター、期待値、またはアプリを修正します。スリープや固定の遅延（setTimeout、waitForTimeout）を追加してはいけません。代わりに agent.waitFor('<that state>') で必要な状態を待ちます（トピック agent。モデルが必要です）。
3. テストは最初に失敗した手順で停止します（expect.soft を使うと続行します）。その後に間違った行があるたびに、再実行がもう 1 回必要になります。再実行する前に、失敗時の画面、アプリのソース、またはライブセッションを使って、確認できる範囲で後続の行も確認してください。
4. 証拠とソースで確認できない画面は、ライブで確認します（トピック mcp）。セッションを開くか再利用し、対象画面に直接移動してから、observe と locate を実行します。ウェブの場合は、❯ at の URL または画面のルートに navigate し、URL から開けない状態にたどり着く場合にだけタップします。デバイスのセッションはアプリの起動画面から始まるため、そこから最短の経路をたどります。
5. 次のセクションの説明に従って、そのテストだけを再実行します（セッションを先に閉じる必要がある場合は、トピック mcp に記載されています）。次の失敗についても同様に繰り返します。

修正中のテストを再実行する

失敗するテストを実行するたびに、失敗が確定するまで待つ必要があり、ライブ実行される agent.act は実行のたびにモデル呼び出しを消費します。再実行の対象は、テスト1件と変更した行だけにしてください。

• ファイル全体やテストスイートではなく、file:line で実行します。テストより上の行を編集した後は、テストの test( 行をもう一度確認してください。古い行番号を使うと別のテストが実行されたり、 テストの開始行が一覧表示される NO_TESTS で失敗したりします。
• --action-timeout 5000 を追加します。何も見つからないロケーターは、デフォルトの30秒ではなく5秒で失敗します。また、エージェントの各ステップ内のアクションにも上限時間を設定するため、画面の読み込みにかかる最長時間より長くしてください。screen 呼び出し独自の { timeout } がある場合は、そちらが優先されます。expect はデフォルトで5秒後にすでにタイムアウトします（assertionTimeout）。
• リプレイキャッシュは有効にしたままにします。失敗した実行では、チェックに合格したすべてのゴールの記録が保持され、次の実行ではモデルを呼び出さずにそれらをリプレイします。新しいゴール、変更されたゴール、失敗したゴールはライブで実行され、トレースページに引き継ぎ済みと表示されるリプレイも同様です。agent.assert、agent.waitFor、agent.extract は常にモデルを呼び出します。--no-cache は指定しないでください。すべてのゴールが再びモデルに送られます。記録を保存するのは read-write キャッシュだけです。これはローカルでのデフォルトですが、CI が設定されていて設定ファイルにキャッシュモードが指定されていない場合や、厳密モードでは保存されません。停止した実行（Ctrl-C、ツールのタイムアウトによって強制終了されたコマンド、--max-duration）では何も保存されないため、コマンドのタイムアウトはテストより長く設定してください。
• テスト名、describe、ファイルの名前は変更しないでください。また、ゴールの言い回しやパラメーターを変更したり、ゴールが合格した後にエージェントの context やテストの agentContext を変更したりしないでください。これらはそれぞれ記録のキーの一部なので、影響を受けるゴールはすべて再びライブで記録されます。ロケーターやアサーションを修正しても、記録は維持されます。
• リトライが有効な場合は、--retries 0 を追加します（設定ファイルの retries、または CI が設定されている場合はデフォルトの1が該当します）。テストまたはその describe に retries オプションがある場合は、フラグよりそちらが優先されます。厳密モード（--strict-cache、cache.strict）以外では、リトライ時にリプレイは行われません。すべてのゴールがライブで実行され、失敗が確定するまで再び待つことになります。
• テストに合格したら、--action-timeout を外し、--no-cache を付けて1回実行します。すべてのゴールが設定のタイムアウトでライブ実行され、記録なしでもエージェントがテストに到達できることを確認できます。

ルール

• プロジェクトに e2e がない場合、ユーザーから依頼されたときはセットアップします。それ以外の場合は、テストフレームワークを追加する前に確認し、既存のフレームワークがあれば名前を伝えます。
• 実際に動作する MCP ツールを使うには、プロジェクト独自の e2e mcp サーバーをクライアントに登録する必要があります（トピック mcp）。テストの作成と実行には CLI を直接使います。Web テストを作成または修正する間は、実行の合間もセッションを開いたままにします。トピック mcp には、セッションと並行して実行できるタイミングと、APP_ALREADY_RUNNING が発生した場合の対処法が記載されています。
• CLI は npx e2e ...（または pnpm exec e2e ...）として実行します。
• 設定は import type { E2EConfig } from 'e2e' と export default { ... } satisfies E2EConfig です。targets は必須です。UI ターゲットではエンジンを指定し、その隣にアプリを宣言します：{ engine: web(), app: { url, command } }。ツールのみのターゲットではエンジンを省略し、platform を設定できます。
• test、describe、フック、expect、credentials、secrets は e2e からインポートします。browser フィクスチャを使うテストでは、test、describe、フックを @e2e-dev/web からインポートします。これらは同じ実行時関数ですが、browser の型が付与されています。
• package.json で type に何が設定されていても、設定とテストは ES モジュールです。
• ロケーターは使用時に解決されます。アクションは準備が整うまで待機し、expect はアサーションを再試行します。textContent() などの読み取りでは、アクションのタイムアウトまで一致する要素を待ってから、現在の値を返します。count() と isVisible() は現在の画面に基づいて値を返します。値が変わるまで待機する処理はないため、値が確定する必要がある場合はマッチャーを使います。
• ロケーターが 2 つのノードに一致すると、LOCATOR_AMBIGUOUS エラーになります。絞り込んでください（トピック writing-tests）。
• シークレットをテストコードに記述することはありません。アカウントは設定の credentials に、それ以外の機密情報はすべて secrets に宣言します。credentials.user(name).password または secrets.get(name) で取得します（名前空間は別々です。secrets.get がパスワードを返すことはありません）。不透明な Secret は fill() または agent.act のパラメーターにのみ渡します。
• エージェントへの指示：act ごとに目標を 1 つにし、画面上の表現を使い、パラメーターには実際の値を指定します。目標は単一の成果であり、1 つのチェックで確認できる必要があります。確認する価値のある成果が 2 つある場合は目標を 2 つに分け、act を 2 回呼び出します（トピック agent）。悪い例：'add a todo and mark it done'。良い例：'add a todo' を実行して確認し、続けて 'mark the todo as done' を実行して確認します。表現ではなく意味を判定します。モデルが生成した文と完全一致させるのではなく、toContain('Pro') を使います。
• 各エージェントの目標の成果を確認します。チェックを記録した act が成功するとキャッシュされ、モデルを呼び出さずに再生できます（トピック agent）。
• このアプリに合わせてエージェントを調整します。画面で使われる語彙は context に、仕組みは system に、テスト API はツールに設定し、名前付きペルソナは agents の下に配置します。ステップが失敗したら、まず目標を明確にし、次にコンテキストを見直し、それからエージェントを調整します。
• .e2e/ は出力先です（report.json、results/、cache/、logs/。設定の output を変更すると、レポートと成果物の保存先が変わりますが、cache/ やアプリのログの保存先は変わりません）。内容は読み取りますが、編集はしません。

フィードバック

e2e 自体が作業の妨げになった場合は、e2e チームへの報告を提案してください。動作しなかったコマンドや API（bug）、誤解を招いたドキュメントやこのスキル（docs）、必要だったものの見つからなかった機能（feature）が対象です。問題ごとに、回避策を見つけた後、または諦めた後に一度だけ報告してください。次の内容は報告しないでください。

• テスト対象のアプリの不具合や、そのアプリ自体の動作。
• 一度だけ発生し、再現できなかった問題。
• 古い e2e に関する問題。コマンドは古いバージョンを拒否するため、アップグレードし（npx e2e@latest upgrade）、まず問題が引き続き発生することを確認してください。

まず既存のイシューを検索してください （gh issue list -R tester-army/e2e --search "<words>"）。該当するものがあれば、新しい報告を送らずに、そのイシューにコメントしてください。

bug を報告するには、アプリの内容に依存せず、毎回問題を再現できる手順を --repro で指定する必要があります。そうした手順がない場合、またはアプリを表示しないと再現できない場合は、--repro を省略してください。その場合、コマンドは入力済みの GitHub イシューを表示するだけで、何も送信しません。ユーザーにリンクを示し、最小限の再現例を追加して送信するよう伝えてください。イシューを自分で作成してはいけません。

まず --dry-run を付けて実行し、送信される内容をユーザーに示してください。ユーザーが同意した場合にのみ送信します。

npx e2e feedback --type bug -m "<one or two sentences>" \
  --repro "<steps that reproduce it every time>" --error-code LOCATOR_AMBIGUOUS \
  --task "<what you were doing>" --expected "<...>" --actual "<error message>" \
  --approach "<what you tried>" --command "<e2e command>" --agent "<agent / model>"

e2e の動作だけを簡潔に説明してください。アプリの内容、ページ上のテキスト、テストファイル、非公開アプリの URL、認証情報は決して貼り付けないでください。シークレットを名前に含む環境変数と、一般的なトークン形式はマスキングされますが、それに頼ってはいけません。送信後、表示された参照 ID をユーザーに伝えてください。