MTW E2E Runner

You can run JSON-driven end-to-end browser tests with a built-in MCP server that integrates with Claude Code. Define tests as simple JSON action arrays, execute them in parallel against a Chrome pool, and generate JSON and JUnit XML reports without writing JavaScript test files.

How to use

To use this MCP server, install the package in your project, start the Chrome pool, and connect your MCP client or Claude integration to run tests. Define tests as JSON files, place them in your tests directory, and trigger runs through the MCP interface. You will see structured reports and screenshots for failures, and you can run tests in parallel against a shared pool.

How to install

Prerequisites you need before installing and running the MCP server in your project.

# Install the package
npm install @matware/e2e-runner

# Scaffold project structure
npx e2e-runner init

# Start Chrome pool (requires Docker)
npx e2e-runner pool start

# Run all tests
npx e2e-runner run --all

Configuration and usage notes

The MCP server supports a configuration file that controls base URL, concurrency, timeouts, and environment profiles. It also supports hooks that run actions before and after tests. You can customize per-suite settings and enable retries with per-test timeouts.

export default {
  baseUrl: 'http://host.docker.internal:3000',
  concurrency: 4,
  retries: 2,
  testTimeout: 30000,
  outputFormat: 'both',

  hooks: {
    beforeEach: [{ type: 'goto', value: '/' }],
    afterEach: [{ type: 'screenshot', value: 'after-test.png' }],
  },

  environments: {
    staging: { baseUrl: 'https://staging.example.com' },
    production: { baseUrl: 'https://example.com', concurrency: 5 },
  },
};

How tests are defined and run

Create JSON test suites that describe a sequence of actions. Each test has a name and an ordered array of actions. You can run all suites, a single suite, or a specific test file. The runner executes actions in order, reporting results and capturing screenshots on failure.

[
  {
    "name": "homepage-loads",
    "actions": [
      { "type": "goto", "value": "/" },
      { "type": "wait", "selector": ".hero" },
      { "type": "assert_text", "text": "Welcome" },
      { "type": "assert_url", "value": "/" },
      { "type": "screenshot", "value": "homepage.png" }
    ]
  }
]

MCP integration with Claude Code

A built-in MCP server is provided to enable Claude Code native access to the test runner. You can add the MCP server to Claude with either npm-based or Docker-based commands. Once installed, Claude Code can run tests, examine failures, and manage the Chrome pool as part of your workflow.

# Via npm (requires Node.js)
claude mcp add --transport stdio --scope user e2e-runner \
  -- npx -y -p @matware/e2e-runner e2e-runner-mcp

# Via Docker (no Node.js required)
claude mcp add --transport stdio --scope user e2e-runner \
  -- docker run -i --rm fastslack/e2e-runner-mcp

Tools and capabilities

The MCP integration exposes a set of tools to interact with the test runner, list suites, create tests, manage the Chrome pool, and generate reports.

Security and environment

Keep your base URL and pool credentials in secure environments. Use per-environment configurations and avoid exposing sensitive data in test files. The MCP server is designed to run in containers or local environments with network access to the host for test orchestration.

Troubleshooting tips

If tests fail to start or the pool reports issues, check that Docker is running and the pool is reachable at the configured WebSocket URL. Validate that tests exist in the correct directory and that the base URL is accessible from the running browser context.

Notes

This MCP server is designed to enable end-to-end browser testing in a streamlined JSON workflow, with parallel execution and standard reporting formats. Ensure your environment matches the prerequisites: Node.js version 20 or later and Docker for the Chrome pool.

Available tools

e2e_run

Run tests (all suites, by suite name, or by file path) from the MCP interface.

e2e_list

List available test suites with test names and counts.

e2e_create_test

Create a new test JSON file via MCP workflow.

e2e_pool_status

Check Chrome pool availability and capacity.

e2e_pool_start

Start the Chrome pool Docker container.

e2e_pool_stop

Stop the Chrome pool.