E2e Runner

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.

Why host.docker.internal (Docker option only)?

With the Docker pool, Chrome runs inside a container, so localhost there means the container — not your machine. host.docker.internal bridges to your host. On Linux (Docker Engine, not Docker Desktop) add --add-host=host.docker.internal:host-gateway, or use your LAN IP. Options 1 & 2 don't have this — the browser is local, so plain localhost just works.

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.

Add OpenCode (optional)

cp node_modules/@matware/e2e-runner/opencode.json ./

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

See OPENCODE.md for details.

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.

🏗️ CI-ready — JUnit XML output, exit code 1 on failure, auto-captured error screenshots. Drop-in GitHub Actions example included.

🌐 Multi-project — One dashboard aggregates test results from all your projects. One Chrome pool serves them all.

🐳 Portable — Chrome runs in Docker, tests are JSON files in your repo. Works on any machine with Node.js and Docker.

---

✍️ Writing tests

Everything about authoring tests — the file format, the full action vocabulary, retries, state isolation, and reuse. Expand what you need:

Test format & file layout

Each .json file in e2e/tests/ contains an array of tests. Each test has a name and sequential actions:

[

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

Suite files can have numeric prefixes for ordering (01-auth.json, 02-dashboard.json). The --suite flag matches with or without the prefix, so --suite auth finds 01-auth.json.

Action catalog — navigation, input & interaction

| clear | selector | Clear