e2e 0.15.2 → 0.17.0

package/docs/reference/web.mdx

@@ -7,9 +7,10 @@ description: The browser engine, its options, and the browser fixture it contrib
 A web target names it as its engine, and it contributes the `browser` fixture for
 browser-only work. Import `test` from the package to have `browser` typed.
 
-The package declares `playwright` as a peer dependency (`>=1.63.0 <2`) and
-does not install it. An app that already depends on Playwright keeps its
-version; `e2e init` adds `playwright` only to a project that has none.
+The package depends on `playwright-core` pinned to an exact version, so the
+engine always runs the Playwright it was tested against. An app that depends
+on Playwright itself keeps its own copy; the two share a browser cache only
+when their versions match.
 
 ```ts title="e2e.config.ts"
 import type { E2EConfig } from 'e2e';
@@ -20,6 +21,31 @@ export default {
 } satisfies E2EConfig;
 ```
 
+## Installing browsers
+
+A missing browser downloads once per run, before the run's clock starts. To
+install browsers as their own step, in CI or a container image, run the
+package's command. It installs the browsers for the Playwright version the
+engine pins:
+
+<CodeGroup>
+```bash npm
+npx @e2e-dev/web install chromium --with-deps
+```
+
+```bash pnpm
+pnpm exec e2e-web install chromium --with-deps
+```
+
+```bash bun
+bunx @e2e-dev/web install chromium --with-deps
+```
+</CodeGroup>
+
+Name any of `chromium`, `firefox`, and `webkit`; with none named it installs
+`chromium`. `--with-deps` also installs the system libraries the browsers need
+on Linux. The command exits with the installer's exit code.
+
 ## Options
 
 ```ts
@@ -82,8 +108,27 @@ export interface WebOptions {
    * (`connect.reconnectEndpoint`, or a provider with `scope: 'attempt'`).
    */
   readonly userAgent?: string;
+  /**
+   * The locale every attempt's context runs in, a BCP 47 tag such as
+   * `de-DE`: what `navigator.language`, `Intl` formatting, and the
+   * `Accept-Language` header report. Defaults to the browser's own. An
+   * `accept-language` entry in `headers` beside it is `INVALID_CONFIG`, and
+   * so is a persistent context.
+   */
+  readonly locale?: string;
+  /**
+   * The IANA time zone every attempt's context runs in, such as
+   * `Europe/Berlin`: what `Date` and `Intl` resolve local time against.
+   * Defaults to the machine's. A persistent context is `INVALID_CONFIG`.
+   */
+  readonly timezoneId?: string;
+  /** Scripts every document runs before the page's own. See [Init scripts](#init-scripts). */
+  readonly initScripts?: readonly WebInitScript[];
 }
 
+/** JavaScript source, a file relative to the project root, or a function. */
+export type WebInitScript = string | { readonly path: string } | (() => unknown);
+
 /** The engine's screencast of the page: the frame size and the JPEG quality of the frames it encodes. */
 export interface WebScreencastOptions {
   /** Frame size in pixels; default the viewport's, or the window's under `viewport: null`. A smaller size makes a smaller file. */
@@ -180,7 +225,7 @@ recording resume, but a segment lost during the disconnect cannot be recovered.
 Code using `surfaceOf(engine)` must read its accessors again after recovery;
 previously retained Playwright objects belong to the disconnected transport.
 
-Persistent recovery does not support `headers`, `basicAuth`, `userAgent`, `app.clearState`,
+Persistent recovery does not support `headers`, `basicAuth`, `userAgent`, `locale`, `timezoneId`, `app.clearState`,
 or session state capture and restore. `app.restart` remains available. Omit
 `reconnectEndpoint` to keep ordinary isolated contexts and the existing behavior.
 A `browser` provider with `scope: 'attempt'` rides the same persistent
@@ -202,7 +247,7 @@ a page acts on that tab: `goto`, `reload`, `back`, `forward`, `url`, `title`,
 `waitForURL`, `locator`, `frameLocator`, `evaluate`, `waitForResponse`,
 `waitForDownload`, `keyboard`, `mouse`, the `expect(browser)` matchers, and
 every `screen` query. What belongs to the browser covers every tab:
-`cookies`, `setCookies`, `route`, `unroute`, and `onDialog`. `setViewport`
+`cookies`, `setCookies`, `route`, `unroute`, `onDialog`, and `addInitScript`. `setViewport`
 sizes the active tab and every tab opened after it.
 
 A tab the app opens itself, from a `target="_blank"` link or `window.open`,
@@ -253,6 +298,10 @@ export interface Browser extends Expectable<BrowserExpectation> {
     fn: string | ((arg: Arg) => T | Promise<T>),
     arg: Arg,
   ): Promise<T>;
+  /** Adds a script every document runs before the page's own, from the next navigation on. */
+  addInitScript(script: string | { path: string } | (() => unknown)): Promise<void>;
+  /** Adds an init script function called with one JSON argument. */
+  addInitScript<Arg extends JsonValue>(script: (arg: Arg) => unknown, arg: Arg): Promise<void>;
   /** Adds an attempt-scoped network route. */
   route(
     pattern: string | RegExp,
@@ -308,7 +357,7 @@ export interface Browser extends Expectable<BrowserExpectation> {
 | `goto`, `reload`, `back`, `forward` | `config.timeout`, 120000 ms, the same budget `app.open()` uses; `{ timeout }` overrides, capped by the test deadline |
 | `waitForResponse`, `waitForDownload` | `config.actionTimeout`, 30000 ms; `{ timeout }` overrides, capped by the test deadline |
 | `waitForURL` | `config.assertionTimeout`, 5000 ms |
-| `url`, `title`, `evaluate`, `route`, `unroute`, `cookies`, `setCookies`, `setViewport`, `onDialog`, `keyboard.*`, `mouse.*` | `config.actionTimeout`, 30000 ms, not overridable |
+| `url`, `title`, `evaluate`, `addInitScript`, `route`, `unroute`, `cookies`, `setCookies`, `setViewport`, `onDialog`, `keyboard.*`, `mouse.*` | `config.actionTimeout`, 30000 ms, not overridable |
 
 Every `browser` call is a recorded `browser.<method>` step, except `locator` and
 `frameLocator`: they build a locator without touching the page, and the
@@ -319,10 +368,12 @@ in a suite that also runs on other platforms.
 ### Navigation
 
 `goto` defaults `waitUntil` to `'load'` and throws `POLICY_DENIED` for a
-`file:`, `data:`, or `javascript:` URL. `waitForURL` polls every 100 ms; a
+URL whose scheme is not `http:` or `https:` (`about:blank` is admitted). `waitForURL` polls every 100 ms; a
 relative string resolves against the base URL and matches exactly after
 normalization, a `RegExp` tests the full URL, anything else (a predicate
-function, say) is `INVALID_ARGUMENT`, and a timeout is `ASSERTION_FAILED`. The other navigations throw `ACTION_FAILED`.
+function, say) is `INVALID_ARGUMENT`, and a timeout is `ASSERTION_FAILED`. It
+takes `timeout` only: another key, such as Playwright's `waitUntil`, is
+`INVALID_ARGUMENT`. The other navigations throw `ACTION_FAILED`.
 
 ```ts
 await browser.goto('/dashboard', { waitUntil: 'networkidle' });
@@ -337,7 +388,9 @@ await browser.waitForURL(/\/orders\/\d+$/, { timeout: 15_000 });
 The selector is a Playwright selector: CSS by default, XPath with `xpath=` or
 a leading `//`, and `>>` chains, so
 `browser.locator('[data-testid="row"] >> nth=2 >> [data-testid="conditions"] > div')`
-scopes CSS to one row.
+scopes CSS to one row. A `*` capture before the last part
+(`*css=article >> text=Hello`) is `INVALID_LOCATOR`: use
+`filter({ has })` for an element that contains another.
 
 ```ts
 const payment = browser.frameLocator('#payment-frame');
@@ -387,16 +440,49 @@ const flag = await browser.evaluate(
 );
 ```
 
+### Init scripts
+
+An init script runs in every document before the page's own scripts, in every
+tab and frame. `web({ initScripts })` applies to every test;
+`browser.addInitScript` adds one for the rest of the test.
+
+A script is JavaScript source, a `{ path }` relative to the project root, or a
+function. A function cannot close over test variables; pass a JSON `arg`
+instead.
+
+```ts
+await browser.addInitScript((value) => { Math.random = () => value; }, 0.5);
+await app.open('/raffle');
+```
+
+A script added after the page opened runs from the next navigation or reload.
+
 ### Routing
 
 `route`, `unroute`, and `waitForResponse` take a string pattern (`*` within a
 path segment, `**` across `/`) or a `RegExp`, both tested against the full
 URL; a predicate function is `INVALID_ARGUMENT`. A route survives
 `app.restart()`, `app.clearState()`, and session restore.
-The handler must decide exactly once with `fulfill`, `continue`, or `abort`;
-deciding twice or not at all is `ACTION_FAILED`, as is a `waitForResponse`
-that nothing matches inside the deadline. The response resolves once its body
-is known: `url`, `status`, and `headers` are always readable, and a body the
+The handler must decide exactly once with `fulfill`, `continue`, `fallback`,
+or `abort`; deciding twice or not at all is `ACTION_FAILED`. Routes run newest
+first. `continue` sends the request to the network and no other route sees
+it; its `url` resolves against the base URL and goes through the same rule as
+`goto`, so a forbidden scheme is `POLICY_DENIED`, and it must keep the
+request's scheme. `headers` replaces every request header. The configured
+`headers` still ride a continued request bound for the app's site, and only
+that site. `fallback` hands the request to the route registered before this
+one, or the network when none matches. `fulfill` takes one of `json`, `body`,
+or `path`, a file relative to the project root whose extension sets the
+`Content-Type` unless `contentType` or a `content-type` header does. An option
+a decision does not take (Playwright's `abort(errorCode)`, a misspelled key) is
+`INVALID_ARGUMENT`: the request is aborted and the next step fails.
+
+A `waitForResponse` that nothing matches inside the deadline is
+`ACTION_FAILED`. The deadline bounds the match: the response resolves as soon
+as its headers arrive, and `text()` and `json()` wait for the body on a budget
+of their own, `config.actionTimeout` capped by the test deadline; a body still
+streaming when it runs out is `ACTION_FAILED`. `url`, `status`, and `headers`
+are always readable, and a body the
 browser could not read (a connection reset short of the declared
 `Content-Length`, a request the page aborted, or a redirect, whose body the
 browser never keeps) rejects `text()` and `json()` with `ACTION_FAILED`
@@ -417,16 +503,35 @@ expect(response.status).toBe(201);
 ```
 
 ```ts
-/** `json` or `body`, never both; neither fulfills with an empty body. */
+/**
+ * One of `json`, `body`, or `path`, or none for an empty body. `path` names a
+ * file relative to the project root; its `Content-Type` follows its
+ * extension unless `contentType` or a `content-type` header sets one.
+ */
 export type RouteFulfillResponse = {
   status?: number;
   headers?: Record<string, string>;
+  /** Sets the `Content-Type` response header. */
+  contentType?: string;
 } & (
-  | { json: JsonValue; body?: never }
-  | { body: string; json?: never }
-  | { body?: never; json?: never }
+  | { json: JsonValue; body?: never; path?: never }
+  | { body: string; json?: never; path?: never }
+  | { path: string; json?: never; body?: never }
+  | { body?: never; json?: never; path?: never }
 );
 
+/** What `continue` changes about the request before it goes to the network. */
+export interface RouteContinueOverrides {
+  /** Resolved against the base URL like `goto`; must keep the request's scheme. */
+  url?: string;
+  /** Request method. */
+  method?: string;
+  /** Replaces every request header; the configured `headers` for the app's site are added on top. */
+  headers?: Record<string, string>;
+  /** Request body. */
+  postData?: string;
+}
+
 export interface WebRoute {
   /** The intercepted request. */
   readonly request: {
@@ -437,8 +542,10 @@ export interface WebRoute {
   };
   /** Fulfills the intercepted request once. */
   fulfill(response: RouteFulfillResponse): Promise<void>;
-  /** Continues the intercepted request once. */
-  continue(): Promise<void>;
+  /** Sends the intercepted request to the network once, skipping every other route. */
+  continue(overrides?: RouteContinueOverrides): Promise<void>;
+  /** Hands the intercepted request to the route registered before this one, or the network when none matches. */
+  fallback(): Promise<void>;
   /** Aborts the intercepted request once. */
   abort(): Promise<void>;
 }
@@ -450,9 +557,9 @@ export interface WebResponse {
   readonly status: number;
   /** Response headers, lower-cased names. */
   readonly headers: Readonly<Record<string, string>>;
-  /** Parses the response body as JSON. */
+  /** Waits for the body and parses it as JSON. */
   json<T = unknown>(): Promise<T>;
-  /** Reads the response body as text. */
+  /** Waits for the body and reads it as text. */
   text(): Promise<string>;
 }
 ```
@@ -460,7 +567,8 @@ export interface WebResponse {
 ### Cookies and viewport
 
 `setCookies` validates every cookie before setting any; an unparseable
-target or a forbidden scheme is `POLICY_DENIED` and nothing is set. For the
+target or a forbidden scheme is `POLICY_DENIED` and nothing is set. A
+relative `url` resolves against the base URL, as `goto` resolves it. For the
 `domain` form the scheme follows the base URL and a leading `.` is stripped.
 `setViewport` records the new size on the report. It works before the first
 navigation too, as Playwright's `setViewportSize` does: the next `app.open`
@@ -582,7 +690,7 @@ cannot reuse node IDs or publish handles over a newer observation.
 `BrowserProvider`, `BrowserProviderScope`, `BrowserRequest`, `BrowserLease`,
 `BrowserReleaseContext`, `BrowserProviderDownloads`, `BrowserDownloadContext`,
 `PlaywrightLiveSurface`, `Browser`, `FrameScreen`,
-`BrowserExpectation`, `WebRoute`, `RouteFulfillResponse`, `WebResponse`,
+`BrowserExpectation`, `WebRoute`, `RouteFulfillResponse`, `RouteContinueOverrides`, `WebResponse`,
 `Cookie`, `CookieFields`, `Dialog`, and `DialogHandler` are exported from the
 package for typing config helpers and fixtures. The runtime exports are
 `web`, [`surfaceOf`](#surfaceof), and `test`, `describe`, `beforeEach`,

package/docs/security.mdx

@@ -48,7 +48,7 @@ A tool call that breaks a rule fails with `POLICY_DENIED`:
 
 | Denied | Why |
 | --- | --- |
-| Navigation to `file:`, `data:`, or `javascript:` | These URL schemes are forbidden. |
+| Navigation to any scheme but `http:` and `https:`, other than `about:blank` | `file:`, `data:`, `javascript:`, and wrappers such as `view-source:file:` would load local or inline content. |
 | A malformed URL | Nothing is repaired. |
 | A `Secret` reaching a JSON sink | Handles carry no value, and no value may be serialized. |
 | Reading a value, text, or attribute from a secure field, with a getter or a `toHaveValue`, `toHaveText`, `toContainText`, or `toHaveAttribute` matcher | Assert the outcome, not the secret. A withheld value is redacted, not empty or absent. |
@@ -77,10 +77,12 @@ list. Shared hosting domains such as `vercel.app` count as one site, so
 headers can reach other hosts under that domain. `basicAuth` is broader:
 it answers a `401` challenge from any origin.
 
-The runner checks forbidden schemes on explicit navigation: `app.open`, the
-agent's `navigate` verb, and `device.openLink`. `device.openApp` and the
-`open_app` tool take an app id and refuse a link, since the device would
-open one as a URL. The runner does not re-check redirects or attach to popup
+The runner checks the scheme on explicit navigation. `app.open`,
+`browser.goto`, and the agent's `navigate` verb admit `http:`, `https:`,
+and the exact `about:blank`. A device link may use an app's custom scheme, so `device.openLink`
+refuses a list instead: `file:`, `data:`, `javascript:`, `view-source:`,
+`blob:`, and `filesystem:`. `device.openApp` and the `open_app` tool take an
+app id and refuse a link, since the device would open one as a URL. The runner does not re-check redirects or attach to popup
 pages. Register `browser.onDialog` to handle browser dialogs.
 
 ## Secrets
@@ -130,13 +132,28 @@ password on screen is not masked in pixels.
 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. It matches the value as written, JSON-escaped, HTML-escaped, and
+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
+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
+`ctx.step` and the built-in agent's prompt carry the marker, so only a
+handle can type the real value.
+
+Matching covers the value as written, JSON-escaped, HTML-escaped, and
 percent-encoded, in any letter case (so a CSS `text-transform` does not hide
 it), and with its whitespace collapsed. Text cut at a length limit is masked
 too when it ends with the first 8 or more characters of a value (half of a
-value shorter than 16). Redaction rewrites only what the runner reports;
-assertions still compare the text the page shows. Secret values never enter
-cache entries.
+value shorter than 16), as written or with its whitespace collapsed, the way
+an engine collapses text before it cuts it. Every string of the observed
+screen, names, text, values, test ids, attributes, selectors, and frame
+paths alike, is redacted once, before the model, an executor's tree, a
+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.
 
 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
@@ -150,19 +167,24 @@ ordinary text with it.
   a hash, is a different string and passes through.
 - A value the app renders in another Unicode normalization form, decomposed
   accents where the secret has composed ones, passes through.
-- Text that widens the whitespace inside the value, or drops it, passes
-  through.
+- Text that drops the whitespace inside the value passes through. Text that
+  widens it passes through too, except on the observed screen: a field whose
+  collapsed form holds the value is kept collapsed and masked.
 - A value spread over several nodes, one character per cell as a PIN pad
   shows it, is not one string in the tree and passes through.
-- Text cut at a length limit is matched by its prefix only in the value's
-  own form: a case mapping that changes length (`ß` shown as `SS`) or
-  whitespace collapsed to one space escapes the prefix rule.
+- A case mapping that changes length (`ß` shown as `SS`) escapes the prefix
+  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 becomes `<secret:name>`, so unrelated text that shares 8 characters
+  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
@@ -214,8 +236,12 @@ actions without consulting a model and are not signed.
 
 The runner validates entries before use. Invalid entries become misses.
 Files are named by a hash of the expected key and refused if larger than
-1 MiB. Entries store actions and a redacted summary; replay executes only
-the actions. Secret fills store a name and authorize the fill again.
+1 MiB. The key holds the agent's context only as a hash of its redacted
+text, so no secret value enters it. Entries store actions and a redacted
+summary; replay executes only the actions. Secret fills store a name and
+authorize the fill again. An entry recorded by one agent never replays for
+another, and one recorded on the app's origin never replays on a page from
+another origin.
 
 `e2e init` ignores `.e2e/cache/` in Git. If you choose to
 [commit recordings](/cache#commit-the-replay-cache), review their actions and typed
@@ -252,8 +278,8 @@ what comes back is validated again before use.
 
 Built-in features may connect to:
 
-- one telemetry request per CLI invocation to `eu.i.posthog.com`, unless
-  opted out; see [Telemetry](/telemetry)
+- one telemetry request per CLI invocation to `eu.i.posthog.com`, plus at
+  most one per session that `e2e mcp` serves, unless opted out; see [Telemetry](/telemetry)
 - one request to `eu.i.posthog.com` per `e2e feedback` you run; see
   [Feedback](/telemetry#feedback)
 - the provider endpoint used by your configured model. Deterministic tests

package/docs/subscriptions.mdx

@@ -1,6 +1,6 @@
 ---
 title: Subscriptions
-description: Use your ChatGPT, GitHub Copilot, or SuperGrok subscription for agent steps.
+description: Use your ChatGPT, GitHub Copilot, OpenCode Console, or SuperGrok subscription for agent steps.
 ---
 
 Use an existing subscription without a separate API key. Choose your plan
@@ -10,6 +10,7 @@ in `e2e init`, install dependencies, then sign in:
 | --- | --- |
 | ChatGPT Plus or Pro | `npx e2e login openai` |
 | GitHub Copilot | `npx e2e login github-copilot` |
+| OpenCode Console (OpenCode Zen and OpenCode Go) | `npx e2e login opencode-console` |
 | SuperGrok or X Premium+ | `npx e2e login spacexai` |
 
 Follow the terminal prompts, then run `npx e2e run`. Agent calls use your
@@ -52,17 +53,17 @@ const agent = { model: chatgpt('gpt-6-luna') };
   <Tab title="GitHub Copilot">
 <CodeGroup>
 ```bash npm
-npm install -D ai @ai-sdk/openai-compatible
+npm install -D ai @ai-sdk/openai-compatible @ai-sdk/openai
 npx e2e login github-copilot
 ```
 
 ```bash pnpm
-pnpm add -D ai @ai-sdk/openai-compatible
+pnpm add -D ai @ai-sdk/openai-compatible @ai-sdk/openai
 pnpm exec e2e login github-copilot
 ```
 
 ```bash bun
-bun add -d ai @ai-sdk/openai-compatible
+bun add -d ai @ai-sdk/openai-compatible @ai-sdk/openai
 bunx e2e login github-copilot
 ```
 </CodeGroup>
@@ -71,6 +72,33 @@ bunx e2e login github-copilot
 import { copilot } from 'e2e/oauth/copilot';
 
 const agent = { model: copilot('claude-sonnet-5') };
+```
+  </Tab>
+  <Tab title="OpenCode Console">
+<CodeGroup>
+```bash npm
+npm install -D ai @ai-sdk/openai-compatible @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
+npx e2e login opencode-console
+```
+
+```bash pnpm
+pnpm add -D ai @ai-sdk/openai-compatible @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
+pnpm exec e2e login opencode-console
+```
+
+```bash bun
+bun add -d ai @ai-sdk/openai-compatible @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
+bunx e2e login opencode-console
+```
+</CodeGroup>
+
+```ts title="Model setup"
+import { opencodeConsole } from 'e2e/oauth/opencode-console';
+
+// OpenCode Zen, billed to the workspace's credits
+const agent = { model: opencodeConsole('deepseek-v4.1-flash') };
+// OpenCode Go, billed to your Go subscription
+const goAgent = { model: opencodeConsole('go/deepseek-v4.1-flash') };
 ```
   </Tab>
   <Tab title="SuperGrok">
@@ -124,11 +152,49 @@ bunx e2e models openai     # one provider
 ```
 </CodeGroup>
 
-Each line is the id to pass to `chatgpt()`, `copilot()`, or `grok()`, the
-vendor's display name, and what it says about the model: reasoning levels,
-vision, preview, or hidden. ChatGPT lists what the Codex backend serves your
-plan; Copilot lists the chat models of your plan; SuperGrok lists the
-language models the token reaches.
+Each line is the id to pass to `chatgpt()`, `copilot()`, `opencodeConsole()`,
+or `grok()`, the vendor's display name, and what it says about the model:
+reasoning levels, vision, preview, or hidden. ChatGPT lists what the Codex
+backend serves your plan; Copilot lists the chat models of your plan;
+OpenCode Console lists the Zen and Go models your workspace has enabled,
+each tagged with the plan that pays for it, and leaves out custom providers; SuperGrok lists the language models the
+token reaches.
+
+Copilot also lists models that `copilot()` cannot call, and marks them:
+
+- `not enabled`: the model is off for your plan. Turn it on in your Copilot
+  settings on GitHub, or ask your organization admin if they manage your
+  seat.
+- `no chat or responses`: Copilot serves the model only over APIs `copilot()`
+  does not speak, such as Anthropic's Messages API, so pick another model.
+
+On its first call `copilot()` picks the endpoint from the model's entry in
+this same listing: chat completions for most models, Copilot's Responses API
+for the ones served only there. When the listing cannot be read, that call
+goes over chat completions and the next call reads it again. The Responses
+call runs through `@ai-sdk/openai`, so install it beside
+`@ai-sdk/openai-compatible` to use those models; `e2e init` adds both.
+
+### OpenCode Console
+
+One OpenCode Console sign-in serves both plans billed through it:
+
+- A bare id, such as `deepseek-v4.1-flash`, is an OpenCode Zen model, paid from
+  the workspace's credits.
+- A `go/` id, such as `go/deepseek-v4.1-flash`, is an OpenCode Go model, paid
+  from the Go subscription. Go models are listed only when you hold the
+  workspace's Go subscription.
+
+The list leaves out models your workspace has turned off, and Zen's free
+models, which OpenCode keeps for its own clients.
+
+On its first call `opencodeConsole()` reads the workspace config to pick the
+model's API: chat completions, OpenAI Responses (`@ai-sdk/openai`), Anthropic
+Messages (`@ai-sdk/anthropic`), or Google (`@ai-sdk/google`). Install those
+beside `@ai-sdk/openai-compatible`; `e2e init` adds all four. Set
+`providerOptions` under the key of that API: `opencode` for chat completions
+models, on Zen and Go alike, and `openai`, `anthropic`, or `google` for the
+others.
 
 ## Sign-in help
 
@@ -137,6 +203,9 @@ language models the token reaches.
 - Copilot reuses your GitHub CLI login. If you do not use `gh`, pass
   `--client-id` for your own GitHub OAuth app with device flow enabled.
   Use `--enterprise-url` for GitHub Enterprise.
+- OpenCode Console prints a device code and opens the page where you approve
+  it and pick the workspace; the page shows e2e as an unknown client. To
+  switch workspaces, run `npx e2e logout opencode-console` and sign in again.
 - SuperGrok prints a device code and the URL where you enter it.
 
 Run `npx e2e login` to choose a provider and see which accounts are signed
@@ -155,3 +224,22 @@ instead of the local file, but refreshed tokens are not saved back to that
 variable. A value containing a rotating refresh token cannot be reused
 indefinitely. See [CLI reference](/reference/cli#e2e-login) for all sign-in
 options.
+
+For OpenCode Console in CI, create a service account API key in the Console
+(Service Accounts, then API Keys) and set it as `OPENCODE_API_KEY`;
+`opencodeConsole()` uses it instead of the stored login. `e2e models` still
+reads the stored login.
+
+<CodeGroup>
+```bash npm
+OPENCODE_API_KEY=oc_sk_... npx e2e run
+```
+
+```bash pnpm
+OPENCODE_API_KEY=oc_sk_... pnpm exec e2e run
+```
+
+```bash bun
+OPENCODE_API_KEY=oc_sk_... bunx e2e run
+```
+</CodeGroup>

package/docs/telemetry.mdx

@@ -59,9 +59,11 @@ sends nothing.
 ## What is sent
 
 Each command sends a session event. `run` and `explore` also send a run event,
-and `init` an init event. `--help` and `--version` send nothing, also when
-asked on a command. Events go in one request when the command ends, with a
-two-second deadline for all telemetry work.
+`init` an init event, and `mcp` one event per MCP session. `--help` and
+`--version` send nothing, also when asked on a command. Events go in one
+request when the command ends, with a two-second deadline for all telemetry
+work. `e2e mcp` runs as long as its client does, so it sends each MCP session
+event in its own request when that session ends, with the same deadline.
 
 Every event carries these properties.
 
@@ -110,13 +112,14 @@ Versions:
 | `engine`, `gateway` | The ids of the engine and the model gateway chosen for a new config (`web`, `mobile`, `none`; `vercel`, `openrouter`, `openai-compatible`, `chatgpt`, `copilot`, `grok`, `none`), `null` when not asked. Never the endpoint typed for an OpenAI-compatible gateway |
 | `skill`, `mcp`, `install` | Whether the agent skill, the MCP registration, and the dependency install were chosen |
 
-`e2e_run_completed`, once per `e2e run` or `e2e explore`, built from the numbers in `report.json`:
+`e2e_run_completed`, once per `e2e run` or `e2e explore`, built from the numbers in `report.json` and the resolved config:
 
 | Property | Value |
 | --- | --- |
+| `command` | `run` or `explore` |
 | `status`, `exit_code`, `duration_ms` | The run's outcome |
 | `flags` | The names of the flags given to the run command, never their values |
-| `tests_discovered`, `tests_selected`, `tests_executed`, `tests_passed`, `tests_failed`, `tests_flaky`, `tests_skipped` | The summary counts |
+| `tests_discovered`, `tests_selected`, `tests_executed`, `tests_passed`, `tests_failed`, `tests_interrupted`, `tests_flaky`, `tests_skipped` | The summary counts |
 | `attempts_total`, `tests_retried` | How many attempts the run made across tests and serial groups, and how many of them needed more than one |
 | `targets`, `platforms`, `engines` | How many targets, on which platforms, and with which engines and versions, as your config declares them: `web`, `ios`, `web@0.6.1`, or your own engine's name and version. A name that is not a plain token of letters, digits, dots, dashes, and underscores is reported as `other` |
 | `steps_total`, `steps_agent`, `steps_locator`, `steps_assertion`, `steps_screen`, `steps_app`, `steps_session`, `steps_resource` | Step counts by kind |
@@ -129,11 +132,50 @@ Versions:
 | `primary_error_code` | The first error the run recorded, which is the one that decided its status: a run-level error, else the failed attempt's verdict, else a step's; `null` for a clean run |
 | `error_kinds` | For `ENGINE_FAILURE`, `MODEL_PROVIDER_FAILED`, and `ERROR`, whose code says where a failure surfaced but not what it was: the code and a kind read off the message against a closed list (`auth`, `rate-limit`, `overloaded`, `timeout`, `network`, `server`, `bad-request`, `device`, `daemon`, `browser`, `permission`, `not-found`, `memory`, `other`), as `MODEL_PROVIDER_FAILED:rate-limit`. Only the kind's name leaves the machine, never the message |
 
+Which config features the run used, absent when the config did not load. Each
+is a count, a boolean, or one of the runner's own option values, never a name,
+a path, or free text you wrote:
+
+| Property | Value |
+| --- | --- |
+| `config_workers`, `config_retries` | The worker count and retries the run resolved |
+| `config_agents`, `config_custom_executor`, `config_separate_judge`, `config_project_tools` | How many agents are configured, whether any has a custom executor or a judge model of its own, and how many distinct project tools they declare |
+| `config_credentials`, `config_secrets` | How many credentials and secrets are configured |
+| `config_cache_mode`, `config_cache_store`, `config_cache_strict` | `off`, `read-only`, or `read-write`; `file` or `custom`; whether strict replay is on |
+| `config_reporters`, `config_custom_reporters`, `config_artifact_store` | The built-in reporter ids (`list`, `json`, `junit`, `markdown`), how many reporter objects the config adds, and whether an artifact store is set |
+| `config_trace_modes`, `config_video_modes` | The distinct recording modes across targets (`off`, `on`, `retain-on-failure`, `on-first-retry`, `on-all-retries`) |
+| `config_app_commands`, `config_environments` | How many targets start an app command, and the distinct app environments (`test`, `staging`, `production`) |
+
+On `e2e explore` only, what the exploration was given and found, by count.
+Never the goal, a step's charter, or a finding's words:
+
+| Property | Value |
+| --- | --- |
+| `explore_ended` | Why it stopped: `finished`, `step-limit`, `time`, `stuck`, or `aborted` |
+| `explore_max_steps`, `explore_timeout_ms` | The budgets it ran with |
+| `explore_steps`, `explore_steps_passed`, `explore_steps_failed`, `explore_steps_blocked`, `explore_steps_exhausted` | Exploration steps, by how each ended |
+| `explore_assessed` | Whether the agent gave a closing assessment |
+| `explore_issues`, `explore_warnings`, `explore_findings_by_severity` | Findings by kind, and by severity: `{"1": 0, "2": 1, "3": 0, "4": 0, "5": 1}` |
+
+`e2e_mcp_session`, once per `open_session` an `e2e mcp` server receives, sent when the session closes or the open fails. A session still open when the client kills the server is not sent:
+
+| Property | Value |
+| --- | --- |
+| `client`, `client_version` | The name and version the MCP client gives itself (`claude-code`, `cursor-vscode`, ...). A value that is not a plain token is reported as `other`; `null` before the client introduced itself |
+| `outcome`, `error_code` | `closed` for a session that opened, `open-failed` with the runner code it failed with (`APP_UNREACHABLE`, `ENGINE_FAILURE`, ...) |
+| `ended_by` | `agent` for `close_session`, `idle`, `step` for the session's time limit, `server` when the server shut down; `null` for a failed open |
+| `platform`, `engine`, `headed` | The target's platform and engine with its version, as for a run, and whether the UI was shown |
+| `duration_ms`, `sessions_open` | How long the session lived, and how many other sessions were open when it opened |
+| `calls_total`, `calls_failed`, `calls` | Tool calls, failed calls, and calls by the session's own tool names: `{"observe": 4, "tap": 9, "locate": 2, "screenshot": 1}`. A project's own tools are counted together as `tool` and anything else as `other`; no other name is sent |
+| `error_codes` | How often each runner code failed a call: `{"LOCATOR_NOT_FOUND": 2}`, at most 20 codes. A code that is not an upper-case token is reported as `OTHER` |
+
 ## What is never sent
 
 Test titles, file paths, URLs, origins, instructions, observations, page
 content, screenshots, error messages, stack traces, environment variable
-values, credentials, or file contents. Events include only the properties
+values, credentials, or file contents. Nor the names of targets, agents,
+credentials, secrets, or project tools, the arguments or results of MCP tool
+calls, an exploration's goal, or its findings. Events include only the properties
 listed above.
 
 ## In CI