Matware E2e Runner

Docker プールでは Chrome がコンテナ内で動作するため、コンテナ内の localhost はお使いのマシンではなく、コンテナを指します。host.docker.internal を使うとホストに接続できます。Linux（Docker Desktop ではなく Docker Engine）の場合は、--add-host=host.docker.internal:host-gateway を追加するか、LAN IP を使用してください。オプション 1 と 2 ではこの設定は不要です。ブラウザーはローカルで動作するため、通常の localhost をそのまま使用できます。

cp node_modules/@matware/e2e-runner/opencode.json ./
mkdir -p .opencode && cp -r node_modules/@matware/e2e-runner/.opencode/* .opencode/

詳細については、OPENCODE.md を参照してください。

e2e/tests/ 内の各 .json ファイルには、テストの配列が含まれます。各テストには name と、順番に実行される actions があります。

[
  {
    "name": "homepage-loads",
    "actions": [
      { "type": "goto", "value": "/" },
      { "type": "assert_visible", "selector": "body" },
      { "type": "assert_url", "value": "/" },
      { "type": "screenshot", "value": "homepage.png" }
    ]
  }
]

順序を指定するために、スイートファイルに数値の接頭辞を付けることができます（01-auth.json、02-dashboard.json）。--suite フラグは接頭辞の有無を問わず一致するため、--suite auth で 01-auth.json が見つかります。

テキストでクリック — click で selector の代わりに text を使うと、一般的なインタラクティブ要素やコンテンツ要素を横断して検索します。

button, a, [role="button"], [role="tab"], [role="menuitem"], [role="option"],
[role="listitem"], div[class*="cursor"], span, li, td, th, label, p, h1-h6

{ "type": "click", "text": "Sign In" }

これらのアクションは、通常は冗長な evaluate の定型コードが必要となる React/MUI アプリの一般的なパターンに対応します。

// Before: 5 lines of evaluate boilerplate
{ "type": "evaluate", "value": "const input = document.querySelector('#search'); const nativeSet = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set; nativeSet.call(input, 'term'); input.dispatchEvent(new Event('input', {bubbles: true})); input.dispatchEvent(new Event('change', {bubbles: true}));" }

// After: 1 action
{ "type": "type_react", "selector": "#search", "value": "term" }

以降のすべてのアクションは、アクティブなタブで実行されます。

{ "type": "click", "text": "Open report" }
{ "type": "wait_for_tab", "text": "report" }
{ "type": "assert_text", "text": "Quarterly results" }
{ "type": "close_tab" }

テスト単位の再試行 — テスト全体を失敗時に再試行します。設定ファイルで全体に設定するか、テストごとに設定します。

{ "name": "flaky-test", "retries": 3, "timeout": 15000, "actions": [...] }

再試行後に成功したテストは、レポートと学習システムで不安定としてフラグ付けされます。

アクション単位の再試行 — テスト全体を再実行せずに、単一のアクションを再試行します。タイミングに左右されるクリックや待機に便利です。

{ "type": "click", "selector": "#dynamic-btn", "retries": 3 }
{ "type": "wait", "selector": ".lazy-loaded", "retries": 2 }

全体に設定するには、設定ファイルの actionRetries、CLI の --action-retries <n>、または環境変数の ACTION_RETRIES を使います。再試行間の遅延は actionRetryDelay で設定します（デフォルトは 500ms）。

状態を共有するテスト（たとえば、同じレコードを変更する 2 つのテスト）は、並列実行時に競合する可能性があります。シリアルとして指定します。

{ "name": "create-patient", "serial": true, "actions": [...] }
{ "name": "verify-patient-list", "serial": true, "actions": [...] }

シリアルテストは、すべての並列テストの完了後に一度に 1 つずつ実行されます。これにより、独立したテストの実行を遅くすることなく、干渉を防げます。

最も簡単な方法は、実際のユーザーと同じように UI からログインすることです。

{
  "hooks": {
    "beforeEach": [
      { "type": "goto", "value": "/login" },
      { "type": "type", "selector": "#email", "value": "[email protected]" },
      { "type": "type", "selector": "#password", "value": "test-password" },
      { "type": "click", "text": "Sign In" },
      { "type": "wait", "selector": ".dashboard" }
    ]
  },
  "tests": [...]
}

{ "type": "set_storage", "value": "accessToken=eyJhbGciOiJIUzI1NiIs..." }

または、設定ファイルでグローバルに設定します。

// e2e.config.js
export default {
  authToken: 'eyJhbGciOiJIUzI1NiIs...',
  authStorageKey: 'accessToken',
};

各テストは新しいブラウザーコンテキストで実行されるため、テスト間で認証状態は自動的にクリーンになります。

その他の方法： Cookie ベースの認証、HTTP ヘッダーの注入、OAuth／SSO のバイパス、再利用可能な認証モジュール、ロールベースのテストについては、docs/authentication.md をご覧ください。

共通のフローをパラメーター化されたモジュールに抽出します。

// e2e/modules/login.json
{
  "$module": "login",
  "description": "Log in via the UI login form",
  "params": {
    "email": { "required": true, "description": "User email" },
    "password": { "required": true, "description": "User password" }
  },
  "actions": [
    { "type": "goto", "value": "/login" },
    { "type": "type", "selector": "#email", "value": "{{email}}" },
    { "type": "type", "selector": "#password", "value": "{{password}}" },
    { "type": "click", "text": "Sign In" },
    { "type": "wait", "value": "2000" }
  ]
}

テストで使用します。

{
  "name": "dashboard-loads",
  "actions": [
    { "$use": "login", "params": { "email": "[email protected]", "password": "secret" } },
    { "type": "assert_text", "text": "Dashboard" }
  ]
}

モジュールは、パラメーターの検証（必須パラメーターがない場合は即座に失敗）、条件付きブロック（{{#param}}...{{/param}}）、ネストした合成、循環参照の検出をサポートしています。

ライフサイクルの各タイミングでアクションを実行します。設定ファイルまたは各スイートで定義できます。

{
  "hooks": {
    "beforeAll": [{ "type": "goto", "value": "/setup" }],
    "beforeEach": [{ "type": "goto", "value": "/" }],
    "afterEach": [{ "type": "screenshot", "value": "after.png" }],
    "afterAll": []
  },
  "tests": [...]
}

重要： beforeAll は別のブラウザーページで実行され、テスト開始前にそのページは閉じられます。テストで必要な状態（Cookie、localStorage、認証トークン）には beforeEach を使用してください。

探索用または下書きのテストを --all の実行から除外します。

// e2e.config.js
export default {
  exclude: ['explore-*', 'debug-*', 'draft-*'],
};

個別のスイート実行（--suite）は、除外パターンの影響を受けません。

claude plugin marketplace add fastslack/mtw-e2e-runner
claude plugin install e2e-runner@matware

Claude Code に 17 個の MCP ツール、ワークフロースキル、4 つのスラッシュコマンド（/e2e-runner:run、/e2e-runner:create-test、/e2e-runner:verify-issue、/e2e-runner:capture）、3 つの特化型エージェント（test-analyzer、test-creator、test-improver）が追加されます。

MCP のみのインストール（ツールのみ。スキル、コマンド、エージェントは含まれません）：

claude mcp add --transport stdio --scope user e2e-runner \
  -- npx -y -p @matware/e2e-runner e2e-runner-mcp

cp node_modules/@matware/e2e-runner/opencode.json ./
mkdir -p .opencode && cp -r node_modules/@matware/e2e-runner/.opencode/* .opencode/

詳細は OPENCODE.md を参照してください。

プールの起動／停止は CLI 専用です。MCP では公開されていません。

ページの見た目を説明すると、AI がスクリーンショットから合否を判定します：

{
  "name": "dashboard-loads",
  "expect": "Patient list with at least 3 rows, no error messages, sidebar with navigation links",
  "actions": [
    { "type": "goto", "value": "/dashboard" },
    { "type": "wait", "selector": ".patient-list" }
  ]
}

テストアクションの完了後、ランナーが検証用スクリーンショットを自動で撮影します。MCP の応答にはスクリーンショットのハッシュが含まれ、Claude Code がこれを取得して、expect の説明と照らし合わせて視覚的に検証します。API キーは不要です。

GitHub と GitLab のイシューを実行可能な E2E テストに変換します。イシューの URL を貼り付けるだけで、実行可能なテストを自動で作成できます。

仕組み：

1. 取得 — gh または glab CLI を使って、イシューの詳細（タイトル、本文、ラベル）を取得します
2. 生成 — AI がイシューの説明に基づいて JSON テストアクションを作成します
3. 実行 — 必要に応じてテストをすぐに実行し、バグが再現するかどうかを検証します

# Fetch and display
e2e-runner issue https://github.com/owner/repo/issues/42

# Generate a test file via Claude API
e2e-runner issue https://github.com/owner/repo/issues/42 --generate

# Generate + run + report
e2e-runner issue https://github.com/owner/repo/issues/42 --verify
# -> "BUG CONFIRMED" or "NOT REPRODUCIBLE"

Claude Code では、次のように依頼するだけです：

「イシュー #42 を取得して、E2E テストを作成してください」

バグ検証の仕組み： 生成されたテストは正しい動作を検証します。テストが失敗した場合は、バグが確認されたことを意味します。すべてのテストに合格した場合は、再現できなかったことを意味します。

認証： GitHub には gh CLI、GitLab には glab CLI が必要です。セルフホスト型 GitLab にも対応しています。

ライブ実行 — ステップごとの進捗、所要時間、稼働中のワーカー数を確認しながら、テストをリアルタイムで監視できます。

テストスイート — プロジェクト全体のすべてのスイートを閲覧できます。ワンクリックで単一のスイート、またはすべてのテストを実行できます。

実行詳細 — PASS/FAIL バッジ、コピー可能なハッシュ（ss:77c28b5a）付きのスクリーンショットサムネイル、整形されたコンソールエラー、ネットワークリクエストログを表示します。

スクリーンショットギャラリー — ハッシュ検索で、キャプチャしたすべてのスクリーンショット（アクション、エラー、検証時のキャプチャ）を閲覧できます。

プールのステータス — Chrome プールの稼働状況（利用可能なスロット、実行中のセッション、メモリ負荷）を確認できます。

ランナーはテストを実行するたびに学習し、時間の経過とともにテストスイートに関するナレッジを構築します。e2e_learnings MCP ツールでインサイトを照会できます。

ストレージとエクスポート：

• SQLite（~/.e2e-runner/dashboard.db）— デフォルト。セットアップ不要
• Neo4j ナレッジグラフ — 任意。関係に基づく分析向け。e2e_neo4j MCP ツールまたは docker compose で管理できます
• Markdown レポート（e2e/learnings.md）— 各実行後に自動生成

テストのナレーション： 各テストの実行時に、発生した内容を手順ごとに説明する、人が読みやすい形式のナラティブを生成します。CLI 出力とダッシュボードで確認できます。

明示的なアサーション — 重要なページの読み込み後に assert_no_network_errors を配置します。

{ "type": "goto", "value": "/dashboard" },
{ "type": "wait", "selector": ".loaded" },
{ "type": "assert_no_network_errors" }

グローバルフラグ — failOnNetworkError: true を設定すると、ネットワークエラーが発生したテストは自動的に失敗します。

e2e-runner run --all --fail-on-network-error

無効の場合（デフォルト）、ランナーはネットワークエラーを収集して報告します。テストが合格してもネットワークエラーがある場合、MCP のレスポンスに警告が含まれます。

詳細なネットワークログ — すべての XHR/fetch リクエストをキャプチャし、URL、メソッド、ステータス、所要時間、リクエスト／レスポンスヘッダー、レスポンス本文（50KB で切り詰め）を記録します。ダッシュボードで、リクエストの詳細行を展開して確認できます。

MCP の詳細確認フロー：

1. e2e_run          → compact networkSummary + runDbId
2. e2e_network_logs(runDbId)                     → all requests (url, method, status, duration)
3. e2e_network_logs(runDbId, errorsOnly: true)   → only failed requests
4. e2e_network_logs(runDbId, includeHeaders: true) → with headers
5. e2e_network_logs(runDbId, includeBodies: true)  → full request/response bodies

キャプチャしたリクエスト数にかかわらず、e2e_run のレスポンスはコンパクト（約 5KB）に保たれます。返された runDbId を e2e_network_logs で使用すると、必要に応じて詳細を確認できます。

テストスイートを用意せずに、任意の URL のスクリーンショットをオンデマンドで撮影できます。

e2e-runner capture https://example.com
e2e-runner capture https://example.com --full-page --selector ".loaded" --delay 2000

MCP 経由では、e2e_capture ツールで authToken と authStorageKey を指定して、認証が必要なページに対応できます。ページに移動する前に、トークンを localStorage に注入します。

{
  "tests": [
    {
      "name": "checkout flow (heavy JS, real Chrome)",
      "driver": "browserless",
      "actions": [...]
    },
    {
      "name": "scrape product page (lightweight)",
      "driver": "obscura",
      "fallbackDriver": "cdp",
      "actions": [...]
    }
  ]
}

driver は省略可能です。設定すると、検出されたドライバーが一致するプールのみが候補になります。fallbackDriver は明示的なオプトインです。指定しない場合、対象ドライバーが見つからないと、明確なメッセージとともにテストが失敗します。プールの混雑を理由にフォールバックすることはありません。ランナーはフィルター後の候補内で待機します。

実行全体でドライバーを固定します（CLI の設定はテストごとの設定より優先されます。A/B ベンチマークに便利です）。

e2e-runner run --all --driver obscura
e2e-runner run --all --driver obscura --fallback-driver cdp

# browserless (default) — managed by `pool start`
e2e-runner pool start

# Lightpanda — pool start uses templates/docker-compose-lightpanda.yml
e2e-runner pool start                 # with poolDriver: 'lightpanda' in config

# Obscura — install the binary and run it yourself
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-linux.tar.gz
tar xzf obscura-x86_64-linux.tar.gz
./obscura serve --port 9222 --stealth
# then point the runner at it: poolUrls: ['http://localhost:9222'], poolDriver: 'obscura'

# Run tests
e2e-runner run --all                  # All suites
e2e-runner run --suite auth           # Single suite
e2e-runner run --tests path/to.json   # Specific file
e2e-runner run --inline '<json>'      # Inline JSON

# Pool management (CLI only, not MCP)
e2e-runner pool start                 # Start Chrome container
e2e-runner pool stop                  # Stop Chrome container
e2e-runner pool status                # Check pool health

# Issue-to-test
e2e-runner issue <url>                # Fetch issue
e2e-runner issue <url> --generate     # Generate test via AI
e2e-runner issue <url> --verify       # Generate + run + report

# Dashboard
e2e-runner dashboard                  # Start web dashboard

# Other
e2e-runner list                       # List available suites
e2e-runner capture <url>              # On-demand screenshot
e2e-runner init                       # Scaffold project

プロジェクトのルートに e2e.config.js を作成します。

export default {
  baseUrl: 'http://host.docker.internal:3000',
  concurrency: 4,
  retries: 2,
  actionRetries: 1,
  testTimeout: 30000,
  outputFormat: 'both',
  failOnNetworkError: true,
  exclude: ['explore-*', 'debug-*'],

  hooks: {
    beforeEach: [{ type: 'goto', value: '/' }],
  },

  environments: {
    staging: { baseUrl: 'https://staging.example.com' },
    production: { baseUrl: 'https://example.com', concurrency: 5 },
  },
};

設定の優先順位（上位が優先されます）：

1. CLI フラグ
2. 環境変数
3. 設定ファイル（e2e.config.js または e2e.config.json）
4. デフォルト値

--env <name> を設定すると、一致するプロファイルがすべての設定より優先されます。

e2e-runner run --all --output junit

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx e2e-runner pool start
      - run: npx e2e-runner run --all --output junit
      - uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: e2e/screenshots/junit.xml

import { createRunner } from '@matware/e2e-runner';

const runner = await createRunner({ baseUrl: 'http://localhost:3000' });

const report = await runner.runAll();
const report = await runner.runSuite('auth');
const report = await runner.runFile('e2e/tests/login.json');
const report = await runner.runTests([
  { name: 'quick-check', actions: [{ type: 'goto', value: '/' }] },
]);