English · Español

@matware/e2e-runner

The AI-native E2E test runner that writes, runs, and debugs tests for you.

E2E Runner lets you test your web app without writing test code. Tests are plain JSON — and you don't even have to write that yourself: just ask Claude Code.

🎬 Write a test by asking — then watch it run

_{The live dashboard while a suite runs — every step streams a screenshot into the feed, in real time.}

With the built-in MCP server, creating a test is a conversation — no docs, no syntax to memorize:

You: Create an E2E test for the login flow and run it.

Claude Code: writes the test, runs it in a real browser, and reports back — ✅ login-flow passed in 2.3s · screenshot saved · no network errors.

Behind the scenes Claude just wrote and ran this. A test is just JSON — an ordered list of what a user does:

[
  { "name": "login-flow", "actions": [
    { "type": "goto", "value": "/login" },
    { "type": "type", "selector": "#email", "value": "user@test.com" },
    { "type": "type", "selector": "#password", "value": "secret" },
    { "type": "click", "text": "Sign In" },
    { "type": "assert_text", "text": "Welcome back" },
    { "type": "screenshot", "value": "logged-in.png" }
  ]}
]

No imports, no describe/it, no build step. If you can read it you can write it — or just ask.

Connect it to Claude Code (2 commands):

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

Now say "create a test for X and run it" — Claude gets 17 MCP tools, slash commands, and specialized agents.

Using a different agent (Cursor, Codex, Copilot, 40+ more)? Install the skill: npx skills add fastslack/mtw-e2e-runner

📖 Contents

🚀 Install — it's tiny

npm install --save-dev @matware/e2e-runner
npx e2e-runner init        # scaffolds e2e/ with a sample test + config

Then pick how to run the browser. You don't need Docker unless you want the parallel pool:

Option 1 · Use the Chrome you already have — no Docker ⭐

Launch any Chromium browser with a debugging port, then point the runner at it:

google-chrome --headless=new --remote-debugging-port=9222 &   # or brave / chromium / msedge
CHROME_POOL_URL=http://localhost:9222 POOL_DRIVER=cdp npx e2e-runner run --all

Or bake it into e2e.config.js so you never repeat it:

export default {
  baseUrl: 'http://localhost:3000',     // your app — plain localhost, no docker hostname
  poolUrls: ['http://localhost:9222'],
  poolDriver: 'cdp',
};

Nothing to install beyond npm, and baseUrl is just localhost (the browser is on your machine).

Option 2 · Obscura — one tiny binary, no Docker

A single ~30 MB binary with built-in anti-detection. Install once, run it, point the runner at it:

obscura serve --port 9222 --stealth &
CHROME_POOL_URL=http://localhost:9222 POOL_DRIVER=obscura npx e2e-runner run --all

npx e2e-runner pool start (with poolDriver: 'obscura' in your config) prints the exact install command for your OS.

Option 3 · Docker pool — parallel, for CI & big suites

A shared, queue-managed Chrome pool that runs many tests at once:

npx e2e-runner run --all     # the first run auto-starts the Docker pool for you

Requires Docker. Set baseUrl: 'http://host.docker.internal:3000' so the containerized Chrome can reach your app.

Write your first test

Open e2e/tests/sample.json — a flow is an ordered list of actions:

[
  { "name": "homepage loads", "actions": [
    { "type": "goto", "value": "/" },
    { "type": "assert_text", "text": "Welcome" },
    { "type": "screenshot", "value": "home.png" }
  ]}
]

Run it with npx e2e-runner run --all. Results — pass/fail, timing, screenshots, network errors — print to your terminal and to the web dashboard if it's open.

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

Updating

Each install method updates separately — bump the one(s) you use:

# npm dependency (per project)
npm install --save-dev @matware/e2e-runner@latest

# Claude Code plugin
claude plugin update e2e-runner@matware

# MCP-only install (npx caches the package — pin @latest to force a refresh)
claude mcp add --transport stdio --scope user e2e-runner \
  -- npx -y -p @matware/e2e-runner@latest e2e-runner-mcp

[!NOTE] Two gotchas: (1) npx prefers a copy found in the project's node_modules over its own cache — if a project pins an old version, the MCP server and dashboard run that old version, so update the project dependency too. (2) Already-running processes keep the old code in memory: after updating, restart the dashboard and reconnect the MCP server (/mcp → e2e-runner → Reconnect, or restart your session).

✨ What you get

🧪 Zero-code tests — JSON files that anyone on your team can read and write. No JavaScript, no compilation, no framework lock-in.

🤖 AI-powered testing — Claude Code creates, executes, and debugs tests natively through 17 MCP tools. Ask it to "test the checkout flow" and it builds the JSON, runs it, and reports back.

🐛 Issue-to-Test pipeline — Paste a GitHub or GitLab issue URL. The runner fetches it, generates E2E tests, runs them, and tells you: bug confirmed or not reproducible.

👁️ Visual verification — Describe what the page should look like in plain English. The AI captures a screenshot and judges pass/fail against your description. No pixel-diffing setup needed.

🧠 Learning system — Tracks test stability across runs. Detects flaky tests, unstable selectors, slow APIs, and error patterns — then surfaces actionable insights.

⚡ Parallel execution — Run N tests simultaneously against a shared browser pool (browserless, raw CDP, Lightpanda, Obscura, or Steel). Serial mode available for tests that share state.

🎯 Pluggable browser drivers — Pick the engine that fits each test: real Chrome via browserless, Lightpanda or Obscura for fast lightweight runs, Steel for managed sessions. Set driver per test or override the whole run with --driver.

📊 Real-time dashboard — Live execution view, run history with pass-rate charts, screenshot gallery with hash-based search, expandable network request logs.

🔁 Smart retries — Test-level and action-level retries with configurable delays. Flaky tests are detected and flagged automatically.

📦 Reusable modules — Extract common flows (login, navigation, setup) into parameterized modules and reference them with $use.