e2e 0.15.2 → 0.17.0

package/dist/telemetry/telemetry.js

@@ -4,8 +4,10 @@
  * One instance lives for one CLI invocation. Commands hand it events; at the
  * end of the invocation `flush` sends them in a single bounded request, so a
  * command never waits on telemetry for more than the flush budget and never
- * fails because of it. Telemetry is a CLI concern only: the runner never
- * constructs this class.
+ * fails because of it. A long-lived command (`e2e mcp`) sends what it has
+ * queued as it goes with `sendQueued`, so a client that kills it loses only
+ * what was still in progress. Telemetry is a CLI concern only: the runner
+ * never constructs this class.
  *
  * Off means off at every step. `E2E_TELEMETRY_DISABLED`, `DO_NOT_TRACK`, a
  * source checkout of the repository, an `e2e telemetry disable`, or a
@@ -34,13 +36,13 @@ import { postBatch } from './posthog.js';
 import { anonymousProjectId } from './project.js';
 import { preferencesPath, TelemetryStore, telemetryConfigDir } from './store.js';
 /** Bumped when what is collected changes enough that the notice must show again. */
-export const NOTICE_VERSION = 2;
+export const NOTICE_VERSION = 3;
 /** The longest a flush may hold the process; the project lookup and the request share it. */
 const DEFAULT_FLUSH_MS = 2_000;
 /** The one-time notice: what is collected, and the two ways out. */
 function noticeText() {
     return [
-        `${picocolors.bold('e2e collects anonymous usage telemetry')} to improve the framework: the command, the versions, the OS, and run counts. Never test names, app data, or credentials.`,
+        `${picocolors.bold('e2e collects anonymous usage telemetry')} to improve the framework: the command, the versions, the OS, and summaries of runs and MCP sessions. Never test names, app data, or credentials.`,
         `Opt out with ${picocolors.cyan('e2e telemetry disable')} or ${picocolors.cyan('E2E_TELEMETRY_DISABLED=1')}. What is sent: ${picocolors.underline(`${DOCS_URL}/telemetry`)}`,
         '',
         '',
@@ -74,6 +76,8 @@ export class Telemetry {
     command;
     failure;
     exitCode;
+    /** Sends `sendQueued` started that have not settled; the flush waits for them. */
+    sending = new Set();
     constructor(options) {
         this.version = options.version;
         this.env = options.env ?? process.env;
@@ -200,14 +204,28 @@ export class Telemetry {
         return [cliSessionEvent(this.command.name, this.command.flags, ended)];
     }
     /**
-     * Sends everything queued in one request, or prints it under debug. One
-     * deadline covers the project lookup still running and the request; a
-     * lost batch is the accepted cost of a command that never waits on
-     * telemetry.
+     * Sends everything queued in one request, or prints it under debug, and
+     * waits for the sends `sendQueued` started. One deadline covers the
+     * project lookup still running and the request; a lost batch is the
+     * accepted cost of a command that never waits on telemetry.
      */
     async flush(maxWaitMs = DEFAULT_FLUSH_MS) {
         const events = [...this.sessionEvent(), ...this.queue.splice(0)];
         this.command = undefined;
+        await Promise.all([this.send(events, maxWaitMs), ...this.sending]);
+    }
+    /**
+     * Sends what is queued now, without the session event, which only the
+     * flush at the end can complete. For a command that runs until its client
+     * goes away; the caller need not wait, the flush does.
+     */
+    sendQueued(maxWaitMs = DEFAULT_FLUSH_MS) {
+        const sending = this.send(this.queue.splice(0), maxWaitMs).finally(() => this.sending.delete(sending));
+        this.sending.add(sending);
+        return sending;
+    }
+    /** Sends `events` in one bounded request, or prints them under debug; nothing when off. */
+    async send(events, maxWaitMs) {
         if (events.length === 0)
             return;
         // A choice saved from another process while this command ran wins over the snapshot taken at its start.
@@ -250,4 +268,3 @@ export class Telemetry {
         await postBatch(items, { signal: deadline, fetch: this.fetchImpl });
     }
 }
-//# sourceMappingURL=telemetry.js.map

package/dist/telemetry/token.d.ts

@@ -9,4 +9,3 @@
 export declare function plainToken(value: string): string;
 /** A runner error code as it is, `OTHER` for a code shaped like a project's own. */
 export declare function errorCodeToken(code: string): string;
-//# sourceMappingURL=token.d.ts.map

package/dist/telemetry/token.js

@@ -15,4 +15,3 @@ export function plainToken(value) {
 export function errorCodeToken(code) {
     return ERROR_CODE.test(code) ? code : 'OTHER';
 }
-//# sourceMappingURL=token.js.map

package/dist/types.d.ts

@@ -198,7 +198,7 @@ export interface TextMatchOptions {
 /**
  * Role query options. A role query never matches a node hidden from the
  * accessibility tree, on every engine; `visible` (inherited) is the one knob
- * that narrows the other query kinds the same way.
+ * that narrows the other query kinds, to the nodes `toBeVisible()` accepts.
  */
 export interface RoleOptions extends TextMatchOptions {
     /** Accessible name filter. */
@@ -377,9 +377,13 @@ export interface Locator extends Screen {
     all(): Promise<Locator[]>;
     /** Reads the normalized text of every current match, without auto-waiting; empty when nothing matches. */
     allTextContents(): Promise<string[]>;
-    /** Waits for the requested locator state. */
+    /**
+     * Waits for the requested locator state, `visible` by default: `attached`
+     * for one match, visible or not; `detached` for none; `hidden` for none or
+     * a hidden one.
+     */
     waitFor(options?: {
-        state?: 'visible' | 'hidden';
+        state?: 'attached' | 'detached' | 'visible' | 'hidden';
         timeout?: number;
     }): Promise<void>;
     /** Adds deterministic locator filters. */
@@ -585,31 +589,39 @@ export interface TestAPI<Fixtures = TestFixtures> {
     /** Registers a suite-instance teardown hook. */
     afterAll(fn: SuiteHookFn): void;
 }
+/**
+ * The locator matchers. An option a matcher does not take, or a flag that is
+ * not a boolean, is `INVALID_ARGUMENT` before the first read.
+ */
 export interface AsyncExpectation {
     /** Inverts the matcher. A negated matcher passes after 1000 ms of continuous truth. */
     readonly not: AsyncExpectation;
-    /** Waits for visibility. */
+    /** Waits for visibility; `visible: false` waits for hidden or absent state, as `toBeHidden`. */
     toBeVisible(options?: {
+        visible?: boolean;
         timeout?: number;
     }): Promise<void>;
     /** Waits for hidden or absent state. */
     toBeHidden(options?: {
         timeout?: number;
     }): Promise<void>;
-    /** Waits for one match to exist, visible or not. */
+    /** Waits for one match to exist, visible or not; `attached: false` waits for none. */
     toBeAttached(options?: {
+        attached?: boolean;
         timeout?: number;
     }): Promise<void>;
-    /** Waits for enabled state. */
+    /** Waits for enabled state; `enabled: false` waits for disabled state. */
     toBeEnabled(options?: {
+        enabled?: boolean;
         timeout?: number;
     }): Promise<void>;
     /** Waits for disabled state. */
     toBeDisabled(options?: {
         timeout?: number;
     }): Promise<void>;
-    /** Waits for checked state. */
+    /** Waits for checked state; `checked: false` waits for unchecked state. */
     toBeChecked(options?: {
+        checked?: boolean;
         timeout?: number;
     }): Promise<void>;
     /** Waits for selected state. */
@@ -625,19 +637,11 @@ export interface AsyncExpectation {
         timeout?: number;
     }): Promise<void>;
     /** Waits for exact normalized text; a list waits for exactly that many matches, each with its entry's text, in order. */
-    toHaveText(expected: TextMatch, options?: {
-        timeout?: number;
-    }): Promise<void>;
-    toHaveText(expected: readonly TextMatch[], options?: {
-        timeout?: number;
-    }): Promise<void>;
+    toHaveText(expected: TextMatch, options?: TextMatcherOptions): Promise<void>;
+    toHaveText(expected: readonly TextMatch[], options?: TextMatcherOptions): Promise<void>;
     /** Waits for contained normalized text; a list waits for each entry to be contained by a distinct match, in order, extra matches allowed. */
-    toContainText(expected: TextMatch, options?: {
-        timeout?: number;
-    }): Promise<void>;
-    toContainText(expected: readonly TextMatch[], options?: {
-        timeout?: number;
-    }): Promise<void>;
+    toContainText(expected: TextMatch, options?: TextMatcherOptions): Promise<void>;
+    toContainText(expected: readonly TextMatch[], options?: TextMatcherOptions): Promise<void>;
     /** Waits for a form control's value, compared as it is. */
     toHaveValue(expected: TextMatch, options?: {
         timeout?: number;
@@ -646,17 +650,20 @@ export interface AsyncExpectation {
     toHaveAttribute(name: string, options?: {
         timeout?: number;
     }): Promise<void>;
-    toHaveAttribute(name: string, value: TextMatch, options?: {
-        timeout?: number;
-    }): Promise<void>;
+    toHaveAttribute(name: string, value: TextMatch, options?: TextMatcherOptions): Promise<void>;
     /** Waits for an exact match count. */
     toHaveCount(expected: number, options?: {
         timeout?: number;
     }): Promise<void>;
     /** Waits for an accessible name. */
-    toHaveAccessibleName(expected: TextMatch, options?: {
-        timeout?: number;
-    }): Promise<void>;
+    toHaveAccessibleName(expected: TextMatch, options?: TextMatcherOptions): Promise<void>;
+}
+/** Options of a locator matcher that compares text. */
+export interface TextMatcherOptions {
+    /** Compares a string case-insensitively; on a RegExp, `true` adds the `i` flag and `false` removes it. */
+    ignoreCase?: boolean;
+    /** Assertion budget in milliseconds. */
+    timeout?: number;
 }
 /**
  * An object that carries its own expectation surface, so `expect(object)`
@@ -1247,6 +1254,8 @@ export interface E2EConfig {
     cleanupTimeout?: number;
     /** Retries per test, 0 through 10; default 1 in CI, else 0. */
     retries?: number;
+    /** Fail the run when a test skips itself after a soft failure or an earlier failed attempt; default false. */
+    failOnSkippedFailure?: boolean;
     /** Parallel workers, 1 through 1024; default 1 in CI, else half the cores. An engine may cap it lower. */
     workers?: number;
     /** `{ store }` hands every artifact to a host store as it is produced. */
@@ -1313,4 +1322,3 @@ export interface E2EConfig {
      */
     secrets?: Readonly<Record<string, SecretConfig>>;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -3,4 +3,3 @@
  * `tests/types/sdk-types.ts` pins the parts that are easy to loosen by accident.
  */
 export {};
-//# sourceMappingURL=types.js.map

package/docs/agents.mdx

@@ -109,9 +109,12 @@ agent if the problem affects several tests:
 5. Compare models or `providerOptions` by running the same tests with
    `--agent <name>`.
 
-Named agents can use the [replay cache](/cache). Custom tools and executors
-have their own replay constraints, described under [project tools](/tools)
-and [custom executors](/executors#replay-cache).
+Named agents can use the [replay cache](/cache). Each agent records its
+own entries, keyed by its name and its context, so a test that runs as
+`buyer` and as `admin` never replays one persona's steps for the other, and
+changing `agentContext` records again. Custom tools and executors have their
+own replay constraints, described under [project tools](/tools) and
+[custom executors](/executors#replay-cache).
 
 ## Pick an agent per run
 

package/docs/assertions.mdx

@@ -0,0 +1,94 @@
+---
+title: Assertions
+description: Check the screen with agent.assert, wait for a condition, and extract data.
+---
+
+An assertion checks what is on screen. The agent has three judgment calls:
+`assert` checks the screen now, `waitFor` waits until a condition holds, and
+`extract` reads structured data. When you know the exact value, use an
+`expect` [locator assertion](#locator-assertions) instead, with no model call.
+
+```ts
+await agent.assert('the dashboard shows a trial badge');
+```
+
+## `agent.assert`
+
+`assert` checks a statement against the current screen. A false statement
+fails with `ASSERTION_FAILED`. If the screen does not provide enough evidence,
+it fails with `ASSERTION_INCONCLUSIVE`.
+
+The judging model sees the statement and the current screen. It does not see
+earlier steps or the acting agent's summaries.
+
+## `agent.waitFor`
+
+`assert` checks the screen now. Use `waitFor` when the condition may become true
+later. It polls the screen and only calls the model when the observation changes.
+
+```ts
+await agent.waitFor('the export finishes and a download link appears', {
+  interval: 500,
+  timeout: 120_000,
+});
+```
+
+## `agent.extract`
+
+`extract` reads structured data from the screen. Provide a
+[Standard Schema](https://standardschema.dev) validator, such as Zod, to define
+the result.
+
+```ts
+import { expect } from 'e2e';
+import { z } from 'zod';
+
+const data = await agent.extract('every todo title and how many remain', {
+  schema: z.object({ titles: z.array(z.string()), remaining: z.number().int() }),
+});
+expect(data.titles).toContain('Buy milk');
+```
+
+<Tip>
+For model-generated descriptions, check the relevant meaning rather than the
+entire sentence. Use a [locator assertion](/locators) when the exact text matters.
+</Tip>
+
+## Judging pixels
+
+By default, judgments read a redacted text snapshot of the screen. Add
+`vision: true` for visual checks, such as charts or layout. Use
+`vision: 'only'` to judge the screenshot alone.
+
+```ts
+await agent.assert('the chart trends upward', { vision: true });
+await agent.assert('the search form is not covered by a banner', { vision: 'only' });
+```
+
+Images add input tokens. Screenshots are withheld for the rest of an attempt
+after a secret is filled. The [agent reference](/reference/agent#vision)
+lists the modes and restrictions.
+
+## Locator assertions
+
+`expect` on a locator checks an exact value and calls no model. It retries
+until the check passes or the assertion timeout runs out.
+
+```ts
+await expect(screen.getByRole('status')).toHaveText('2 remaining');
+await expect(screen.getByRole('heading', 'Dashboard')).toBeVisible();
+```
+
+[Locators](/locators) covers queries and actions. The
+[expect reference](/reference/expect#locator-matchers) lists every matcher.
+
+## Next
+
+<CardGroup cols={2}>
+  <Card title="Locators" icon="crosshairs" href="/locators">
+    Exact actions and checks with `screen` and `expect`.
+  </Card>
+  <Card title="How agent steps work" icon="list-check" href="/agent-steps">
+    Verdicts, exit codes, and what the model sees.
+  </Card>
+</CardGroup>

package/docs/authentication.mdx

@@ -211,7 +211,9 @@ export default {
 ```
 
 `E2E_SECRET_<NAME>` overrides an entry per run, with the same uppercasing rule
-as credentials, so a CI job can supply the value without touching the config:
+as credentials, so a CI job can supply the value without touching the config.
+Two entries that map to one variable, like `stripe-key` and `stripe_key`, fail
+the config load with `INVALID_CONFIG`, as two such credentials do:
 
 <CodeGroup>
 ```bash npm

package/docs/browser.mdx

@@ -39,7 +39,9 @@ await app.open('/checkout');
 await expect(screen.getByText('$42.00')).toBeVisible();
 ```
 
-Each handler must call exactly one of `fulfill`, `continue`, or `abort`. An
+Each handler must call exactly one of `fulfill`, `continue`, `fallback`, or
+`abort`. The newest route runs first; `continue` sends the request straight to
+the network, while `fallback` passes it to the route registered before. An
 `expect` that fails inside the handler fails the test, at the next step or at
 the end of the test when nothing follows. To inspect a real response, start
 waiting before the action that sends it:
@@ -114,14 +116,33 @@ const flag = await browser.evaluate((name: string) => window.localStorage.getIte
 Use `evaluate` for state that `screen` cannot read. Prefer locators and
 assertions for visible UI so tests depend less on the DOM structure.
 
+## Run a script before the page
+
+An init script runs in every document before the page's own scripts: mock a
+browser API, seed `Math.random`, or set a flag the app reads at boot. For every
+test:
+
+```ts
+web({ initScripts: [{ path: 'tests/init.js' }] })
+```
+
+For one test, before the page opens:
+
+```ts
+await browser.addInitScript((value) => { Math.random = () => value; }, 0.5);
+await app.open('/raffle');
+```
+
+See [init scripts](/reference/web#init-scripts).
+
 ## Cookies
 
 ```ts
 await browser.setCookies([{ url: 'http://localhost:3000', name: 'tz', value: 'UTC' }]);
 ```
 
-A cookie URL that does not parse, or uses `file:`, `data:`, or
-`javascript:`, is `POLICY_DENIED`; a domain cookie is checked as the origin
+A cookie URL that does not parse, or uses a scheme other than `http:` or
+`https:` (`about:blank` included), is `POLICY_DENIED`; a domain cookie is checked as the origin
 it would be sent to. If any entry is refused, no cookies are set. To resize
 the page, see [Testing viewports](/viewports).
 
@@ -144,8 +165,23 @@ export default {
 } satisfies E2EConfig;
 ```
 
-`npx playwright install webkit --with-deps` provisions the extra browser in
-CI. `connect` attaches to a remote Chromium over CDP instead of launching
+In CI, provision the extra browser with the [install command](/reference/web#installing-browsers):
+
+<CodeGroup>
+```bash npm
+npx @e2e-dev/web install webkit --with-deps
+```
+
+```bash pnpm
+pnpm exec e2e-web install webkit --with-deps
+```
+
+```bash bun
+bunx @e2e-dev/web install webkit --with-deps
+```
+</CodeGroup>
+
+`connect` attaches to a remote Chromium over CDP instead of launching
 one; a [browser provider](#hosted-browsers) does the same and also leases
 and releases the browser. [Testing viewports](/viewports) covers sizes.
 
@@ -237,7 +273,7 @@ The attempt runs in the browser's persistent default context, on the
 browser's own first tab, so the remote must contain only that context, and
 the limits of
 [`connect.reconnectEndpoint`](/reference/web#recovering-a-cdp-transport)
-apply: no `headers`, `basicAuth`, or `userAgent` (each is `INVALID_CONFIG`), no
+apply: no `headers`, `basicAuth`, `userAgent`, `locale`, or `timezoneId` (each is `INVALID_CONFIG`), no
 `app.clearState()` (`UNSUPPORTED_CAPABILITY` naming the scope), and no session
 state capture or restore, so a run whose tests consume a
 [session](/authentication) on the target fails with `COLLECTION_ERROR`

package/docs/cache.mdx

@@ -45,27 +45,60 @@ bunx e2e run --no-cache
 
 ## How a replay works
 
-1. Check the starting screen: the same route, whatever the record id, the
-   query, or the fragment. Retries always run live.
+1. Check the starting screen: the same route, whatever the record id or the
+   fragment. Retries always run live.
 2. Find each recorded control and repeat its action. The runner matches
    controls by their role, name, test id, and surrounding context. It waits
    for missing controls and stops if a match is ambiguous. A control with no
-   name is found by its place among the unnamed controls of its kind.
-3. Check the final path and controls that appeared during the original step.
-   Text that changes with the data, a count, a date, an id, is not used.
+   name is found by its place among the unnamed controls of its kind inside
+   the same named row, list item, or group; with no such container to tell
+   it from its twins, the agent takes the step.
+3. Check the final route and what the original step changed: the controls
+   that appeared, with their checked, selected, expanded, or pressed state,
+   and the ones that went away. At least one of those changes must happen
+   during the replay, counted from the first screen the replay saw on the
+   route it ended on, so an outcome already on screen before the actions
+   that should produce it proves nothing; a step whose last action moved to
+   another route has that move as its evidence. An alert the replay raised
+   that the recording never saw stops it too. Text that reads differently on
+   every run, a date, a time, a duration, an id, is not used, except in an
+   alert, where it is read as a placeholder.
 4. Finish without a model call, or let the agent continue with a record of
    what ran and why replay stopped.
 
+A route is the origin, the path, and the query. Ids, tokens, timestamps,
+and cache busters in either the path or the query are read as an id
+placeholder, so `/orders/42?t=1727780000` and `/orders/7?t=1727780999` are
+one route. Every other query value is part of it: `?mode=safe` and
+`?mode=unsafe`, or `/companies` and `/companies?tab=notes`, are different
+screens, and so is a tracking parameter that was not there when the step
+was recorded. Two routes that differ in one word, `/products/summer-sneaker`
+and `/products/winter-boot`, are different screens too, even when they look
+alike. A location on the app's own origin is compared by its path, so a
+recording follows the app to a preview deployment that shares its
+`app.identity`; a page on any other origin is another route.
+
+A count that names what it counts, `3 records imported` or `Showing 1 to 9
+of 9 results`, is part of the effect when the step made it appear on the
+screen it acted on, and must read the same on replay. A count that was
+already on screen and only moved, `41 items` to `42 items`, or one on a
+screen the step navigated to, is not used, since leftover data from earlier
+runs moves it again. A bare number such as a badge is never used.
+
 Typed values replay as recorded, even when an earlier run left the same
 value on screen. Secret fills resolve the current value by name and run
 through authorization again.
 
 ## What must match
 
-A cache entry belongs to a specific test, target, instruction, and set of
-params. Renaming the test or target, changing the instruction or an ordinary
-param, or upgrading the engine's major or minor version causes a miss.
-Changing the model does not.
+A cache entry belongs to a specific test, target, instruction, set of
+params, and agent. Renaming the test or target, changing the instruction or
+an ordinary param, running with another configured agent, changing the
+agent's `context` or the test's `agentContext`, or upgrading the engine's
+major or minor version causes a miss. A test that runs once per agent
+(`agent: ['buyer', 'admin']`) records once per agent. Changing the model
+does not. The agent context enters the key as a hash of its redacted text,
+so a secret in it contributes only its name.
 
 A timestamp or a fresh email address would cause a miss on every run. Wrap
 values like these in `unique()` so the runner substitutes the current value
@@ -96,7 +129,9 @@ identity. On devices, replay uses the
 
 In `read-write` mode, the runner saves a recording at the end of the
 attempt when a later verification step passed. A step that took no action
-records nothing.
+records nothing, and neither does one that changed nothing the replay could
+check: no control appeared, went away, or changed state, and the route
+stayed the same.
 
 | Counts as verification | Does not count |
 | --- | --- |
@@ -145,14 +180,14 @@ such as an `afterEach` assertion.
 | `retry` | Retries never replay. | Nothing. |
 | `invalid-entry` | The file is unreadable, over 1 MiB, or from another schema version. | `npx e2e cache clear`. |
 | `truncated` | The recording hit a limit, see [below](#limits-and-gaps). | Split the step, or pass the secret as a `Secret`. |
-| `wrong-context` | The app was on another screen than when the step was recorded: a different route, not a different record, query, or fragment. | Open the same screen before the step. |
-| `target-not-found` | A recorded control did not appear within 15 seconds. | The UI changed. The next passing run re-records. |
+| `wrong-context` | The app was on another screen than when the step was recorded: a different origin, path, or query, not a different record id or fragment. | Open the same screen before the step. |
+| `target-not-found` | A recorded control did not appear within 15 seconds, or it has no name and no named container to tell it from its twins. | The UI changed: the next passing run re-records. For an unnamed control, give it a label or put it in a named row or group. |
 | `target-ambiguous` | The number of matching controls changed. | Give repeated controls distinct names or use unique test data. |
 | `gap` | An action cannot be replayed, see [below](#limits-and-gaps). | The agent continues this part live. Put stable values in `params`. |
 | `action-failed` | The app rejected a replayed action. | Check the app. |
 | `action-uncertain` | A replayed action failed with an unknown commit state. The agent is told to check before acting again. | Check the app. |
 | `viewport-changed` | A bare-point tap or hover was recorded on a viewport of another size. | Keep the viewport fixed. |
-| `end-mismatch` | Every action ran, but the recorded path or a control that should have appeared did not come back. | Leftover data from an earlier run, a banner that comes and goes, or a regression. |
+| `end-mismatch` | Every action ran, but the recorded route, a control that should have appeared or gone away, or a recorded state did not come back; the outcome was already on screen before the replay; or the replay raised an alert the recording never saw. | Leftover data from an earlier run, a banner that comes and goes, or a regression. |
 
 A stop before any action ran is a miss. After replay starts, it is a
 hand-off. Unique test data and cleanup in `afterEach` help avoid stale
@@ -176,8 +211,9 @@ the instruction or `params`, or ones the agent composed itself, replay.
 
 Each entry is a JSON file under `.e2e/cache/`, named by a hash of its key.
 It contains actions, target descriptions, typed text, a step summary, and
-checks for the final state. Those checks include the path and up to eight
-controls that appeared during the step.
+checks for the final state. Those checks include the route, up to eight
+controls that appeared during the step, alerts and status messages first,
+and up to eight that went away.
 
 Entries contain no prompts, conversations, screenshots, observed trees, or
 secret values. A secret fill stores only the secret's name. Other typed
@@ -220,12 +256,16 @@ Local runs leave a committed directory clean unless something changed. A
 replayed step never rewrites its entry, and a live re-recording with the same
 actions, paths, and anchors is not written: the summary, the measured end
 wait, and the rule that flagged a typed run-time value differ between two
-live runs of the same flow and do not count. A file changes when:
+live runs of the same flow and do not count. Upgrading `e2e` to a version
+that changes how entries are matched re-keys every entry, so the first run
+after it records them again. A file changes when:
 
 - a step records for the first time,
 - the agent finishes a step after a hand-off, re-recording what it saw,
 - a step fails after replaying, or ends in an `end-mismatch` the agent had
   to repair, which deletes the entry,
+- a step with an entry passes without leaving anything to record, which
+  deletes the entry,
 - no verification step confirmed the entry by the end of the attempt, which
   deletes it.
 
@@ -257,8 +297,14 @@ CI=1 bunx e2e run --strict-cache
 The reasons that fail are the ones that mean the app or the entry changed:
 `invalid-entry`, `wrong-context`, `target-not-found`, `target-ambiguous`,
 `viewport-changed`, `action-failed`, `action-uncertain`, and `end-mismatch`.
-A step with no recording (`no-entry`), a retry, a `gap`, and a `truncated`
-recording still run live. `REPLAY_STALE` exits 2 and is not retried, since a
+A `no-entry` miss fails too when the cache directory holds a recording of the
+same step under another key, from before an `e2e` or engine upgrade or a
+change to the project id, the app's identity, or the agent's context. The
+message names that file; delete it once nothing replays it. A custom
+`cache.store` is not checked this way. Entries recorded before this check
+existed are covered once a `read-write` run replays or re-records them. A
+step never recorded (a new or edited instruction or params), a retry, a
+`gap`, and a `truncated` recording still run live. `REPLAY_STALE` exits 2 and is not retried, since a
 retry never replays and would pass live. The entry stays where it is, even
 in `read-write` mode, so every strict run fails on it until it is re-recorded:
 run the test in `read-write` mode without the flag, and with `cache.strict`

package/docs/ci.mdx

@@ -35,7 +35,7 @@ jobs:
       - run: pnpm install --frozen-lockfile
 
       - name: Install browsers
-        run: npx playwright install chromium --with-deps
+        run: pnpm exec e2e-web install chromium --with-deps
 
       - name: Run e2e
         run: npx e2e run --reporter list,junit
@@ -66,7 +66,9 @@ jobs:
 ```
 
 The workflow pins actions to commit SHAs and installs dependencies from the
-lockfile. `npx e2e` runs the installed version.
+lockfile. `npx e2e` runs the installed version. The
+[install command](/reference/web#installing-browsers) downloads the browsers
+for the Playwright version the engine pins, with their system libraries.
 
 Artifacts upload on every run that is not cancelled, so a test that failed
 and then passed on retry still has its evidence.
@@ -139,10 +141,12 @@ implemented yet.
 
 `--last-failed` runs only the tests the previous run did not pass, read from
 `report.json` in the [`output`](/reference/config#output) directory (`.e2e`
-by default). The rerun empties `artifacts/` there when it starts, so
-upload the first run's artifacts before rerunning in the same job if you want
-both. The [CLI reference](/reference/cli#flags) lists what counts as not
-passed. Locally it is the loop after a red run:
+by default). The rerun keeps the artifacts the first run's report names and
+writes its own under `artifacts/rerun-1/`, so one upload after both steps
+holds the evidence of each. A test another filter keeps out of the rerun
+stays owed: the next `--last-failed` runs it. The
+[CLI reference](/reference/cli#flags) lists what counts as not passed.
+Locally it is the loop after a red run:
 
 <CodeGroup>
 ```bash npm
@@ -193,7 +197,7 @@ flaky, so you can identify flows that need investigation.
 `--max-failures <n>` stops the run once that many tests have failed, so a
 broken deploy does not spend a model call on every remaining agent step. The
 tests not started are skipped with cause `failure-limit`, the ones running
-end as `interrupted`, and the job exits 1.
+end as `interrupted`, counted apart from the failures, and the job exits 1.
 
 ## Exit codes
 

package/docs/debugging.mdx

@@ -91,7 +91,9 @@ failed result:
 
 Artifacts land under `.e2e/artifacts/` (`<output>/artifacts/` when the
 [`output`](/reference/config#output) is moved), one directory per attempt.
-Each run empties it first, so it holds the latest run's evidence:
+Each run empties it first, so it holds the latest run's evidence. A
+`--last-failed` rerun instead empties it down to the files the report it
+reruns names, and writes its own under `rerun-<n>/`:
 
 - **Screenshots.** Failed attempts capture one whenever the engine can and
   pixels are allowed. The built-in `agent.assert` also captures one after
@@ -99,8 +101,9 @@ Each run empties it first, so it holds the latest run's evidence:
   be withheld. Use `app.screenshot('label')` to capture one explicitly.
 - **Playwright traces** on the attempts the [`trace`](/reference/config#trace)
   mode records: every attempt locally, the first retry in CI. Open one with
-  `npx playwright show-trace <file>`; `--trace off` skips the cost for one
-  run, `--trace` records every attempt of a CI run.
+  `npx playwright-core@1.63.0 show-trace <file>` (`pnpm dlx` under pnpm);
+  `--trace off` skips the cost for one run, `--trace` records every attempt
+  of a CI run.
 - **Downloads** saved through `browser.waitForDownload`, recorded with kind
   `download`. They are the app's bytes: `redaction: "incomplete"` unless a
   secret reached the session (filled, or held by the engine for basic auth)