@e2edev/e2e 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e2edev/e2e",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "SDK, runner, and CLI for agentic end-to-end testing",
   "keywords": [
     "e2e",
@@ -51,12 +51,13 @@
     "skills"
   ],
   "dependencies": {
-    "@clack/prompts": "1.7.0",
+    "@clack/prompts": "1.8.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "@vitest/expect": "5.0.0",
     "commander": "15.0.0",
     "picocolors": "1.1.1",
     "tsx": "4.23.13",
-    "zod": "4.5.4"
+    "zod": "4.6.1"
   },
   "peerDependencies": {
     "ai": "^7.0.0"
@@ -68,14 +69,14 @@
   },
   "devDependencies": {
     "@ai-sdk/openai-compatible": "3.0.47",
+    "@e2edev/playwright": "0.9.0",
     "@openrouter/ai-sdk-provider": "3.0.0",
     "@types/node": "26.4.1",
-    "ai": "7.0.93",
+    "ai": "7.0.97",
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
     "typescript": "7.0.2",
-    "vitest": "5.0.0",
-    "@e2edev/playwright": "0.8.0"
+    "vitest": "5.0.0"
   },
   "engines": {
     "node": ">=22.12.0"

package/skills/e2e/SKILL.md

@@ -66,6 +66,7 @@ one. Without them, the installed CLI prints the same text:
 | `running` | [references/running.md](references/running.md) | CLI flags, reporters, `.e2e/report.json`, exit codes, CI |
 | `explore` | [references/explore.md](references/explore.md) | Exploring an app toward a goal without a test file: `e2e explore`, its budgets, verdict, and `run.explore` |
 | `debugging` | [references/debugging.md](references/debugging.md) | A run failed: error codes and their fixes, `--headed`, `--debug`, `--ai-trace` |
+| `mcp` | [references/mcp.md](references/mcp.md) | Driving the live app from a coding agent over MCP: `e2e mcp`, its tools, and the explore-then-write loop |
 
 ## Workflow
 
@@ -74,8 +75,10 @@ one. Without them, the installed CLI prints the same text:
    there: follow `setup`.
 2. Learn the screens you will drive before writing a test: routes, labels,
    roles, button text. Semantic locators need the accessible names the app
-   renders, so read the templates or components, or open the page with
-   `--headed`.
+   renders, so read the templates or components, open the page with
+   `--headed`, or drive the live app through the `e2e mcp` server when it is
+   registered (topic `mcp`): `open_session`, `observe`, and `locate` show the
+   exact names and check a locator before you write it.
 3. Write `tests/<feature>.e2e.ts`. Deterministic steps first. One `agent.act`
    per goal where the flow varies, and an `expect` on its outcome right after.
 4. Run one file: `npx --no-install e2e run tests/<feature>.e2e.ts`. Agent

package/skills/e2e/references/agent.md

@@ -6,7 +6,7 @@ transcript between calls. Deterministic tests never load a model.
 
 ## Configure a model
 
-Agents live under `agents` by name; `default` is the one tests use, `e2e run --agent <name>` re-points that default, a test or describe pins one with `{ agent: 'name' }`, and any `agent.*` call can name one with `{ agent: 'name' }` (innermost wins). There is no default model. Pick one of three shapes for an entry:
+Agents live under `agents` by name; `default` is the one tests use, `e2e run --agent <name>` re-points that default, a test or describe pins one with `{ agent: 'name' }` or several with `{ agent: ['buyer', 'admin'] }` (the test runs once per agent, one result each, tagged `[admin]` in the terminal and `agent` in the report), and any `agent.*` call can name one with `{ agent: 'name' }` (innermost wins). `--agent buyer,admin` runs every unpinned test once per agent; on a pinned list it narrows to the names both give and never overrides a pin it does not name. A signed-in persona pairs the pin with a `session`, one per describe block, so a loop over describe blocks sweeps signed-in personas. There is no default model. Pick one of three shapes for an entry:
 
 ```ts
 // e2e.config.ts
@@ -222,7 +222,7 @@ arbitrary tool result JSON or other fields are preserved.
   can be the `agent`; the runner still owns observations, actions, budgets,
   and the report.
 
-Full reference: https://e2e-docs.vercel.app/agents
+Full reference: https://e2e.mintlify.app/agents
 
 ## In CI
 

package/skills/e2e/references/explore.md

@@ -3,14 +3,14 @@
 `e2e explore` runs the agent against the app with a goal instead of a test
 file. Use it to see what the agent can do with an app before tests exist, to
 hunt for regressions on a branch, or to find what is worth turning into a
-test. It needs a config with a target and a model (on the agent, or
-`E2E_MODEL`), nothing else.
+test. It needs a config with a target and an agent that holds a model,
+nothing else.
 
 ```bash
 npx --no-install e2e explore                                         # goal: "Explore the app and find bugs"
 npx --no-install e2e explore 'Explore checkout like a first-time buyer and report anything off'
 npx --no-install e2e explore --target web --max-steps 4 --headed
-E2E_MODEL=provider/model-id npx --no-install e2e explore 'Hunt for broken forms' --video
+npx --no-install e2e explore 'Hunt for broken forms' --video
 ```
 
 ## What a run does

package/skills/e2e/references/mcp.md

@@ -0,0 +1,88 @@
+# Driving the app over MCP
+
+`e2e mcp` serves a project's live app to a coding agent over MCP (stdio).
+It gives the agent the same hands the testing agent has on the app: look at
+a screen before writing a test, and check a locator before committing to it.
+Running tests and reading a failed run stay on the CLI (topics `running` and
+`debugging`).
+
+## Setup
+
+The server ships with `@e2edev/e2e`. `e2e init` offers to register it; by
+hand:
+
+```bash
+claude mcp add e2e -- npx --no-install e2e mcp          # Claude Code
+```
+
+Or declare it in the client's project config (`.mcp.json` for Claude Code,
+`.cursor/mcp.json` for Cursor, `.vscode/mcp.json` for VS Code):
+
+```json
+{ "mcpServers": { "e2e": { "command": "npx", "args": ["--no-install", "e2e", "mcp"] } } }
+```
+
+Flags: `--config <path>` names the default config file, `--target <name>`
+fixes the target every session opens on, `--headless` hides the browser or
+simulator (sessions are headed by default outside CI, so the developer can
+watch).
+
+## Tools
+
+The server has four tools, and the list never changes. Everything a session
+can do is a catalog behind `call`.
+
+| Tool | Does |
+| --- | --- |
+| `open_session` | Loads the config (`config` names another file; default the nearest `e2e.config.ts`), starts the declared app command if any, boots the engine, opens the app URL, and returns the session id, the catalog, and the first observation. `target` is required when the config declares several. One session at a time. |
+| `tools` | The catalog: one line per tool with its argument names (`?` marks optional), the first sentence of its description, and `[read-only]` where it changes nothing. `tools {tool}` shows one tool's full description and the JSON Schema of its arguments. |
+| `call` | Runs one catalog tool: `call {tool: "tap", args: {target: "n42"}}`. Arguments are checked against the tool's schema first; a wrong one fails with `INVALID_ARGUMENT` naming the field. |
+| `close_session` | Ends the attempt, disposes the engine, stops the app processes the session started. |
+
+The catalog, per session:
+
+| Catalog tool | Does |
+| --- | --- |
+| `observe` | A fresh observation: one node per line as `#id role "name" ...`, plus the current path. |
+| `tap`, `type`, `press`, `select`, `scroll`, `navigate` | The grammar verbs, exactly as the testing agent gets them. Each reports what changed on screen; `observe` shows the whole screen. A verb the engine cannot honor is not listed and fails with `UNSUPPORTED_CAPABILITY`. |
+| `type_secret` | Fills a configured credential's password into a secure field by credential name; the plaintext never reaches the agent. Listed when the config declares `credentials`. |
+| `locate` | Tries a semantic locator (`role` + `name`, `text`, `label`, `placeholder`, `testId`, `exact`) and returns how many nodes match, which, and the `screen.*` call to write. |
+| `screenshot` | The masked pixels as an image, withheld once a secret was filled in the session. |
+| Project tools | Every `defineTool` passed to `createAgent({ tools })` that applies to the target's platform, under its own name; an engine pack such as `agentDeviceTools` adds `open_app`, `swipe`, `type_text`, `alert`. |
+
+Resources: `e2e://guide` and `e2e://guide/<topic>` hold this skill.
+
+## Workflow
+
+1. `open_session`, then `call {tool: "observe"}` and act until the screen you
+   want to test is in front of you. Node ids are valid only for the newest
+   observation; an action reports what changed, so observe again before
+   using new ids. The opening text lists every tool with its arguments;
+   `tools {tool}` when you need the full contract.
+2. `call {tool: "locate", args: {...}}` for each locator you intend to write.
+   One match: use the printed `screen.getByRole(...)` call. Zero or several:
+   adjust before writing the test, the same failure would hit the test as
+   `LOCATOR_NOT_FOUND` or `LOCATOR_AMBIGUOUS`.
+3. Write `tests/<feature>.e2e.ts` (topic `writing-tests`). Deterministic steps
+   where you saw exact names; `agent.act` where the flow varies.
+4. Run it from the shell: `npx --no-install e2e run tests/<feature>.e2e.ts`,
+   read the failure (topic `debugging`), fix, repeat.
+5. `close_session` when you are done exploring; an idle session closes on its
+   own after 30 minutes and never outlives 4 hours. To look at another
+   project or config, `open_session {config: "path/to/e2e.config.ts"}`; no
+   restart needed.
+
+## Rules
+
+- Sessions enforce the same policy as tests: navigation stays inside the
+  engine's allowed origins, secrets fill only through `type_secret`, and
+  pixels are withheld once a secret is on screen.
+- Nothing a session does is recorded as a test or into the trace cache. A
+  session is for looking and trying; the test is what you write afterwards.
+- A run from the shell and a live session can share the app only if the
+  engine's `command` uses `reuseExisting`; otherwise close the session before
+  running.
+- `TARGET_REQUIRED`: pass `target` to `open_session` or start with `--target`.
+  `NO_SESSION`: call `open_session` first. `SESSION_OPEN`: one is already
+  open; use it or `close_session`. `UNKNOWN_TOOL`: the name is not in this
+  session's catalog; the message lists what is.

package/skills/e2e/references/running.md

@@ -7,8 +7,9 @@ npx --no-install e2e run [files...] [options]   # run tests
 npx --no-install e2e explore [goal] [options]   # explore the app toward a goal, no test file (see the explore topic)
 npx --no-install e2e list [files...] [options]  # print what run would select, without running
 npx --no-install e2e init [--yes]               # scaffold a project, refresh the agent skill
-npx --no-install e2e guide [topic]              # print this skill: setup, writing-tests, agent, running, explore, debugging
+npx --no-install e2e guide [topic]              # print this skill: setup, writing-tests, agent, running, explore, debugging, mcp
 npx --no-install e2e cache ls|clear|stats       # read or empty the trace cache
+npx --no-install e2e mcp [--target <name>]      # serve the project to a coding agent over MCP (topic mcp)
 npx --no-install e2e telemetry [disable|enable] # anonymous usage telemetry: status, or the switch
 ```
 
@@ -21,7 +22,7 @@ npx --no-install e2e telemetry [disable|enable] # anonymous usage telemetry: sta
 | `--target <ids>` | Comma-separated target names. Only selected targets start app commands and services; unknown names fail before startup. |
 | `--tag <tag>` | Repeatable tag filter; `--tag-mode all` requires every tag. |
 | `--headed` | Visible browser or simulator when the engine supports it. |
-| `--agent <name>` | Run with another configured agent (`agents.<name>`); default is `agents.default`. |
+| `--agent <names>` | Run unpinned tests as other configured agents (`agents.<name>`), comma-separated or repeated; several names run each such test once per agent. Default is `agents.default`. |
 | `--workers <n>`, `--retries <n>` | Override the resolved values. |
 | `--reporter <ids>` | `list`, `json`, `junit`, comma-separated. `json` cannot combine with `list`. |
 | `--artifacts <dir>` | Artifact root, default `.e2e/artifacts`. |
@@ -71,7 +72,7 @@ recorded flow is stale — `--no-cache` only skips the cache for one run.
 
 - `list` (default): one line per file and target, a `Failed Tests` section
   with each error, its code, the failing line and a code frame, then a
-  summary (`Test Files`, `Tests`, `AI`, `Start at`, `Duration`, `Report`); setup steps (a first-run browser download, each service and app command) print above the tests and stay out of `Duration` or are split out of it as `(startup …)`.
+  summary (`Test Files`, `Tests`, `AI`, `Cache` when the trace cache was on: agent steps `replayed` whole, `handed off` to the model part-way, or `missed`, `Start at`, `Duration`, `Report`); setup steps (a first-run browser download, each service and app command) print above the tests and stay out of `Duration` or are split out of it as `(startup …)`.
 - `.e2e/report.json` is written on every run whatever the reporters:
   `run.status`, `run.exitCode`, `run.errors[]` (run-level failures such as
   `APP_UNREACHABLE`), and `run.results[]`, one per test and target, with

package/skills/e2e/references/setup.md

@@ -21,14 +21,15 @@ pnpm dlx @e2edev/e2e@beta init  # pnpm
 When `@e2edev/e2e` is already installed, run `npx --no-install e2e init`
 instead, so the installed version scaffolds.
 
-The wizard asks for the engine (Playwright by default; None and agent-device
-are the alternatives), whether to enable AI testing (adds `ai@^7.0.0` and
-`createAgent` to the config), which agent directories receive this skill
+The wizard asks for the engine (Web with Playwright by default; Mobile with
+agent-device and None are the alternatives), which model gateway agent steps
+use (adds AI SDK v7 and the provider package), which agent directories receive this skill
 (`.agents/skills/` and `.claude/skills/`), a confirmation of the files it
 will write, and whether to install. `--yes` skips every prompt (use it from
-scripts and from a shell without a TTY): Playwright, AI on, no installation,
-skill in both directories. The closing line prints the run command,
-`APP_URL=http://localhost:3000 npx --no-install e2e run` for Playwright, and
+scripts and from a shell without a TTY): Playwright, the Vercel AI Gateway,
+no installation, skill in both directories. The closing line prints the run
+command through the project's package manager,
+`APP_URL=http://localhost:3000 npm run test:e2e` for Playwright under npm, and
 suggests a `tsconfig.json` when the project has none.
 
 Init writes `package.json` (a private ESM package when missing; otherwise