e2e

テストファイルは既定で tests/**/*.e2e.ts。フィクスチャとして app・agent・screen（Web では browser も）を受け取る。

// tests/checkout.e2e.ts
import { test, expect } from 'e2e';

test('a member upgrades to Pro', async ({ app, agent, screen }) => {
  await app.open('/settings/billing');

  await agent.act('upgrade the workspace to the Pro plan');
  await agent.assert('the invoice preview shows a prorated amount');

  await expect(screen.getByRole('status')).toContainText('Pro');
});

targets が必須。UI のターゲットはエンジンとテスト対象アプリを並べて宣言する。アプリの起動コマンドも設定に書けるので、ランナーが開発サーバーを立ち上げてからテストを流す。各テストはターゲットごとに 1 回ずつ実行される。

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' },
      },
    },
  ],
  // agent.* ステップに使うモデル（AI SDK のインスタンス）
  agents: {
    default: {
      model: gateway('openai/gpt-6-luna-fast'),
      system: 'You are a thorough QA agent. Verify every outcome on screen.',
    },
  },
} satisfies E2EConfig;

モバイルは mobile({ platform: 'ios' }) のようにエンジンを差し替え、app に bundleId を指定する。テストは Web と同じ agent / screen / expect API で書ける。セットアップは npx e2e init がエンジン（Web かモバイル）とモデルプロバイダを尋ね、設定とサンプルテストを生成する。

エンジンは自作もできる（公式ドキュメントの「Writing an engine」）。完成済みのセットアップ例は examples/ に Vite、Next.js、Expo、SwiftUI の 4 本がある。

エージェントステップは agent.act / assert / waitFor / extract の 1 呼び出し。ランナーがマスキング、アクションの許可、予算、シークレット、レポートを受け持ち、エグゼキュータ（既定は組み込みエージェント）がどのアクションを要求するか決めて判定を返す。

ループは同じ呼び出しの繰り返しを検出する。3 回続けてアクションが失敗するとアプローチの変更を求め、5 回で判定を求める。ターゲット指定のアクションのタイムアウトは最大 15 秒。

コストを決める要因

• assert と extract は 1 回の判定（応答が壊れていれば修復呼び出しが 1 回追加）。
• waitFor は画面が変わらない間はモデルを呼ばない。
• スクリーンショットは載せた呼び出しごとに入力トークンを増やす。
• 合格した act はリプレイキャッシュでモデル呼び出しなしに再実行される。

エントリはテスト、ターゲット、指示、params、エージェントの組に属する。次の変更はミスになる。

• テスト名・ターゲット名の変更、指示や通常の param の変更
• 別のエージェントでの実行、エージェントの context やテストの agentContext の変更
• エンジンのメジャー / マイナーバージョンの更新

モデルの変更ではミスにならない。タイムスタンプや毎回新しいメールアドレスは unique() で包むと、再生時に現在の値へ差し替えられる。キャッシュを疑うときは npx e2e run --no-cache で一度切り分ける。

テストファイルを書かずにゴールだけを渡すと、エージェントが自分でステップを計画してアプリを操作し、気づいた点（期待、実際、再現手順、可能ならスクリーンショット）を .e2e/report.json に記録する。agent.act() と同じモデル、ツール、アクション規則を使う。

npx e2e explore 'Explore the checkout flow like a first-time buyer and report anything off'

issue は機能上の不具合で実行を失敗させ、warning は見た目の問題で失敗させない。失敗または blocked のステップが新しい指摘なしに 3 回続くと探索を終える。

リポジトリには skills/e2e/SKILL.md があり、トピック別の参照ファイルを持つ。インストール済みの CLI は同じ内容を npx e2e guide <topic> で表示する。

プロジェクトのライブアプリを stdio の MCP サーバーとしてコーディングエージェントに公開する。テストを書く前に画面を見て、ロケータが一意に当たるかを確かめるための仕組み。テストの実行と失敗の読解は CLI 側で行う。ai パッケージがなくても決定的なツールは動く。

claude mcp add e2e -- npx e2e mcp   # Claude Code

カタログの locate は role / text / label / placeholder / testId のいずれか 1 つでロケータを試し、一致数と、テストに書くべき screen.* 呼び出しを返す。同時セッション数は既定 4（--max-sessions で 1〜16）。

npx e2e init [directory]          # エンジンとモデルを選んで設定とサンプルを生成
npx e2e login [provider]          # モデルプロバイダのサブスクリプションにサインイン
npx e2e models [provider]
npx e2e guide [topic]             # スキルのトピックを表示
npx e2e mcp [options]
npx e2e run [files...] [options]  # --headed / --debug / --ai-trace / --no-cache など
npx e2e explore [goal] [options]
npx e2e list [files...] [options]
npx e2e cache ls|clear|stats
npx e2e feedback -m <text> [options]
npx e2e telemetry [status|enable|disable]

CLI は Node.js 24.8 以降（22 系なら 22.22.3 以降）で動く。npm、pnpm、Yarn、Bun のどれでもインストールできるが、実行ランタイムは Node.js（bunx e2e も Node.js 上で動く）。

複数の結果が混ざった実行では 130 > 4 > 3 > 2 > 1 > 0 の優先順で終了コードが決まる。個々の結果は .e2e/report.json に残る。.e2e/（report.json、artifacts/、cache/、logs/）は出力専用で、読むが編集しない。

テストコードにシークレットを書かない。アカウントは設定の credentials、その他の値は secrets に宣言し、credentials.user(name).password や secrets.get(name) で不透明な Secret を受け取る。Secret を渡せるのは fill() と agent.act の params だけ。

• モデルが受け取るのはシークレットの名前と用途だけ。ランナーがモデルの選んだフィールドを検査してから値を入力する。
• 画面上に現れた既知のシークレット値は <secret:name> に、セキュアフィールドは value=<secure> に置き換えられる。
• シークレットを入力したあとは、その試行の間スクリーンショットをモデルに送らない。

アプリの内容がツール、認証情報、予算を与えることはできない。ランナーはモデルのテキストをコード、セレクタ、シェルコマンド、設定として評価しない。

• GitHub: tester-army/e2e — モノレポ（packages / examples / skills / docs）
• e2e ドキュメント — Quickstart、Goals、Caching agent steps、Security など
• Quickstart — npx e2e init からの導入手順
• examples/ — Vite、Next.js、Expo、SwiftUI の独立したサンプル
• npm: e2e
• callstack/agent-device — モバイルエンジンの基盤