mirror of
https://github.com/tester-army/e2e.git
synced 2026-11-22 18:19:48 +08:00
Second review round: only code cut off by a cancel or the timeout is parked, so a handler one call left runs in the next; a string passes the ledger before it is escaped into a line; a rejection in the code's last turn fails the call; a cancel aborts the operation in flight and stops waiting for one that ignores it; names are numbered by the session; bytes, maps, and dates come back as themselves.
768 lines
35 KiB
Plaintext
768 lines
35 KiB
Plaintext
---
|
|
title: MCP server (e2e mcp)
|
|
description: Let a coding agent inspect and interact with your app over MCP.
|
|
"og:image": "https://e2e.com/docs/images/og/reference/mcp.png?v=3d3880edad"
|
|
"twitter:image": "https://e2e.com/docs/images/og/reference/mcp.png?v=3d3880edad"
|
|
---
|
|
|
|
`e2e mcp` lets coding agents such as Claude Code and Cursor inspect your app,
|
|
try locators, run test lines, and take masked screenshots while they write tests. It runs over
|
|
stdio and uses the project's configured engine. For setup and what to ask
|
|
the agent, see the [MCP server guide](/mcp-server).
|
|
|
|
```json title=".mcp.json"
|
|
{
|
|
"mcpServers": {
|
|
"e2e": { "command": "npx", "args": ["e2e", "mcp"] }
|
|
}
|
|
}
|
|
```
|
|
|
|
Four MCP tools manage the session and call its available app tools. The app
|
|
tool catalog reloads from the config whenever a session opens.
|
|
|
|
## Reference
|
|
|
|
### Flags
|
|
|
|
<CodeGroup>
|
|
```bash npm
|
|
npx e2e mcp [--config <path>] [--target <name>] [--headed] [--max-sessions <n>]
|
|
```
|
|
|
|
```bash pnpm
|
|
pnpm exec e2e mcp [--config <path>] [--target <name>] [--headed] [--max-sessions <n>]
|
|
```
|
|
|
|
```bash bun
|
|
bunx e2e mcp [--config <path>] [--target <name>] [--headed] [--max-sessions <n>]
|
|
```
|
|
</CodeGroup>
|
|
|
|
| Flag | Default |
|
|
| --- | --- |
|
|
| [`--config <path>`](#config) | discovered like `e2e run` |
|
|
| [`--target <name>`](#target) | the only target |
|
|
| [`--headed`](#headed) | headless |
|
|
| [`--max-sessions <n>`](#max-sessions) | `4`, `1` on Bun |
|
|
|
|
#### `--config`
|
|
|
|
The config every session loads unless `open_session` names one. Each
|
|
session loads it afresh ([Several sessions](#several-sessions)) with the
|
|
server's environment: `process.env` in the config reads the variables the
|
|
MCP client started `e2e mcp` with, not the agent's shell.
|
|
|
|
#### `--target`
|
|
|
|
The target a session opens on when `open_session` names none.
|
|
|
|
- Without it and without a name, the only target is used.
|
|
- Several targets and no name is `TARGET_REQUIRED`.
|
|
|
|
#### `--headed`
|
|
|
|
Shows the browser or simulator, when the engine supports it, in every
|
|
session whose `open_session` does not set `headed`.
|
|
|
|
- Sessions are headless by default, as in `e2e run`.
|
|
|
|
#### `--max-sessions`
|
|
|
|
How many sessions may be open at once, 1 through 16. On
|
|
[Bun](/reference/cli#bun), one. See [Several sessions](#several-sessions).
|
|
|
|
```bash
|
|
e2e mcp --max-sessions 8 # default: 4
|
|
```
|
|
|
|
### Tools
|
|
|
|
| Tool | Description |
|
|
| --- | --- |
|
|
| [`open_session`](#open_session) | Opens a session |
|
|
| [`tools`](#tools-2) | Lists the catalog or one tool |
|
|
| [`call`](#call) | Runs one catalog tool |
|
|
| [`close_session`](#close_session) | Ends the session and its engine |
|
|
|
|
`session` may be left out while exactly one session is open. See
|
|
[Several sessions](#several-sessions).
|
|
|
|
#### `open_session`
|
|
|
|
Without `attach`, starts a new attempt using the config, engine, and app
|
|
command for the target. The app opens at its URL or starts fresh on a
|
|
device from the [pinned app](/mobile#point-at-your-app). It installs
|
|
no build, so a local device target needs `app.bundleId`. Returns the session
|
|
id, the catalog, and the first observation. The catalog there gives the single
|
|
actions by name and arguments only; [`tools`](#tools-2) describes each. The summary above the observation
|
|
tells the agent to read the `writing-tests` guide (`e2e://guide/writing-tests`) before it
|
|
writes or edits a test; the server's instructions say the same.
|
|
|
|
The summary names the app's URL, with the port a free-port `url` was
|
|
assigned, and the app command: its executable, readiness URL, `env` and
|
|
`inheritEnv` names, and log file. It prints no `args`, no `env` values, and
|
|
no URL userinfo or query. e2e starts no other app process, so a database the
|
|
app uses runs outside it.
|
|
|
|
```text wrap
|
|
App: http://127.0.0.1:57162/ (port 57162, assigned for the declared port 0).
|
|
Process: app.command "node" (ready at http://127.0.0.1:57162/; env PORT, DATABASE_URL; log .e2e/app.log). e2e starts no other app process for this session; a database or other service the app uses runs outside e2e.
|
|
```
|
|
|
|
```txt
|
|
open_session {target: "web", headed: true}
|
|
```
|
|
|
|
| Input | Type | Required | Does |
|
|
| --- | --- | --- | --- |
|
|
| `target` | string | no | The target to open. Otherwise `--target`, else the only target. |
|
|
| `config` | string (path) | no | The config for this session, absolute or relative to the server's working directory (`cwd` in the client's MCP config). Otherwise `--config`, else discovered like `e2e run`. |
|
|
| `headed` | boolean | no | `true` shows this session's browser or simulator, `false` hides it. Without it the session follows `--headed`. |
|
|
| `path` | string | no | Where on the app URL to open instead of its root, such as `/settings/members`. The first observation is that page. Not with `test`. |
|
|
| `test` | string | no | One test to run first, named like an `e2e run` positional. The session stops where the test stopped. See [Running a test](#running-a-test). |
|
|
| `engine` | string or object | no | The session's engine in a directory with no config file, as a package name or `{package, export, options}`. See [Without a config](#without-a-config). |
|
|
| `app` | object | no | The app under test for an `engine` session, as `url`, `bundleId`, or `appPath`. |
|
|
| `attach` | string | no | ID from the pause header of a [held test](#attaching-to-a-held-test). Pass only this field. |
|
|
|
|
#### `tools`
|
|
|
|
Returns the catalog, one line per tool.
|
|
|
|
```txt
|
|
tools {tool: "locate"}
|
|
```
|
|
|
|
| Input | Type | Required | Does |
|
|
| --- | --- | --- | --- |
|
|
| `tool` | string | no | A catalog tool. Returns its full description and argument schema. |
|
|
| `session` | string | while several are open | The session id. |
|
|
|
|
#### `call`
|
|
|
|
Runs one catalog tool.
|
|
|
|
```txt
|
|
call {tool: "tap", args: {target: "n42"}, session: "<id>"}
|
|
```
|
|
|
|
| Input | Type | Required | Does |
|
|
| --- | --- | --- | --- |
|
|
| `tool` | string | yes | A catalog tool name. |
|
|
| `args` | object | no | The tool's arguments. |
|
|
| `session` | string | while several are open | The session id. |
|
|
|
|
- Arguments are validated against the tool's closed schema first. A wrong
|
|
type, or an argument a tool that declares arguments does not declare, is
|
|
`INVALID_ARGUMENT`, and nothing runs. `back` and `dismiss_keyboard` take no
|
|
arguments; they drop any they are given and run.
|
|
- An action that fails is an error result that still carries the screen it
|
|
re-observed. It leads with the tool, its target, and the code:
|
|
`navigate file:///etc/passwd failed: POLICY_DENIED: forbidden URL scheme: file:`.
|
|
- Project tools honor their AI SDK `toModelOutput` renderer, including when
|
|
`execute` returns a string. Rendered `error-text` and `error-json` outputs
|
|
are MCP error results (`isError: true`). The coding agent can tell a failed
|
|
tool call from a successful one.
|
|
|
|
#### `close_session`
|
|
|
|
Saves a recording still running, ends the attempt, and disposes the engine.
|
|
It stops the app processes the session started once no other session uses
|
|
them. Use it on an attachment to detach and leave the test held.
|
|
|
|
```txt
|
|
close_session {session: "<id>"}
|
|
```
|
|
|
|
| Input | Type | Required | Does |
|
|
| --- | --- | --- | --- |
|
|
| `session` | string | while several are open | The session id. |
|
|
|
|
### The catalog
|
|
|
|
What `call` can run depends on the session's target.
|
|
|
|
| Catalog tool | Description |
|
|
| --- | --- |
|
|
| [`observe`](#observe) | Returns a fresh observation |
|
|
| [Actions](#actions) | Act on an observed node |
|
|
| [`dismiss_keyboard`](#dismiss_keyboard) | Hides the on-screen keyboard |
|
|
| [`locate`](#locate) | Tries a semantic locator |
|
|
| [`run_code`](#run_code) | Runs JavaScript on the test API |
|
|
| [`test_lines`](#test_lines) | Returns the session's test lines |
|
|
| [`screenshot`](#screenshot) | Returns the masked viewport, optionally saved to a file |
|
|
| [Point tools](#point-tools) | Act at a screenshot point |
|
|
| [`start_recording`, `stop_recording`](#recording) | Records a video of the app |
|
|
| [Project tools](#project-tools) | Your `defineTool` tools |
|
|
|
|
#### `observe`
|
|
|
|
A fresh observation, one node per line as `#id role "name" ...`, with the
|
|
current path and revision. Takes no arguments.
|
|
|
|
- A link's `href` is its path when it is on the app URL's origin, else
|
|
origin and path.
|
|
- `mailto:`, `tel:`, and `blob:` targets keep their scheme.
|
|
- `…` marks what is left out: `?…` a query, `#…` a fragment, `data:…` or
|
|
`javascript:…` an inline payload, a trailing `…` a target cut at 256
|
|
characters.
|
|
|
|
#### Actions
|
|
|
|
`tap`, `double_tap`, `long_press`, `right_click`, `hover`, `type`, `press`,
|
|
`select`, `check`, `scroll`, `scroll_to`, `drag`, `upload`, `navigate`,
|
|
`back`, `resize_viewport`, `switch_tab`, `close_tab`, `type_secret`. Each returns the action's summary, the
|
|
[test line](#test_lines) that repeats it or why there is none, and what
|
|
changed on screen.
|
|
|
|
| Input | Does |
|
|
| --- | --- |
|
|
| A node id | From the newest observation. |
|
|
| The value, key, `checked` state, direction, drop target, project-relative or `sample:` `files`, URL, `width` and `height`, or secret name | What the verb needs. |
|
|
| `modifiers` (optional) | On `tap`, `double_tap`, and `right_click`, when the engine declares `tapModifiers`: a list of `Shift`, `Control`, `Alt`, `Meta`, `ControlOrMeta`, held for the click. |
|
|
|
|
- A verb the engine does not declare is not in the catalog.
|
|
- `upload` refuses a path outside the project, a hidden file, or a file
|
|
under a hidden directory with `POLICY_DENIED`. A `sample:` file has no
|
|
test line: save a file in the project for one.
|
|
- `type_secret` is listed when the config declares `credentials` or
|
|
`secrets` and the engine declares the `fill` action. The plaintext never
|
|
reaches the agent as text; see
|
|
[screenshots after a secret fill](/reference/security#screenshots-after-a-secret-fill).
|
|
|
|
#### `dismiss_keyboard`
|
|
|
|
Hides the on-screen keyboard. Takes no arguments. Listed when the engine's
|
|
keyboard declares `dismiss`, as the device engines do.
|
|
|
|
#### `locate`
|
|
|
|
Returns how many nodes match a semantic locator, which ones, and the
|
|
`screen.*` call to write.
|
|
|
|
| Input | Does |
|
|
| --- | --- |
|
|
| `role` (with optional `name`), `text`, `label`, `placeholder`, `testId` | Exactly one of them. |
|
|
| `exact` | Exact matching; `false` for substring, case-insensitive. |
|
|
|
|
- Zero or several matches name the error a test would get.
|
|
- A `name` matches the accessible name only. `observe` shows a `status`,
|
|
`alert`, or `listitem` by its text, so one of those with a name that
|
|
matches nothing also points at `getByRole(role).filter({ hasText })` and
|
|
`getByText`.
|
|
- What it shows of a node passes the secret ledger, as `observe` does: a
|
|
filled secret reads `<secret:name>`.
|
|
|
|
#### `run_code`
|
|
|
|
Runs JavaScript on the live session and returns what the code returned, what
|
|
it logged, each line it ran on the app, and what changed on screen. Use it
|
|
to read values, compute on them, and act in one call, and to run a line
|
|
before you write it into a test.
|
|
|
|
```txt
|
|
call {tool: "run_code", args: {code: "const rows = screen.getByRole('listitem');\nconst prices = (await rows.allTextContents()).map((text) => Number(text.match(/\\$([\\d.]+)/)[1]));\nawait expect(rows).toHaveCount(12);\nreturn prices;"}}
|
|
```
|
|
|
|
| Input | Does |
|
|
| --- | --- |
|
|
| `code` | The body of an async function. `screen`, `app`, `expect`, `credentials`, `secrets`, `console`, and the engine's fixture (`browser` or `device`) are in scope. A session attached to a held test has no engine fixture. |
|
|
| `timeout` | Optional. How long each action or matcher on `screen` may wait, in ms, 1 through 120000. Default `5000`. |
|
|
|
|
```txt
|
|
Returned: [12.5,18,24]
|
|
Test lines: 2, 1 read not listed.
|
|
1. await expect(screen.getByRole('listitem')).toHaveCount(12);
|
|
```
|
|
|
|
- The code is ordinary JavaScript in the server's Node process, and the
|
|
objects in scope are the ones a test body gets. A call waits, matches,
|
|
and fails as it does in a test, and a function you pass, such as a
|
|
`browser.route` handler, is called like a test's.
|
|
- `return` a JSON value to get it back. `console.log` lines come back too.
|
|
- A line that fails throws the error a test gets, with its `code`. Uncaught,
|
|
it stops the code and the result is an error result. The app stays where
|
|
the passing lines left it.
|
|
- `await` each line. A failure nothing awaited fails the call. So does a
|
|
promise the code left to reject, and an error a `setTimeout` callback
|
|
throws.
|
|
- The result lists the lines that ran. A read shows its value there when the
|
|
code returns nothing and logs nothing. Otherwise `return` the value.
|
|
- The lines that pass, except reads, join the [`test_lines`](#test_lines)
|
|
draft in the order they ran. A call that resolves with a value counts as a
|
|
read, unless it passes a function, such as a page script for `evaluate`,
|
|
which may change the page. An object a call resolves with, such as a new
|
|
tab, gets a `const` line that names it.
|
|
- Each action or matcher on `screen` waits at most `timeout`. The config's
|
|
[`actionTimeout`](/reference/config#actiontimeout) and
|
|
[`assertionTimeout`](/reference/config#assertiontimeout) apply when
|
|
shorter. `app` and the engine's fixture wait as they do in a test.
|
|
- The whole call may run 5 minutes. Code that never yields, such as
|
|
`while (true) {}`, blocks the server.
|
|
- The result shows `<secret:name>` where a configured secret value is.
|
|
|
|
The code is not confined. It has the authority of a test file: it can
|
|
import modules, read files, and read the values the app shows, a secret
|
|
included. See [Security](/reference/security).
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `INVALID_ARGUMENT` | Code that doesn't parse. The message gives the line, and nothing runs. |
|
|
| `ASSERTION_FAILED` | An `expect` that doesn't hold. |
|
|
| `POLICY_DENIED` | A read of a secure field, such as a password input. |
|
|
|
|
An error that is not the runner's, such as a `TypeError`, comes back by its
|
|
name with the line it was thrown on.
|
|
|
|
#### `test_lines`
|
|
|
|
Returns every test line the session's actions printed, and every line
|
|
[`run_code`](#run_code) passed, in order, as a draft test body. Takes no
|
|
arguments.
|
|
|
|
Each action's result carries its line after the summary:
|
|
|
|
```txt
|
|
Tapped #n31.
|
|
Test line: await screen.getByRole("button", "Sign in").tap();
|
|
```
|
|
|
|
- The locator comes from the target as the newest observation listed it,
|
|
before the action runs. Role and name, label, placeholder, text, and test
|
|
id are tried in that order, and the first that matches the target and
|
|
nothing else on the live screen wins, as [`locate`](#locate) would report it.
|
|
- A locator that also matches twins is narrowed: to nodes that render
|
|
(`{ visible: true }`), then under a container
|
|
(`getByRole("listitem").filter({ hasText: "Offer B" })`), then by position
|
|
(`.nth(1)`, with a comment saying so). A position is used only when the
|
|
live twins are the ones the observation listed, each in place or all
|
|
moved together.
|
|
- A control with no name, label, placeholder, text, or test id is found by
|
|
its role: alone when it is the only one (`getByRole("spinbutton")`, with
|
|
a comment), else narrowed like twins.
|
|
- At most 10 locators are tried per target. On a device each try reads the
|
|
whole screen.
|
|
- When nothing reaches the target alone, the result says `No test line:`
|
|
and why. A line that would fail is never printed.
|
|
- A failed action prints and records no line. The draft shows an action
|
|
without a line as a `//` comment.
|
|
|
|
| Action | Line |
|
|
| --- | --- |
|
|
| Opening the session, without [`test`](#running-a-test) | `app.open()` |
|
|
| `tap`, `double_tap`, `long_press`, `right_click`, `hover` | `tap()`, `doubleTap()`, `longPress()`, `secondaryTap()`, `hover()`, with any `modifiers` |
|
|
| `type` into a node | `fill(value)`; a credential's username as `credentials.user(name).username` |
|
|
| `type_secret` | `fill(credentials.user(name).password)` or `fill(secrets.get(name))`, never the value |
|
|
| `press` on a node, once | `press(key)` |
|
|
| `select`, `check` | `selectOption(label)`, `check()` or `uncheck()` |
|
|
| `drag`, `upload` | `dragTo(locator)`, `setInputFiles(files)` |
|
|
| `scroll_to` a node | `scrollIntoView()` |
|
|
| `navigate`, `back` | `app.open(url)`, with a URL on the app's origin as its path; `app.back()` |
|
|
|
|
No line: `type` or `press` with no target, `press` with `times` over 1,
|
|
`scroll`, `scroll_to` a text, `dismiss_keyboard`, `resize_viewport` (set the
|
|
size with the engine's built-in fixture, `browser.setViewport` on web), `switch_tab`
|
|
and `close_tab` (`browser.tabs()[tab - 1].activate()` and `.close()` on
|
|
web), and a `type` the
|
|
node took through the keyboard. The [point tools](#point-tools) print nothing.
|
|
|
|
#### `screenshot`
|
|
|
|
The masked viewport as an image.
|
|
|
|
| Argument | Type | Description |
|
|
| --- | --- | --- |
|
|
| `path` | `string` | Optional. Also saves the screenshot as a PNG file, resolved against the project root, and returns its absolute path. A path outside the project, a hidden file, or one under a hidden directory is `POLICY_DENIED`. |
|
|
|
|
```json
|
|
{ "tool": "screenshot", "args": { "path": "screenshots/checkout.png" } }
|
|
```
|
|
|
|
- From then on every action result carries a fresh screenshot.
|
|
- It masks secure fields only, after a secret fill too.
|
|
- The file is a second, full-resolution capture, masked as `app.screenshot`
|
|
masks it. The attached image may be scaled down.
|
|
|
|
#### Point tools
|
|
|
|
Each takes `x` and `y` in the latest screenshot's pixels. `drag_at` takes its
|
|
drop point as `to_x` and `to_y`.
|
|
|
|
| Tool | Inputs | Does | Listed when the engine declares |
|
|
| --- | --- | --- | --- |
|
|
| `tap_at` | `x`, `y` | Taps the bare point through the engine's `performAt`. Without `performAt` the point must land on a listed control, which is tapped by id. | `tap` or `performAt` |
|
|
| `hover_at` | `x`, `y` | Hovers the same way: the bare point through `performAt`'s `hover` kind, otherwise a listed control under it by id. | the `hover` action or pointer kind |
|
|
| `drag_at` | `x`, `y`, `to_x`, `to_y` | Drags from the first point to the second through `performAt`'s `dragTo` kind. Without that kind the points must land on two different listed controls, which are dragged by id, or the call fails with `UNSUPPORTED_CAPABILITY`. | the `dragTo` action or pointer kind |
|
|
| `type_at` | `x`, `y`, `value`; `replace` on an engine with a keyboard | Fills a listed input under the point by id. With a keyboard, anything else is tapped to focus it and typed into, at the caret unless `replace` is set. Without one, a point on nothing listed fails. | `type` or a keyboard |
|
|
| `press_at` | `x`, `y`, `key` | Sends the key to a listed control under the point by id. With a keyboard, anything else is tapped to focus it and the key goes through the keyboard. | `press` or a keyboard |
|
|
| `select_at` | `x`, `y`, `value` (the option's visible label) | Picks the option in the listed select-like control under the point. Nothing listed there fails. | `select` |
|
|
|
|
<Note>
|
|
Before the session's first `screenshot`, each point tool answers with the
|
|
line that says to take one, at no cost.
|
|
</Note>
|
|
|
|
#### Recording
|
|
|
|
`start_recording` and `stop_recording` record a video of the app. Both are
|
|
listed when the engine records video.
|
|
|
|
```txt
|
|
call {tool: "start_recording", args: {name: "checkout-flow"}}
|
|
call {tool: "stop_recording"}
|
|
```
|
|
|
|
| Tool | Input | Does |
|
|
| --- | --- | --- |
|
|
| `start_recording` | `name` (optional): up to 64 letters, digits, `-`, and `_`, starting with a letter or digit | One recording at a time. A second start reports the one running. |
|
|
| `stop_recording` | none | Saves the video and returns each file's absolute path, or the URL where a provider keeps it. |
|
|
|
|
- A session records video only between `start_recording` and
|
|
`stop_recording`, as many times as needed. The configured
|
|
[`video`](/reference/config#video) mode applies to runs, not sessions, and
|
|
a session writes no [trace](/reference/config#trace).
|
|
- Each recording is saved to `<output>/videos/<session>/<n>[-<name>].webm`
|
|
(`.mp4` on mobile, and [`output`](/reference/config#output) is `.e2e` by
|
|
default), where `n` counts the session's recordings.
|
|
- A web recording that spans a restart or a state reset has one file per
|
|
page, `-part2`, `-part3`, and so on, in play order.
|
|
- A browser or device provider that records the lease itself records the
|
|
session instead. [Kernel](/integrations/kernel) downloads its replay, saved
|
|
here as `<n>[-<name>].mp4` like any other file. A provider that keeps its
|
|
recordings is listed by URL instead of a file.
|
|
- `close_session`, the idle timeout, and the session TTL save a recording
|
|
still running, and the close result lists its files.
|
|
|
|
<Warning>
|
|
Recordings are not masked: they are files for a person to watch, and no
|
|
tool returns their pixels. A secret typed into a plain input while
|
|
recording is readable in the video.
|
|
</Warning>
|
|
|
|
#### Project tools
|
|
|
|
Project tools in `agents.default.tools` follow in the catalog under their
|
|
own names, scoped to the target's platform. A mobile project that passes
|
|
`mobileTools(...)` also gets `open_app`, `swipe`, and `alert`.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `INVALID_CONFIG` | A project tool named like a built-in, at config load. |
|
|
| `UNKNOWN_TOOL` | A name not in the catalog. The message lists the names. |
|
|
|
|
## Setup
|
|
|
|
The server ships with `e2e`. `e2e init` offers to register it in
|
|
`.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), and
|
|
`.codex/config.toml` (Codex). Install dependencies and start the MCP client
|
|
in the project directory so `npx` (`bunx` in a Bun project) uses the installed e2e version. By hand:
|
|
|
|
<CodeGroup>
|
|
```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>
|
|
|
|
For clients that use a `mcpServers` config, add the entry shown above.
|
|
Codex reads the project's `.codex/config.toml` once the project is trusted.
|
|
Start a new session after registering it:
|
|
|
|
```toml title=".codex/config.toml"
|
|
[mcp_servers.e2e]
|
|
command = "npx"
|
|
args = ["e2e", "mcp"]
|
|
```
|
|
|
|
OpenCode reads the server from `mcp` in the project's `opencode.json`. See
|
|
the OpenCode tab in [MCP server](/mcp-server#set-it-up).
|
|
|
|
The server is also listed in the
|
|
[MCP Registry](https://registry.modelcontextprotocol.io) as
|
|
`io.github.e2e-inc/e2e`. A client that installs it from there runs the
|
|
listed release with `npx` and must start it in the project directory. The
|
|
project still needs e2e and its engine installed, since the config imports
|
|
them. A listed release on another version than the project's e2e can reject
|
|
config keys it does not know; the registration above always matches.
|
|
|
|
The server needs no model: a project without the optional `ai` package
|
|
opens sessions and drives the app with the deterministic tools. A test a
|
|
session [runs](#running-a-test) calls the configured model for an agent step
|
|
the replay cache cannot serve.
|
|
|
|
Start the server in the project directory. Config discovery works like
|
|
`e2e run`. For another config, see [`--config`](#config) and
|
|
[`open_session`](#open_session).
|
|
|
|
## Without a config
|
|
|
|
In a directory with no config file, `open_session` needs an `engine`. The
|
|
session has one target on that engine. Every other setting is at its
|
|
default, so the session has no credentials, secrets, or project tools.
|
|
|
|
```txt
|
|
open_session {engine: "@e2e-dev/web", app: {url: "http://localhost:3000"}}
|
|
open_session {engine: {package: "@e2e-dev/mobile", options: {platform: "ios"}}, app: {bundleId: "com.example.app"}}
|
|
```
|
|
|
|
A package name is enough for an engine that needs no options. To pass
|
|
options, or to name an export, write `engine` as an object:
|
|
|
|
| Field | Type | Does |
|
|
| --- | --- | --- |
|
|
| `package` | string | The package to load. It can carry a subpath, such as `@e2e-dev/testmu/web`. |
|
|
| `export` | string | The export to call. Default: the default export. |
|
|
| `options` | object | The options the factory takes, as in an `e2e.config.ts`. |
|
|
|
|
- **A package name alone** calls the package's default export with no
|
|
options. `@e2e-dev/web` and `@e2e-dev/mobile` export their factory this
|
|
way. [Your own engine](/writing-an-engine#open-it-by-name) can do the same.
|
|
- **An option can be another factory call.** The server reads an option
|
|
value as a call when it has `package` and no key other than `export` and
|
|
`options`. It makes that call first and passes the result as the option.
|
|
Use it to give an engine a device or browser provider:
|
|
|
|
```txt
|
|
open_session {
|
|
engine: {package: "@e2e-dev/mobile", options: {
|
|
platform: "ios",
|
|
device: {package: "@e2e-dev/limrun", export: "limrun", options: {region: "eu"}}
|
|
}},
|
|
app: {bundleId: "com.example.app"}
|
|
}
|
|
```
|
|
|
|
The call above builds
|
|
`mobile({ platform: 'ios', device: limrun({ region: 'eu' }) })`. The
|
|
provider reads its API key from the server's environment.
|
|
- **Lookup.** The server looks for each package in the project, then beside
|
|
the running `e2e`, then in `~/.e2e/engines`. When it is in none of them,
|
|
the error names the command that installs it for every project:
|
|
`npm install --prefix ~/.e2e/engines @e2e-dev/web`. An agent that cannot
|
|
run it, such as one in a sandbox without network access, asks you to.
|
|
- **`app`** takes `url`, `bundleId`, and `appPath`, as a target's
|
|
[`app`](/reference/config#the-app-under-test) does. `@e2e-dev/web` needs
|
|
`url`. `@e2e-dev/mobile` needs `bundleId` or `appPath`.
|
|
- **Files.** The project root is the server's working directory, and the
|
|
session writes `.e2e/` there.
|
|
- **Tests.** `e2e run` and `open_session {test}` need a config. To keep
|
|
the session's test lines as a test, write a config with
|
|
[`e2e init`](/reference/cli#e2e-init).
|
|
- **Several sessions.** Sessions opened with `engine` run side by side. A
|
|
session on a config doesn't open beside them and fails with
|
|
`CONFIG_IN_USE`.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `CONFIG_NOT_FOUND` | `open_session` without `engine`, and the directory has no config. |
|
|
| `ENGINE_NOT_INSTALLED` | A package that `engine` names is in none of the three lookup places. |
|
|
| `INVALID_ARGUMENT` | `package` is not a package name, `export` is not an export name, `engine` comes with `target`, `config`, or `test`, or the directory has a config. Also `app` without `engine`. |
|
|
| `INVALID_CONFIG` | The named export is not a function, a factory refused its `options`, the engine's factory returned no engine, or the engine refused `app`. For an export that is not a function, the message lists the package's functions. |
|
|
|
|
## Output
|
|
|
|
- Operator output goes to stderr, prefixed `e2e mcp:`. Stdout carries only
|
|
the protocol.
|
|
- What your code writes through `console`, `process.stdout`, or
|
|
`process.stderr` (the config's top-level code, project tools, a test a
|
|
session runs) goes to stderr with secret values redacted.
|
|
- Output printed while a config loads appears once it has loaded. If the
|
|
load fails, that output is withheld, since the config's secrets are
|
|
unknown.
|
|
- A promise a session's test leaves rejected fails that test, as in a run.
|
|
One that rejects after the test's body ended is an `UNHANDLED_REJECTION`
|
|
line in `close_session`'s result, and a warning on stderr once the session
|
|
has closed. Any other error nobody caught, a rejection before any session
|
|
has run a test included, is logged redacted and shuts the server down.
|
|
|
|
<Note>
|
|
A child process that inherits the server's stdio writes past this.
|
|
</Note>
|
|
|
|
## Sessions
|
|
|
|
A session is one attempt on one target. A `call` before any session is open
|
|
fails with `NO_SESSION`.
|
|
|
|
A session closes:
|
|
|
|
- on `close_session`,
|
|
- after 30 idle minutes,
|
|
- after 4 hours,
|
|
- when the client disconnects,
|
|
- on SIGINT or SIGTERM.
|
|
|
|
The idle and lifetime limits apply to sessions that open their own attempt.
|
|
|
|
The client disconnects when it closes the server's stdin or dies. Then every
|
|
session closes, the app commands the sessions started stop, and the server
|
|
exits.
|
|
|
|
Sessions enforce what tests enforce:
|
|
|
|
- Node ids are valid only against the newest observation.
|
|
- The single actions fill a secret only through `type_secret`.
|
|
[`run_code`](#run_code) fills one as a test does.
|
|
- Once the config has loaded, its secret values are redacted from every text
|
|
a tool returns, a node `locate` found, an action's result, an
|
|
`open_session` or `close_session` failure, a cleanup line, and the server's
|
|
own log lines.
|
|
- Nothing a session does is recorded as a test result. Only a test the
|
|
session runs reads or writes the replay cache
|
|
([Running a test](#running-a-test)). Its artifacts land under
|
|
`<output>/results/mcp/<target>-<attemptId>/`, its videos under
|
|
`<output>/videos/`. A later `e2e run` clears `<output>/results`; the videos
|
|
stay.
|
|
- A queued call cancelled by the client does not execute when its turn
|
|
arrives.
|
|
|
|
## Attaching to a held test
|
|
|
|
Use the ID in the pause header. It stays the same across holds of one
|
|
attempt. Start MCP from the run's directory with the same e2e version.
|
|
|
|
```txt
|
|
open_session {attach: "k3f9"}
|
|
```
|
|
|
|
Pass only `attach`. An attached session has the same tools as a normal
|
|
session on that target. Use `start_recording` and `stop_recording` to save
|
|
a video under `<output>/videos/<session>/`. If the run already records
|
|
the attempt, `start_recording` returns an error with the run's video
|
|
directory.
|
|
|
|
Use `close_session` to detach and leave the test held. The reply includes
|
|
the path of any recording saved on detach.
|
|
|
|
Press Enter or run `npx e2e run --step next` to resume the test and end the
|
|
attachment right away. Any recording still running saves in the background.
|
|
The runner logs the saved path or the error. The MCP server logs the same
|
|
result if it's still connected.
|
|
|
|
The report and trace record the test's own steps. App logs and screen
|
|
updates from an attached call can appear in the trace if they arrive after
|
|
the call ends.
|
|
|
|
## Running a test
|
|
|
|
`open_session {test}` runs one test of the project on the session's attempt,
|
|
then hands the session over on the screen where the test stopped. A coding
|
|
agent fixes a failing test from there without clicking through the flow
|
|
again.
|
|
|
|
```txt
|
|
open_session {test: "tests/checkout.e2e.ts:12"}
|
|
```
|
|
|
|
- **Selection.** `test` takes what `e2e run` takes as a positional: a file
|
|
with `:line` for the test declared on that line, a file, a directory, a
|
|
glob, or a name. It must select exactly one test on the session's target.
|
|
The line is the one the `test(` call is on; a line inside the test
|
|
selects nothing.
|
|
- **What runs.** The test's `beforeAll` hooks, its `test.extend()` fixtures,
|
|
its `beforeEach` hooks, and its body, with the same fixtures, locators,
|
|
`expect`, `timeout`, `actionTimeout`, and `assertionTimeout` as in a run.
|
|
The session does not open the app URL or launch the pinned app first; the
|
|
test opens the app itself.
|
|
- **Where it stops.** At the first failure, or at the end of the body. Nothing
|
|
is torn down. The opening text leads with the outcome: passed, or failed
|
|
with the code, the message, the failing line and the code around it, the
|
|
URL, the nodes nearest a locator that matched nothing, and the last 15
|
|
steps. The session summary, the catalog, and the screen follow.
|
|
- **Test lines.** The test's own steps print no [test line](#test_lines).
|
|
The session's lines start with the agent's first action, and `test_lines`
|
|
returns them as the lines that continue the test.
|
|
- **Teardown.** `afterEach` hooks, fixture teardowns, and `afterAll` hooks
|
|
run at `close_session`, or when the session closes on its own. Their
|
|
failures show as `Cleanup (afterEach)` and `Cleanup (afterAll)` lines.
|
|
- **Rerun.** `close_session`, then `open_session {test}` again. Each session
|
|
loads the config and the test files fresh, files they import included.
|
|
- **Replay cache.** The test reads and writes the cache as a run's first
|
|
attempt: steps replay, and a new recording is saved once a later check
|
|
passes. A failure evicts the entries no check confirmed. The cache settles
|
|
when the body ends, so an `afterEach` check confirms nothing.
|
|
[`cache.strict`](/reference/config#cache) holds as in a run.
|
|
- **Not part of it.** No test result, report, or trace page. Retries, and the
|
|
test's `trace` and `video` modes, don't apply. The failure screenshot and
|
|
`screen-at-failure.txt` land in the session's artifacts directory.
|
|
- **Screenshots.** Each session counts as a run of its own for
|
|
`toHaveScreenshot`: a baseline one session writes is compared against in
|
|
the next.
|
|
- **Several sessions.** Test code in two sessions takes turns: one session
|
|
runs its test or its teardown at a time, since `expect.poll`,
|
|
`expect.soft`, and `test.skip` find the running test through one slot per
|
|
process. An open cancelled while its test waits for its turn runs none of
|
|
the test's code.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `NO_TESTS` | `test` selects no runnable test. The message names the cause, as for `e2e run`. |
|
|
| `TEST_AMBIGUOUS` | `test` selects several tests. The message lists them as `file:line`. |
|
|
| `SESSION_TEST_UNSUPPORTED` | The test is in a serial group, starts from a setup test's `session`, or runs as several agents. |
|
|
| `COLLECTION_ERROR` | A test file fails to collect, as for `e2e run`. |
|
|
|
|
## Several sessions
|
|
|
|
Several sessions can be open at once, up to `--max-sessions`, each on its
|
|
own attempt and its own browser or device. Parallel agents, such as a
|
|
coding agent's subagents, share one server this way: each opens a session
|
|
and passes its id to every `tools`, `call`, and `close_session`.
|
|
[Bug bashes](/bug-bash) use this: a verifying subagent that hardens a repro
|
|
into a scripted test drives its own session.
|
|
|
|
| Throws | When |
|
|
| --- | --- |
|
|
| `SESSION_REQUIRED` | A call without `session` while several are open. The message lists the open sessions. |
|
|
| `NO_SESSION` | A `session` id that is not open. For a session that is closing or ended, the message says why. |
|
|
| `SESSION_OPEN` | An `open_session` past the limit, or while the server shuts down. |
|
|
| `CONFIG_IN_USE` | An `open_session` on another config while sessions are open, or on a config beside sessions opened with `engine`. |
|
|
| `ENGINE_IN_USE` | A second session on an engine created inside a package. |
|
|
| `CANCELLED` | An `open_session` the client cancelled or disconnected from, or the server shut down during, once what it started has stopped. |
|
|
|
|
- A session holds its slot from `open_session` until its attempt has closed,
|
|
so sessions still booting or still closing count toward the limit.
|
|
- Sessions open at once share one config: credentials and secrets resolve
|
|
through one registry per process.
|
|
- While the server shuts down it cancels sessions still opening and waits
|
|
for them, closes every session, and refuses new ones. A cancelled open
|
|
fails once what it started (an app command still waiting on its
|
|
`readyUrl`, say) has stopped.
|
|
- Each session loads the config afresh, down to the files it imports by
|
|
path, such as a base config it spreads, so each gets engine instances of
|
|
its own. A session that runs a test loads the test files the same way. An engine created inside a package is one instance every session
|
|
shares.
|
|
- Sessions on one app command share its process: the first session starts
|
|
it, and it stops when the last of them closes. A URL declared with port
|
|
`0` gets its own port in each session, and so its own process. A shared
|
|
start that every waiting session gave up on is cancelled, and the next
|
|
session starts it afresh.
|
|
- On mobile, each session needs its own simulator or emulator: declare one
|
|
target per device, each naming its `device`, and open each session on its
|
|
own target.
|
|
|
|
## Resources
|
|
|
|
| URI | Content |
|
|
| --- | --- |
|
|
| `e2e://guide` | The agent skill's overview, the text `e2e guide` prints. |
|
|
| `e2e://guide/{topic}` | One topic: `setup`, `writing-tests`, `agent`, `running`, `explore`, `debugging`, `mcp`, `bug-bash`. |
|
|
|
|
## Exit codes
|
|
|
|
| Code | When |
|
|
| --- | --- |
|
|
| `0` | The client disconnects, with or without a session open, or a signal ends it. |
|
|
| `1` | An uncaught error shuts the server down. |
|
|
| `2` | The command line is invalid. |
|
|
| The error's [category code](/reference/cli#exit-codes) | A startup failure. |
|
|
|
|
Config and engine failures come back as tool errors with the same codes the
|
|
CLI prints.
|