Matware E2e Runner

使用 Docker 池时，Chrome 在容器内运行，因此其中的 localhost 指的是容器，而不是你的机器。host.docker.internal 可连接到你的主机。在 Linux 上（Docker Engine，而非 Docker Desktop），请添加 --add-host=host.docker.internal:host-gateway，或使用你的局域网 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 使用 text 而非 selector 时，它会搜索常见的交互元素和内容元素：

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" }

这些操作可处理 React/MUI 应用中的常见模式，而这些模式通常需要编写冗长的 evaluate 样板代码：

// 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）。

共享状态的测试（例如，两个测试修改同一条记录）在并行运行时可能发生竞争。可将这些测试标记为串行：

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

串行测试会在所有并行测试完成后逐个运行——避免相互干扰，同时不降低独立测试的速度。

最简单的方法——像真实用户一样通过 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、本地存储、身份验证令牌），请使用 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 提供 17 个 MCP 工具、一个工作流技能、4 个斜杠命令（/e2e-runner:run、/e2e-runner:create-test、/e2e-runner:verify-issue、/e2e-runner:capture），以及 3 个专用 Agent（test-analyzer、test-creator、test-improver）。

仅安装 MCP（仅工具，不含技能／命令／Agent）：

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. 运行 — 可选择立即执行测试，以验证 Bug 是否可复现

# 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 测试”

Bug 验证逻辑：生成的测试会断言正确行为。测试失败 = 确认存在 Bug。所有测试通过 = 无法复现。

**身份验证：**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。 每张截图都会获得一个确定性哈希（ss:a3f2b1c9）。使用 e2e_screenshot 按哈希检索任意截图 — 它会返回附带元数据（测试名称、步骤、类型）的图像。

{
  "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: '/' }] },
]);