e2e 0.16.0 → 0.18.0

package/docs/reference/web.mdx

@@ -1,15 +1,17 @@
 ---
 title: Browser
 description: The browser engine, its options, and the browser fixture it contributes.
+icon: "globe"
 ---
 
 `@e2e-dev/web` drives Chromium, Firefox, and WebKit through Playwright.
 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 +22,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 +109,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. */
@@ -117,7 +163,7 @@ That protection is text only: unlike a fill, it withholds no screenshot or
 model pixels, so a page that renders the password on screen is not masked in
 them ([Security](/security#secrets)).
 
-`headers` and `basicAuth` are how a test reaches a [protected preview](/starting-your-app#protected-previews).
+`headers` and `basicAuth` are how a test reaches a [protected preview](/web#protected-previews).
 
 `screencast` shapes the recording, not which attempts record: that is the
 config's [`video`](/reference/config#video) mode. `size` takes whole pixels,
@@ -180,7 +226,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 +248,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`,
@@ -246,13 +292,17 @@ export interface Browser extends Expectable<BrowserExpectation> {
   locator(selector: string): Locator;
   /** Creates a screen query scope inside one iframe. */
   frameLocator(selector: string): FrameScreen;
-  /** Evaluates trusted test code in the page. */
+  /** Evaluates trusted test code in the page: a function, or a string expression whose value is returned, called first if it is a function. */
   evaluate<T extends JsonValue>(fn: string | (() => T | Promise<T>)): Promise<T>;
   /** Evaluates trusted test code with one required JSON-safe argument. */
   evaluate<T extends JsonValue, Arg extends JsonValue>(
     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 +358,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,7 +369,7 @@ 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`. It
@@ -379,6 +429,10 @@ close over anything outside its own body; helpers declared inside the body
 work. Pass outside values through `arg`. Both `arg` and the return value
 must be `JsonValue`, otherwise the call fails with `INVALID_ARGUMENT`.
 
+A string is evaluated as a single expression, not as statements. If it
+evaluates to a function, that function is called with `arg`; otherwise its
+value is the result. A promise, from either, is awaited.
+
 An exception in the evaluated code is `EVALUATE_FAILED` with its message. A
 Playwright timeout is `ACTION_FAILED`; a closed page or lost context is
 `ENGINE_FAILURE`.
@@ -389,18 +443,52 @@ const flag = await browser.evaluate(
   (name: string) => window.localStorage.getItem(name),
   'featureFlags',
 );
+const title = await browser.evaluate<string>('document.title');
+```
+
+### 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`
@@ -421,16 +509,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: {
@@ -441,8 +548,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>;
 }
@@ -454,9 +563,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>;
 }
 ```
@@ -464,7 +573,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`
@@ -586,7 +696,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

@@ -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.
@@ -48,7 +49,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 +78,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
@@ -104,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
@@ -128,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
@@ -145,9 +151,16 @@ 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.
+
+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
@@ -161,40 +174,39 @@ 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
-  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.
@@ -230,8 +242,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
@@ -248,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, or SuperGrok subscription for agent steps.
+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
@@ -10,6 +11,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 +54,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 +73,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,20 +153,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 completions`: Copilot serves the model only over other APIs,
-  mostly its Responses API. `copilot()` uses chat completions, so pick
-  another model.
+- `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
 
@@ -146,6 +204,9 @@ Copilot also lists models that `copilot()` cannot call, and marks them:
 - 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
@@ -164,3 +225,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>