e2e
Write, run, and debug end-to-end tests for web and mobile apps with e2e, the open source agentic test runner.
Документация
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
| Task | Without e2e mcp | With e2e mcp |
|---|---|---|
| Write a test | Guesses locators, runs, fails, guesses again | Writes the test as it walks the flow, from checked test lines and lines it ran with run_code |
| Change the UI | Done when it compiles | Opens the page and checks the result |
| Reproduce a bug | Guesses from the code | Follows the steps in the app |
| Fix a failing test | Clicks through the flow again | Runs the test and stops on the failure |
| Run the suite | Needs a shell for e2e run | Runs it with run_tests |
| Show a change in a PR | Describes it | Records 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 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 app | A run while a session is open |
|---|---|
No command | Both use the app you started. |
url on port 0 | Each 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: true | The run uses the app the session started. When the session closes, also during a run, that app stops. |
command on a fixed port, without reuseExisting | Fails 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_recordingare not masked.