e2e-runner MCP server

---

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

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

	Section	What's inside
🚀	Install & first test	npm setup · run with your own Chrome (no Docker), Obscura, or a Docker pool
✨	What you get	feature overview at a glance
✍️	Writing tests	test format · full action catalog · retries · serial · modules · auth · hooks
🤖	AI integration	Claude Code · OpenCode · 17 MCP tools · visual verification · issue-to-test
📊	Dashboard & insights	live dashboard · learning system · network logs · screenshot capture
🌐	Browser drivers	browserless · cdp · lightpanda · obscura · steel
⚙️	CLI, config & CI	commands · flags · e2e.config.js · GitHub Actions · programmatic API

---

🚀 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.

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.

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:

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	Fields	Description
goto	value	Navigate to URL (relative to baseUrl or absolute)
click	selector or text	Click by CSS selector or visible text content. Text mode also takes scope: "dialog", visible: true, last: true
type / fill	selector, value	Clear field and type text
wait	selector, text, gone, or value (ms)	Wait for element/text to appear, for gone to disappear (spinner/dialog), or fixed delay. Prefer conditions over fixed value sleeps
screenshot	value (filename)	Capture a screenshot
select	selector, value	Select a dropdown option
clear	selector	Clear an input field
press	value	Press a keyboard key (Enter, Tab, etc.)
scroll	selector or value (px)	Scroll to element or by pixel amount
hover	selector	Hover over an element
evaluate	value	Execute JavaScript in the browser context
navigate	value	Browser navigation (back, forward, reload)
clear_cookies	—	Clear all cookies for the current page
wait_network_idle	optional value (idle ms, default 500), timeout	Wait until the network has been idle for value ms — useful after actions that trigger background requests
set_storage	value ("key=val"), optional selector: "session"	Set a localStorage key (or sessionStorage with selector: "session")
gql	value (query), optional text (variables JSON), optional selector (assertion)	Run a GraphQL query/mutation via in-page fetch, with the auth token read from localStorage. Fails on GraphQL errors. selector is a JS expression asserted against the response r (e.g. "r.data.users.length > 0"). Installs window.__e2eGql for later evaluate steps

Click by text — when click uses text instead of selector, it searches across common interactive and content elements:

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

Action	Fields	Description
assert_text	text	Assert text exists anywhere on the page (substring)
assert_no_text	text	Assert text does NOT appear anywhere on the page — opposite of assert_text
assert_text_in	selector, text, optional value: "exact"	Assert text inside a scoped container. text is a case-insensitive regex by default; value: "exact" switches to case-sensitive substring
assert_element_text	selector, text, optional value: "exact"	Assert element's text contains (or exactly matches) the expected text
assert_url	value	Assert current URL path or full URL. Paths (/dashboard) compare against pathname only
assert_visible	selector	Assert element exists and is visible
assert_not_visible	selector	Assert element is hidden or doesn't exist
assert_attribute	selector, value	Check attribute: "type=email" for value, "disabled" for existence
assert_class	selector, value	Assert element has a CSS class
assert_input_value	selector, value	Assert input/select/textarea .value contains text
assert_matches	selector, value (regex)	Assert element text matches a regex pattern
assert_count	selector, value	Assert element count: exact ("5"), or operators (">3", ">=1", "<10")
assert_no_network_errors	—	Fail if any network requests failed (e.g. ERR_CONNECTION_REFUSED)
assert_storage	value ("key" or "key=expected"), optional selector: "session"	Assert a localStorage/sessionStorage key exists or has a specific value
assert_visual	value (golden image), optional selector, text (max diff, e.g. "0.02"), fullPage, maskRegions, threshold	Visual regression: compare a screenshot against a golden reference. The first run saves the golden; later runs fail if more pixels differ than the threshold (default 2%) and write a diff image
get_text	selector	Extract element text (non-assertion, never fails). Result: { value: "..." }

These actions handle common patterns in React/MUI apps that normally require verbose evaluate boilerplate:

Action	Fields	Description
type_react	selector, value, optional blur, waitAfter	Type into React controlled inputs using the native value setter. Dispatches input + change events so React state updates correctly. blur: true commits on blur; waitAfter: "<ms>" waits after (debounced autocomplete).
click_regex	text (regex), optional selector, optional value: "last"	Click element whose textContent matches a regex (case-insensitive). Default: first match. Use value: "last" for last match.
click_option	text	Click a [role="option"] element by text — common in autocomplete/select dropdowns.
select_combobox	text, optional selector, filter, openWait/filterWait/waitAfter	Open a MUI Autocomplete/Select, optionally type filter, then click the option matching text. Falls back across [role="option"], .MuiAutocomplete-option, li.MuiMenuItem-root.
focus_autocomplete	text (label text)	Focus an autocomplete input by its label text. Supports MUI and generic [role="combobox"].
click_chip	text	Click a chip/tag element by text. Searches [class*="Chip"], [class*="chip"], [data-chip].
click_icon	value (icon id), optional selector (scope)	Click an icon by data-testid/data-icon/aria-label/class fragment or SVG <title> — MUI, FontAwesome, Heroicons, etc. Clicks the nearest clickable ancestor (button, link, tab).
click_menu_item	text, optional selector (scope)	Click a menu item by text across [role="menuitem"], .dropdown-item, .menu-item, MUI MenuItem.
click_in_context	text (container text), selector (child)	Click a child element inside the smallest container matching text — e.g. the delete button of one specific card/row.

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

Action	Fields	Description
open_tab	value (URL), optional text (label)	Open a new tab and navigate to the URL (relative to baseUrl or absolute). Label defaults to tab-<n>
switch_tab	value	Switch the active tab by label, numeric index, or title/URL match (regex or substring). "default" returns to the original tab
wait_for_tab	optional text (label), timeout	Wait for a new tab/popup opened by the app (window.open, target="_blank") and make it the active tab
assert_tab_count	value	Assert the number of open tabs: exact ("2") or operators (">=2")
close_tab	optional value (label)	Close the current (or named) tab and switch back to the last remaining one

All subsequent actions run in the active tab:

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

Test-level retry — retry an entire test on failure. Set globally via config or per-test:

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

Tests that pass after retry are flagged as flaky in the report and learning system.

Action-level retry — retry a single action without rerunning the entire test. Useful for timing-sensitive clicks and waits:

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

Set globally: actionRetries in config, --action-retries <n> CLI, or ACTION_RETRIES env var. Delay between retries: actionRetryDelay (default 500ms).

Tests that share state (e.g., two tests modifying the same record) can race when running in parallel. Mark them as serial:

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

Serial tests run one at a time after all parallel tests finish — preventing interference without slowing down independent tests.

The simplest approach — log in via the UI like a real user:

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

For SPAs with JWT, skip the login form by injecting the token directly:

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

Or set it globally in config:

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

Each test runs in a fresh browser context, so auth state is automatically clean between tests.

More strategies: Cookie-based auth, HTTP header injection, OAuth/SSO bypasses, reusable auth modules, and role-based testing — see docs/authentication.md

Extract common flows into parameterized modules:

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

Use in tests:

{
  "name": "dashboard-loads",
  "actions": [
    { "$use": "login", "params": { "email": "user@test.com", "password": "secret" } },
    { "type": "assert_text", "text": "Dashboard" }
  ]
}

Modules support parameter validation (required params fail fast), conditional blocks ({{#param}}...{{/param}}), nested composition, and cycle detection.

Run actions at lifecycle points. Define globally in config or per-suite:

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

Important: beforeAll runs on a separate browser page that is closed before tests start. Use beforeEach for state that tests need (cookies, localStorage, auth tokens).

Skip exploratory or draft tests from --all runs:

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

Individual suite runs (--suite) are not affected by exclude patterns.

---