Matware E2E Runner

JSON-driven E2E test runner with parallel Chrome pool execution, visual verification, and 16 MCP tools.

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

E2E Runnerlets 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-inMCP server, creating a test is a conversation — no docs, no syntax to memorize:

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

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

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

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

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

Nothing to install beyond npm, andbaseUrlis justlocalhost(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(withpoolDriver: '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. SetbaseUrl: 'http://host.docker.internal:3000'so the containerized Chrome can reach your app.

With the Docker pool, Chrome runs inside a container, solocalhostthere means the container — not your machine.host.docker.internalbridges 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 plainlocalhostjust works.

Opene2e/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 withnpx e2e-runner run --all. Results — pass/fail, timing, screenshots, network errors — print to your terminal and to theweb dashboardif it's open.

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

# 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

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

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

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

These actions handle common patterns in React/MUI apps that normally require verboseevaluateboilerplate:

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

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 asflakyin 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:actionRetriesin config,--action-retries <n>CLI, orACTION_RETRIESenv 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 timeafterall parallel tests finish — preventing interference without slowing down independent tests.

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

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

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

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

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

Extract common flows into parameterized modules:

{ "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": [...] }