e2e 0.17.0 → 0.18.0

package/docs/security.mdx

@@ -1,6 +1,7 @@
 ---
 title: Security model
 description: What the model can access, how the runner handles secrets, and the limits of its protections.
+icon: "shield-halved"
 ---
 
 Test code and configuration run with your operating-system permissions.
@@ -106,7 +107,9 @@ redaction and disables pixels for the rest of the attempt.
 After any secret fill, for the rest of the attempt, screenshot and pixel
 tools are unavailable, `app.screenshot()` is denied, and the runner omits
 assertion and failure screenshots. The app could display the value anywhere,
-beyond the field's masked rectangle.
+beyond the field's masked rectangle. An `act` or `vision: true` step whose
+semantic capture times out before the step does fails with `POLICY_DENIED`
+instead of reading a fallback screenshot.
 
 A test that restores a [session](#sessions) whose setup filled a secret keeps
 this protection. A setup that signs in without filling a secret, for example
@@ -130,13 +133,14 @@ password on screen is not masked in pixels.
 ### Redaction
 
 The runner replaces every occurrence of a registered secret value with
-`<secret:name>` in model input, reports, a worker process's console output,
-and the trace text of a session a secret was filled on or an engine option
-holds. That includes a value the test passes as a plain string rather than
-a `secrets.get()` handle: test and `describe` titles, step labels (an
-`app.open` URL, a locator's text), an `agent.act` or `agent.assert`
-instruction, the strings in `agent.act` params, `agentContext`, and an
-`e2e explore` goal. Titles are redacted as the test file is collected, so
+`<secret:name>` in model input, reports, what your code prints during
+`e2e run` (tests, the config's and test files' top-level code, reporters),
+trace text, and text downloads. That includes a value the test passes as a
+plain string rather than a `secrets.get()` handle: test and `describe`
+titles, step labels (an `app.open` URL, a locator's text), a `fill`, an
+`agent.act` or `agent.assert` instruction, the strings in `agent.act`
+params, `agentContext`, and an `e2e explore` goal. A plain string is not a
+secret fill: it is protected as text only, and screenshots stay available. Titles are redacted as the test file is collected, so
 the test id, `--grep`, the reporters, and the artifact and failure-page file
 names all see `<secret:name>`, and two titles in one file that differ only
 in a secret value are a duplicate title path. A custom executor's
@@ -155,6 +159,9 @@ replay cache descriptor, or an end anchor reads it. Redaction rewrites only
 what the runner reports; assertions still compare the text the page shows.
 Secret values and their cut parts never enter cache entries.
 
+Output printed while the config loads appears once it has loaded. If the
+load fails, that output is withheld, since the config's secrets are unknown.
+
 A static value shorter than 6 characters is `INVALID_CONFIG`, and a provider
 returning one fails the fill: every occurrence of so short a value would take
 ordinary text with it.
@@ -176,31 +183,30 @@ ordinary text with it.
   rule for text cut at a length limit.
 - A title is redacted when its file is collected, before any provider
   runs, so a value a secret provider returns is not redacted from titles.
-- A Playwright trace from a session no secret reached is kept as recorded,
-  so a value the test only spelled into a URL or a locator stays in its
-  text.
 - When tests run in the runner's own process, with the config or tests
   passed in memory by an embedding host, their console output is not
   redacted.
-- A Playwright trace from a session a secret reached, filled or held by the
-  engine, is rewritten before it is kept: any run of 8 or more characters of
-  a value, its whitespace collapsed or not, becomes `<secret:name>`, so unrelated text that shares 8 characters
-  with a value is masked too. A base64 or base64url run that decodes to a
-  value or such a fragment (a basic-auth header, a cookie, a token segment)
-  is replaced whole. After a fill, screencast frames are dropped; with only
-  an engine-held secret they are kept. An image the app served that
-  draws the secret survives. A trace the runner cannot rewrite is deleted and
+- A Playwright trace is rewritten before it is kept whenever its session
+  knows a secret value, filled or not: every static one, and a provider's
+  once the session resolved it. Any run of 8 or more characters of a value,
+  its whitespace collapsed or not, becomes `<secret:name>`, so unrelated
+  text that shares 8 characters with a value is masked too. A base64 or
+  base64url run that decodes to a value or such a fragment (a basic-auth
+  header, a cookie, a token segment) is replaced whole. After a fill,
+  screencast frames are dropped; otherwise they are kept. An image the app
+  served that draws the secret survives. A trace the runner cannot rewrite is deleted and
   the attempt records `TRACE_WITHHELD`.
 - A video masks nothing and is labeled `redaction: "incomplete"`. It is
   never recorded unless you ask. A recording a hosted browser or
   device service keeps stays with that service; the report holds only its
   URL.
-- A download is what the app served. Once a secret reached the session,
-  filled or held by the engine, a text download (`text/*` or JSON by file
-  extension) is rewritten the way trace text is and labeled
-  `redaction: "complete"`. Any other download, a binary or one from a
-  session no secret reached, is kept as served and labeled
-  `redaction: "incomplete"`.
+- A download is what the app served. When the session knows a secret
+  value, every whole occurrence of it in a text download (`text/*` or JSON
+  by file extension) is replaced, as in reports, and the download is labeled
+  `redaction: "complete"`. Fragments and base64 runs are matched in traces
+  only. Any other download, a binary, one that is not valid UTF-8 or cannot
+  be rewritten, or one from a session that knows no secret value, is kept
+  as served and labeled `redaction: "incomplete"`.
 - The `headers` a protected preview needs are recorded in the trace as
   request headers. Share that trace as you would the bypass secret.
 - `command.log` is captured as the process writes it.
@@ -258,9 +264,9 @@ project-relative path you configure.
 | --- | --- | --- |
 | `report.json` | The run record. Errors, reasoning excerpts, and action summaries pass the redactor. | complete |
 | `artifacts/.../*.png` | Screenshots. Secure fields are masked before screenshots are returned or saved as artifacts. | complete |
-| `artifacts/.../trace.zip` | Playwright trace, rewritten after a secret fill or when an engine option holds a secret; screencast frames are dropped after a fill only. | not-required, complete, or deleted |
+| `artifacts/.../trace.zip` | Playwright trace, rewritten whenever its session knows a secret value; screencast frames are dropped after a fill only. | not-required (no secret value), complete, or deleted |
 | `artifacts/.../*.webm`, `*.mp4` | Video, opt-in through `video` or `--video`; `retain-on-failure` keeps only the attempts that did not pass. | incomplete |
-| `artifacts/.../downloads/*` | Files the app served through a download. Text ones are rewritten after a secret fill or when an engine option holds a secret; the rest are kept as served. | complete or incomplete |
+| `artifacts/.../downloads/*` | Files the app served through a download. Text ones are rewritten whenever the session knows a secret value; the rest are kept as served. | complete or incomplete |
 | `artifacts/.../failure/screen.txt` | The redacted tree at the moment of failure. | complete |
 | `ai-trace.json` | Every model call, opt-in via `--ai-trace`. Prompts are the redacted ones the model saw; inline image bytes are replaced by their size. | as the prompt |
 | `sessions/<runId>/` | Encrypted sessions, deleted at cleanup. | encrypted |

package/docs/subscriptions.mdx

@@ -1,6 +1,7 @@
 ---
 title: Subscriptions
 description: Use your ChatGPT, GitHub Copilot, OpenCode Console, or SuperGrok subscription for agent steps.
+icon: "id-card"
 ---
 
 Use an existing subscription without a separate API key. Choose your plan

package/docs/telemetry.mdx

@@ -1,6 +1,7 @@
 ---
 title: Telemetry
 description: What the CLI sends, what it never sends, and how to turn it off.
+icon: "chart-line"
 ---
 
 The `e2e` CLI sends anonymous usage data so we can see which commands,
@@ -72,7 +73,7 @@ Who ran it:
 | Property | Value |
 | --- | --- |
 | `distinct_id` | A random id stored in the preferences file. CI uses `ci:<vendor>` instead, and a platform that runs e2e for its users uses `fleet:<name>` when it sets `E2E_TELEMETRY_FLEET` |
-| `project_id` | A hash derived from the repository's root commit, shared across full clones. Outside git or in a shallow clone, a hash of the project path with a random local salt. `null` in CI when no root commit is available |
+| `project_id` | A hash derived from the repository's root commit, shared across full clones. `null` outside git and in a shallow clone |
 | `session_id` | A random id for this one invocation |
 | `first_run`, `days_since_first_run` | Whether this command created the preferences file, and whole days since it was created. `null` in CI and in a fleet, where no machine persists, and for a preferences file from before the time was recorded |
 
@@ -181,16 +182,18 @@ listed above.
 ## In CI
 
 CI runs are attributed to the CI vendor rather than to a machine, no
-preferences file is written on the runner, and no notice is printed. Set
-`E2E_TELEMETRY_DISABLED: '1'` in the job's `env` to send nothing from CI.
+preferences file is written on the runner, and no notice is printed. A coding
+agent that sets `CI` in its shell, with no CI vendor around it, counts as the
+machine it runs on. Set `E2E_TELEMETRY_DISABLED: '1'` in the job's `env` to
+send nothing from CI.
 
 ## In a fleet
 
 A platform that runs e2e on its users' behalf starts each run on a fresh
 machine, and every fresh machine would otherwise count as a new user. Set
 `E2E_TELEMETRY_FLEET=<name>` in those machines and they are attributed to
-`fleet:<name>` instead, like CI: no preferences file, no notice, and no
-project id outside git. Or set `E2E_TELEMETRY_DISABLED=1` and send nothing.
+`fleet:<name>` instead, like CI: no preferences file and no notice. Or set
+`E2E_TELEMETRY_DISABLED=1` and send nothing.
 
 ## Where it goes
 

package/docs/tools.mdx

@@ -1,6 +1,7 @@
 ---
 title: Project tools
 description: Add tools for test APIs, data setup, and device operations.
+icon: "screwdriver-wrench"
 ---
 
 Put tools in an agent's `tools` so the agent can call your test API or perform

package/docs/{starting-your-app.mdx → web.mdx}

@@ -1,13 +1,21 @@
 ---
-title: Starting your app
-description: Point the runner at a running app, or let it start the app for the run.
+title: Web
+description: Point the web engine at your app or let the runner start it, and run a suite at several viewport sizes.
+icon: "globe"
 ---
 
+`@e2e-dev/web` runs tests in a browser against your app's URL. This page
+covers getting the app running for a run and testing it at different
+sizes. For routes, cookies, dialogs, downloads, and the rest of the
+`browser` fixture, see [Working with the browser](/browser).
+
+## Starting your app
+
 Set your app's URL in the target's `app`. If you also provide a start
 command, the runner starts the app, waits until it is ready, and stops it
 when the run ends.
 
-## Point at a running app
+### Point at a running app
 
 Import `web` from `@e2e-dev/web` and put this in the exported
 config object:
@@ -25,7 +33,7 @@ export default {
 you can change the address for a run without editing the file. URLs without
 a scheme use HTTPS, or HTTP for loopback hosts.
 
-## Let the runner start it
+### Let the runner start it
 
 Add `app.command` and the runner spawns the dev server, waits until `app.url`
 answers, and stops it when the run ends, fails, or is interrupted:
@@ -79,7 +87,7 @@ temp-directory variables, and `env`, so pass what the app needs explicitly.
 See the
 [command reference](/reference/config#command) for all options.
 
-### Let the runner pick the port
+#### Let the runner pick the port
 
 Use port `0` to run multiple checkouts without a port conflict. The runner
 chooses a free port and replaces `{port}` in the command's `args` and `env`.
@@ -98,7 +106,7 @@ valid when the port changes. Use `127.0.0.1` or `[::1]`, matching the address
 the command binds; `localhost:0` is rejected. See
 [free ports](/reference/config#free-ports) for details.
 
-### Next.js dev targets
+#### Next.js dev targets
 
 Next.js 16 blocks cross-origin requests to its dev resources. A target that
 opens `127.0.0.1` or `[::1]` while `next dev` identifies as `localhost`
@@ -122,7 +130,7 @@ Use `'[::1]'` in the list when `app.url` opens `http://[::1]:0`.
 A target on `localhost` needs no entry, because `next dev` identifies as
 `localhost`. A production `next start` target is unaffected either way.
 
-## Dependencies
+### Dependencies
 
 <Note>
 This version starts only `app.command` (one process for every target that
@@ -132,7 +140,7 @@ have `app.command` start a script that brings them up and serves the app. A
 services API returns in a later release.
 </Note>
 
-## Several targets
+### Several targets
 
 Two browsers on one app are two targets that each name it:
 
@@ -155,9 +163,9 @@ test runs on every target unless it is scoped with `platforms` or
 `requires`; `--target <name>` selects at run time. A device target sits
 beside a browser target in the same list; see the
 [Mobile engine reference](/reference/mobile). One target per screen size is
-how a suite runs at several [viewports](/viewports).
+how a suite runs at several [viewports](#viewports).
 
-## Protected previews
+### Protected previews
 
 Use `headers` to access protected previews or skip a tunnel's interstitial
 page. For example, a Vercel preview can use a protection bypass header:
@@ -221,11 +229,149 @@ workers. Playwright traces include request headers, so a protected-preview
 trace can contain your bypass secret. Restrict access to those traces.
 </Note>
 
+## Viewports
+
+Set a viewport on the target to run a suite at that size. Use
+`browser.setViewport()` to resize during a test. The agent uses the current size
+and cannot resize it.
+
+### One size per target
+
+`viewport` sets the initial size of each attempt, in pixels. The default is
+1280 by 720. Add one target for each size you want to test:
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { web } from '@e2e-dev/web';
+
+const app = { url: 'http://localhost:3000' };
+
+export default {
+  targets: [
+    { name: 'desktop', engine: web(), app },
+    { name: 'tablet', engine: web({ viewport: { width: 820, height: 1180 } }), app },
+    { name: 'phone', engine: web({ browser: 'webkit', viewport: { width: 390, height: 844 } }), app },
+  ],
+} satisfies E2EConfig;
+```
+
+Each test runs once per target, with a separate result labeled `desktop`,
+`tablet`, or `phone`. Run one size with `npx e2e run --target phone`, or list
+the selected test-target pairs with `npx e2e list`.
+
+To have the runner start one dev server for every size, give every target
+the same `app.command`: targets declaring one command share one process; see
+[several targets](#several-targets). Every retry starts at
+the target's configured size.
+
+### Fill the window
+
+`viewport: null` sets no size, so the page fills the browser window. The
+agent, screenshots, and videos use that size. Use it in a headed run, or
+with a hosted browser whose live view would show a fixed 1280 by 720 page
+in one corner:
+
+```ts title="e2e.config.ts"
+{ name: 'window', engine: web({ viewport: null }), app }
+```
+
+The page takes the window's size, minus the toolbar in a headed browser. A
+local headed launch opens a small window; a hosted browser uses the window
+size you requested from the service. `browser.setViewport` still works.
+
+### Resize inside a test
+
+`browser.setViewport` resizes the page for the rest of the attempt, through
+`app.restart()` and `app.clearState()`:
+
+```ts
+import { test } from '@e2e-dev/web';
+import { expect } from 'e2e';
+
+test('the menu collapses on a narrow screen', async ({ app, screen, browser }) => {
+  await app.open('/');
+  await expect(screen.getByRole('navigation')).toBeVisible();
+
+  await browser.setViewport({ width: 390, height: 844 });
+  await expect(screen.getByRole('button', 'Menu')).toBeVisible();
+  await expect(screen.getByRole('navigation')).toBeHidden();
+});
+```
+
+Use this when one test needs to check a layout before and after resizing.
+For a whole suite, configure separate targets instead.
+
+Call it before `app.open` to load the first page at that size, so the app
+never renders its desktop layout first:
+
+```ts
+await browser.setViewport({ width: 390, height: 844 });
+await app.open('/');
+```
+
+The resize appears as a step in the report. To check the exact width, read
+it from the page:
+
+```ts
+const width = await browser.evaluate(() => window.innerWidth);
+expect(width).toBe(390);
+```
+
+### What the agent sees
+
+The agent receives the current viewport size with each observation.
+Screenshots cover that viewport. Off-screen elements can still appear in
+the tree, and tapping them scrolls them into view. The agent can scroll to
+reveal lazy-loaded content.
+
+Resize before calling `agent.act`:
+
+```ts
+test('the mobile menu reaches pricing', async ({ app, agent, browser }) => {
+  await browser.setViewport({ width: 390, height: 844 });
+  await app.open('/');
+  await agent.act('open the navigation menu and go to Pricing');
+  await expect(browser).toHaveURL('/pricing');
+});
+```
+
+### Scoping a test to one size
+
+`platforms` and `requires` cannot select a viewport; all Playwright targets
+use platform `web`. To skip a test at some sizes, check the width in the
+test:
+
+```ts
+test('the sidebar stays open', async ({ app, screen, browser }) => {
+  await app.open('/');
+  test.skip((await browser.evaluate(() => window.innerWidth)) < 768, 'desktop layout only');
+  await expect(screen.getByRole('complementary')).toBeVisible();
+});
+```
+
+To keep a whole group of size-specific tests apart, give them their own
+config and run it with `--config`.
+
+### Limits
+
+A narrow viewport tests responsive layout. It still uses a desktop browser
+with a scale factor of 1, desktop pointer behavior, and its usual user agent.
+It does not emulate touch, color scheme, or reduced-motion preferences.
+Use the [device engine](/mobile) for tests on a simulator or emulator.
+
+A video keeps the size the page had when it started recording; set
+`web({ screencast: { size } })` for one fixed size. A browser provider that
+records, such as [Kernel](/integrations/kernel#recordings), records the whole
+screen instead.
+
 <CardGroup cols={2}>
+  <Card title="Working with the browser" icon="globe" href="/browser">
+    Routes, cookies, dialogs, downloads, and the rest of the `browser` fixture.
+  </Card>
   <Card title="Config reference" icon="sliders" href="/reference/config#the-app-under-test">
     `app`, `command`, and every app key.
   </Card>
   <Card title="Web engine reference" icon="masks-theater" href="/reference/web">
-    Browser, viewport, `connect`, `headers`, `basicAuth`.
+    Browser, viewport, `connect`, `headers`, `basicAuth`, and every `browser` method.
   </Card>
 </CardGroup>

package/docs/writing-an-engine.mdx

@@ -1,6 +1,7 @@
 ---
 title: Writing an engine
 description: Implement the e2e engine contract for another UI platform.
+icon: "gear"
 ---
 
 An engine connects `screen`, `app`, and agent calls to a UI platform through
@@ -40,7 +41,7 @@ the engine's capabilities when the config loads.
 This skeleton assumes a `createClient` adapter for your platform. Its nodes
 must follow the semantic tree contract described below.
 
-```ts title="src/index.ts"
+```ts title="src/index.ts" expandable
 import { ConfigurationError, defineEngine, resolveExpression, type EngineHandle } from 'e2e/engine';
 
 export function hyperdrive(options: { device: string }): EngineHandle {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "e2e",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "SDK, runner, and CLI for agentic end-to-end testing",
   "keywords": [
     "e2e",
@@ -79,14 +79,18 @@
     "NOTICE"
   ],
   "dependencies": {
-    "@ai-sdk/provider": "4.0.18",
+    "@ai-sdk/provider": "4.0.21",
     "@clack/prompts": "1.8.1",
-    "@modelcontextprotocol/server": "2.2.0",
-    "@vitest/expect": "5.0.2",
+    "@jridgewell/remapping": "2.3.5",
+    "@modelcontextprotocol/server": "2.3.0",
+    "@oxc-project/runtime": "0.152.0",
+    "@vitest/expect": "5.0.3",
     "commander": "15.0.0",
+    "get-tsconfig": "4.14.3",
+    "oxc-parser": "0.152.0",
+    "oxc-transform": "0.152.0",
     "picocolors": "1.1.1",
     "pngjs": "7.0.0",
-    "tsx": "4.23.14",
     "zod": "4.6.1"
   },
   "peerDependencies": {
@@ -123,7 +127,7 @@
     "@ai-sdk/openai": "4.0.71",
     "@ai-sdk/openai-compatible": "3.0.53",
     "@ai-sdk/xai": "5.0.4",
-    "@e2e-dev/web": "0.12.0",
+    "@e2e-dev/web": "0.13.0",
     "@modelcontextprotocol/client": "2.2.0",
     "@openrouter/ai-sdk-provider": "3.1.0",
     "@types/node": "26.6.2",
@@ -135,7 +139,7 @@
     "vitest": "5.0.1"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": "^22.22.3 || >=24.8.0"
   },
   "scripts": {
     "build": "node scripts/prepare-build.ts && tsc --project tsconfig.build.json && node scripts/write-sibling-versions.ts && node ../../scripts/stamp-dist.ts",

package/skills/e2e/SKILL.md

@@ -61,7 +61,9 @@ one; the installed CLI prints the same text with `npx e2e guide <topic>`
 (`e2e guide` alone prints this page). For anything the topics do not cover,
 the full documentation ships in the `docs/` directory of the installed `e2e`
 package (`node_modules/e2e/docs` in a single-package project); a link such as
-`/reference/cli` is `docs/reference/cli.mdx`.
+`/reference/cli` is `docs/reference/cli.mdx`. Complete projects for Vite,
+Next.js, Expo, and SwiftUI, each with its config, scripts, and a passing
+suite, are in https://github.com/tester-army/e2e/tree/main/examples.
 
 | Topic | File | Read it when |
 | --- | --- | --- |

package/skills/e2e/references/agent.md

@@ -29,6 +29,14 @@ Subscription logins and local models:
 [setup](setup.md#subscriptions-and-api-keys). Keep `ai@^7` installed with
 any provider.
 
+Decision models pick actions from choices the executor builds: install
+`@e2e-dev/decision` and put `decisionExecutor({ model:
+typeSafeAi.decisionModel('jev-latest'), textModel: openrouter('inception/mercury-2.5') })`
+under `executor`. Tests stay plain language with no params; the text model
+writes field values. See the shipped `docs/decision-models.mdx` or
+[the online guide](https://e2e.tester.army/docs/decision-models) for setup,
+gates, and limits.
+
 - Pass a model instance, not a string (`INVALID_CONFIG`).
 - An agents entry is one plain object of `model`, `judge`, `system`,
   `context`, `tools`, `maxSteps`, `maxModelCalls`, `judgmentTimeout`,
@@ -162,6 +170,9 @@ expect(data.titles).toContain('Buy milk');
 - Judgments see the assertion and the current screen only, never prior
   steps or the act loop's summaries; malformed output gets one repair
   round, then `MODEL_OUTPUT_INVALID`.
+- A value shown in more than one place (a total in the summary and on the
+  pay button) must agree everywhere, or the judgment fails. Name the one
+  you mean (`'the order summary total is $42.00'`) when only it matters.
 - `waitFor` observes every `interval` (default 3 s), judges only when the
   screen changed, and is `STEP_TIMEOUT` after `timeout` (default 30 s).
 - `extract` takes any Standard Schema validator (zod works); the model sees

package/skills/e2e/references/debugging.md

@@ -65,7 +65,7 @@ jq '.run.results[] | select(.selected and .status != "passed") | .attempts[-1]
 | `AUTOMATION_UNSUPPORTED` | The step needs an interaction the engine's toolset lacks (drag on a device, say); blocked, exit 1 | Do that step with `screen` actions, or run the test on a target that supports it |
 | `STEP_TIMEOUT`, `STEP_BUDGET_EXHAUSTED` | Goal too big or ambiguous, or a slow provider | Split the goal, use on-screen wording, add vocabulary via `agents.<name>.context` or `agentContext`; raise `maxSteps` or `maxModelCalls` (budget), the config `timeout` (`act`), `judgmentTimeout` (judgments); `--debug` |
 | `CONTEXT_OVERFLOW` | Screen plus step history did not fit the model's context window (`act` after one shrink-and-retry; a judgment on the first overflow) | Lower `agents.<name>.maxObservationBytes`, split the step, or pick a larger-window model |
-| `POLICY_DENIED` | A URL whose scheme is not `http:` or `https:` (`file:`, `view-source:`, `data:`); a password `Secret` into a non-password sink; reading a secure field, `toHaveValue`, `toHaveText`, `toContainText`, `toHaveAttribute` included; `app.screenshot()` after a secret fill | http(s) or `about:blank` only; passwords into password inputs only; assert the outcome, not the value; screenshot before filling secrets |
+| `POLICY_DENIED` | A URL whose scheme is not `http:` or `https:` (`file:`, `view-source:`, `data:`); a password `Secret` into a non-password sink; reading a secure field, `toHaveValue`, `toHaveText`, `toContainText`, `toHaveAttribute` included; `app.screenshot()` after a secret fill, or an `act` or `vision: true` step whose tree read timed out after one | http(s) or `about:blank` only; passwords into password inputs only; assert the outcome, not the value; screenshot before filling secrets |
 | `UNSUPPORTED_CAPABILITY` | A fixture the engine lacks (`browser` on a device), `schema` or `vision` on `act`, an action the surface lacks | Declare `requires: ['browser']`; drop the option or action |
 | `SESSION_UNAVAILABLE`, `SESSION_CONTRACT` | `session: 'x'` with no setup saving `x`; a setup that skipped a declared name. `SESSION_MISMATCH`, `SESSION_EXPIRED`, `SESSION_INVALID`: the stored session is another run's or app's, expired, or corrupt | Add or fix the `test.setup`; rerun it |
 | `ONLY_IN_CI` | `test.only` reached CI | Remove it |

package/skills/e2e/references/mcp.md

@@ -24,8 +24,9 @@ No model is needed: without the optional `ai` package, sessions open and the
 deterministic tools work.
 
 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), `--max-sessions <n>`
+fixes the target every session opens on, `--headed` shows the browser or
+simulator when the engine supports it in sessions that do not set `headed`
+(sessions are headless by default, as in `e2e run`), `--max-sessions <n>`
 sets how many sessions may be open at once (default 4, 1 through 16).
 
 ## Tools
@@ -34,7 +35,7 @@ Four tools; 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. Each session has its own browser or device. |
+| `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. `headed: true` shows the browser or simulator when the user wants to watch; without it the session follows the server's `--headed`, headless by default. Each session has its own browser or device. |
 | `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 the 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` | Saves a recording still running, ends the attempt, disposes the engine, stops the app processes the session started once no other session uses them. |
@@ -57,6 +58,10 @@ The catalog, per session:
 | `stop_recording` | Stops it and returns the absolute path of each video file, under `<output>/videos/<session>/` (`.e2e` by default), or the URL of a provider's own recording. |
 | Project tools | Every `defineTool` in the agent's `tools` that applies to the target's platform, under its own name; an engine pack such as `mobileTools` adds `open_app`, `swipe`, `alert`. |
 
+Project tools use their `toModelOutput` renderer for strings as well as
+structured results. Its `error-text` and `error-json` outputs set the MCP
+result's `isError: true`; treat them as failed calls.
+
 Once a secret is filled in the session, `screenshot` and the point tools
 (`tap_at`, `hover_at`, `type_at`, `press_at`, `select_at`) answer with a
 `PIXEL_TAINTED` line for the rest of it; act on listed nodes by id (topic

package/skills/e2e/references/running.md

@@ -67,6 +67,7 @@ npx e2e list tests/signup.e2e.ts --tag smoke --reporter json
 With a `package.json` script `"test:e2e": "e2e run"`, pnpm forwards `--`
 literally: `pnpm test:e2e -- --headed` reaches e2e as `run -- --headed` and
 exits 2. Write `pnpm test:e2e --headed` or `pnpm exec e2e run --headed`.
+With npm, use `npm exec -- e2e run --headed` to pass flags to e2e.
 
 ## The replay cache
 
@@ -176,7 +177,7 @@ jobs:
       - uses: pnpm/action-setup@9fd676a19091d4595eefd76e4bd31c97133911f1 # v4.2.0
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: 26 # any Node >= 22.12
+          node-version: 26 # Node >= 24.8, or >= 22.22.3 on 22
           cache: pnpm
       - run: pnpm install --frozen-lockfile
       - run: pnpm exec e2e-web install chromium --with-deps

package/skills/e2e/references/setup.md

@@ -2,10 +2,13 @@
 
 ## Requirements
 
-- Node.js 22.12 or newer.
+- Node.js 24.8 or newer, or 22.22.3 or newer on Node.js 22.
 - ES modules: `.ts` config, tests, helpers, and workspace packages exporting
   `.ts` source load as ESM regardless of the nearest `package.json` `type`
   (CommonJS packages need no change); never `require` or `module.exports`.
+  Imports follow TypeScript: `./x.js` or `./x` loads `x.ts`, and the nearest
+  `tsconfig.json` `paths` and `baseUrl` apply. Decorators need
+  `experimentalDecorators`; CommonJS TypeScript goes in `.cts`.
 - Browser tests: `@e2e-dev/web`, pinning `playwright-core` exactly; do not
   add `playwright` for it. Missing browsers download on first boot; in CI run
   `npx @e2e-dev/web install chromium --with-deps` (pnpm: `pnpm exec e2e-web
@@ -354,3 +357,8 @@ export default {
 - `.gitignore` lists the `.e2e/` outputs (init adds them); drop the
   `.e2e/cache/` line to commit replays.
 - CI runs the whole suite, agent steps included, on PRs; see `running`.
+
+### Existing MCP registration
+
+Re-running `init` preserves the e2e MCP server's environment and client settings
+while repairing its launch command. A current registration is left unchanged.

package/skills/e2e/references/writing-tests.md

@@ -203,7 +203,7 @@ field and types one character per `delay`, plain string only (a `Secret` is
 Coordinates are CSS pixels, for what the tree does not list: `tap({ position:
 { x, y } })` offsets from the node's top-left corner (with `modifiers` it is
 `INVALID_ARGUMENT`), `screen.tapAt({ x, y })` taps a viewport point,
-`screen.swipe({ from, to })` swipes along a path,
+`screen.swipe({ from, to, duration? })` swipes along a path,
 `screen.swipe({ direction, momentum? })` swipes the viewport. Prefer a
 locator; a point moves with the layout.