e2e

Write, run, and debug end-to-end tests for web and mobile apps with e2e, the open source agentic test runner.

Dokumentasi

MCP server

Let your coding agent use your app and check its own work.

e2e mcp gives a coding agent such as Claude Code, Codex, or Cursor a live session on your app, on web, iOS, or Android. The agent sees the screen, acts on it, and checks its work.

Why it matters

TaskWithout e2e mcpWith e2e mcp
Write a testGuesses locators, runs, fails, guesses againWrites the test as it walks the flow, from checked test lines and lines it ran with run_code
Change the UIDone when it compilesOpens the page and checks the result
Reproduce a bugGuesses from the codeFollows the steps in the app
Fix a failing testClicks through the flow againRuns the test and stops on the failure
Run the suiteNeeds a shell for e2e runRuns it with run_tests
Show a change in a PRDescribes itRecords a video

The server needs no model. A test it runs needs one only for an agent step with no recording.

Set it up

The e2e plugin includes the server as npx -y e2e@<version> mcp, pinned to the plugin's e2e release. It runs that release even when the project has another e2e version installed. Without the plugin, register it in the project. e2e init offers to register the server in .mcp.json (Claude Code), .cursor/mcp.json (Cursor), and .codex/config.toml (Codex). Install the project dependencies and start the MCP client in the project directory so npx (bunx in a Bun project) uses the installed e2e version. By hand:

```bash npm claude mcp add --scope project e2e -- npx e2e mcp ```
```bash pnpm
claude mcp add --scope project e2e -- pnpm exec e2e mcp
```

```bash bun
claude mcp add --scope project e2e -- bunx e2e mcp
```
</CodeGroup>
Run `e2e init --yes --skills none --mcp .codex/config.toml` with the installed CLI, or add the entry below. Trust the project and start a new Codex session. `codex mcp list`, run in the project, shows the registration:
```toml title=".codex/config.toml"
[mcp_servers.e2e]
command = "npx"
args = ["e2e", "mcp"]
```
Add the server to `.cursor/mcp.json`. Other clients that read an `mcpServers` map take the same block.
```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "e2e": { "command": "npx", "args": ["e2e", "mcp"] }
  }
}
```

A session starts the target's app command, if it has one, and names it with its URL and port. The config reads the server's environment, not the agent's shell.

Try it without a config

In a directory with no e2e config file, the agent names the engine when it opens a session:

open_session {engine: "@e2e-dev/web", app: {url: "http://localhost:3000"}}

run_tests still needs a config. For engine options, device providers, and installing an engine, see Without a config.

Ask the agent

  • "Add a Remember me checkbox to the login form. Check it in the app with e2e."
  • "Write a test for checkout while you walk it in the app."
  • "Reproduce issue #123 in the app and record a video."

Add "headed" to watch a local browser or simulator.

How it writes a test line

Each action in a session answers with the test line that repeats it. The line's locator matched that control alone on the live screen:

Tapped #n31.
Test line: await screen.getByRole("button", "Sign in").tap();

The agent copies the lines it needs into the test as it walks the flow. test_lines returns every line so far, in order, as a draft test body. See test_lines for how a line is built.

How it checks a locator

For a line no action printed, such as an assertion, the agent tries the locator in the session first. A wrong guess fails there, not in a test run:

0 nodes match getByLabel("Email").
A test using this locator would fail with LOCATOR_NOT_FOUND. ...

1 node matches getByRole("button", name: "Sign in").
Use: screen.getByRole("button", "Sign in")

How it runs a test line

The agent runs the lines no action printed, such as assertions, with run_code in the open session. The ones that pass join the test_lines draft. A wrong line fails in seconds, without a test run:

Statement 2 of 2 failed; the one before it passed. Each statement waited at most 5000 ms. ...
1. passed: await screen.getByLabel('Full name').fill('Grace Hopper');
2. failed: await screen.getByRole('button', 'Save').tap();
   LOCATOR_NOT_FOUND: locator matched no nodes within getByRole("button", name: "Save")

The server parses the lines and never evaluates them as JavaScript. See run_code.

Fix a failing test

open_session {test: "tests/checkout.e2e.ts:12"} runs one test in the session and stops on the screen where it failed. The agent reads the failure, checks the screen, and edits the test:

Test "a member checks out" (tests/checkout.e2e.ts:12) failed after 30.25s; 8 steps ran.
LOCATOR_NOT_FOUND: locator matched no nodes within getByLabel("Name")
At tests/checkout.e2e.ts:20:3
On screen, closest to what the locator asked for:
  #n32 textbox "Full name"

Each action from that screen prints its test line, and run_code runs a fixed line there. The agent puts those lines in the test in place of the one that failed.

To rerun the edited test, the agent closes the session and opens a new one with the same test. Agent steps replay from the cache as in e2e run. See Running a test for what runs and the limits.

Run tests next to a session

A session writes no test results, and only a test it runs with open_session {test} uses the replay cache. The agent runs suites with run_tests, the same run as e2e run, and, when a run can go beside the session, keeps the session open between runs. After a failed run, it goes to the failing screen in that session instead of opening a new one.

On web, a run next to a session depends on the target's app:

Target's appA run while a session is open
No commandBoth use the app you started.
url on port 0Each starts its own copy of the app. A dev server that runs one copy per directory, such as next dev, fails the run.
command with reuseExisting: trueThe run uses the app the session started. When the session closes, also during a run, that app stops.
command on a fixed port, without reuseExistingFails with APP_ALREADY_RUNNING.

When CI is set, e2e ignores reuseExisting, and the run fails as on a fixed port. Close the session before a run that would fail. On mobile, run on a device no session uses.

Run several agents

Each agent, subagents included, opens its own session with its own browser or device, up to four by default. On mobile, give each session its own target.

Secrets

type_secret, or a fill in run_code, fills a secret without showing it to the agent. Screenshots mask secure fields only, so a secret the app shows anywhere else is in them.

Warning

Videos from start_recording are not masked.

Next

Every tool, flag, session rule, and error code. The skill, running tests, and reading a failure.