e2e 0.16.0 → 0.18.0

package/dist/run/worker/handle.js

@@ -1,18 +1,22 @@
 /** Child-process `UnitRunner`: spawn, messaging, exit tracking. */
 import { fork } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import { WARNED_TSCONFIGS_ENV, warnedTsconfigs } from '../../config/tsconfig.js';
 import { InfrastructureError } from '../../internal/errors.js';
-/** Resolves the worker entry for both src (vitest, .ts) and dist (.js) layouts. */
+/**
+ * Resolves the worker entry for both src (vitest, .ts) and dist (.js)
+ * layouts. From source, e2e's own loader is registered before the entry
+ * loads (`config/register.ts`): Node.js strips types but does not compile
+ * the rest of TypeScript.
+ */
 function resolveEntry() {
     const js = fileURLToPath(new URL('./entry.js', import.meta.url));
     if (existsSync(js))
         return { path: js, execArgv: [] };
     const ts = fileURLToPath(new URL('./entry.ts', import.meta.url));
     if (existsSync(ts)) {
-        const require = createRequire(import.meta.url);
-        return { path: ts, execArgv: ['--import', require.resolve('tsx')] };
+        return { path: ts, execArgv: ['--import', new URL('../../config/register.ts', import.meta.url).href] };
     }
     throw new InfrastructureError('WORKER_ENTRY_MISSING', 'e2e worker entry module not found');
 }
@@ -32,7 +36,8 @@ class ChildProcessRunner {
             cwd: spawn.projectRoot,
             execArgv: entry.execArgv,
             stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
-            env: spawn.env,
+            // Collecting read the project's tsconfig.json files first; the worker warns only about ones it reaches on its own.
+            env: { ...spawn.env, [WARNED_TSCONFIGS_ENV]: warnedTsconfigs() },
         });
         this.child.on('message', (message) => events.onMessage(message));
         this.exit = new Promise((resolve) => {

package/dist/run/worker/protocol.d.ts

@@ -12,7 +12,8 @@ import type { CliOverrides, PortAssignments, ResolvedTarget } from '../../config
 import type { AiTraceSnapshot } from '../../internal/ai-trace.ts';
 import type { DebugSnapshot } from '../../internal/debug.ts';
 import type { SerializedError } from '../../internal/errors.ts';
-import type { ResultRecord, RunError, SerialGroupRecord, WireResultRecord } from '../records.ts';
+import type { AttemptRecord, ResultRecord, RunError, SerialGroupRecord, SerialMemberRecord, WireResultRecord } from '../records.ts';
+import type { SerialAttemptRun, SerialAttemptStart } from '../serial.ts';
 import type { StepProgress } from '../steps.ts';
 /** One runnable pair on the wire; the worker resolves the test function. */
 export interface WirePair {
@@ -56,6 +57,8 @@ export interface WorkerBootstrap {
     readonly workerSlot: number;
     readonly runId: string;
     readonly artifactsRoot: string;
+    /** See `TargetExecutorOptions.rerunDir`. */
+    readonly rerunDir: string | undefined;
     readonly headed: boolean;
     readonly sessionsRoot: string;
     /** Per-run AES key; transferred only over this channel, never disk or env. */
@@ -105,7 +108,15 @@ export interface ShutdownMessage {
 export interface TerminateMessage {
     readonly type: 'terminate';
 }
-export type MainToWorker = RunUnitMessage | InterruptMessage | ShutdownMessage | TerminateMessage;
+/**
+ * Asks the worker to answer with `pong` from its event loop. The scheduler
+ * sends it only once an attempt is past its test timeout, to tell a worker
+ * still tearing the attempt down from one whose event loop is blocked.
+ */
+export interface PingMessage {
+    readonly type: 'ping';
+}
+export type MainToWorker = RunUnitMessage | InterruptMessage | ShutdownMessage | TerminateMessage | PingMessage;
 export interface ReadyMessage {
     readonly type: 'ready';
 }
@@ -164,6 +175,35 @@ export interface NoticeMessage {
     readonly type: 'notice';
     readonly message: string;
 }
+/**
+ * An attempt's test timeout started: its `beforeEach` hooks and body run
+ * now. The worker enforces the timeout with its own timers, which a body
+ * that blocks the event loop never lets fire, so the scheduler keeps the
+ * deadline too; see `SchedulerWorker.watch`.
+ */
+export interface AttemptDeadlineMessage {
+    readonly type: 'attempt-deadline';
+    readonly testId: string;
+    readonly agent: string;
+    readonly repeat: number;
+    /** The attempt's index among the pair's attempts. */
+    readonly attempt: number;
+    /** The attempt's record id and start, which a watchdog kill reports it with. */
+    readonly attemptId: string;
+    readonly startedAt: string;
+    /** The test's resolved `timeout`. */
+    readonly timeoutMs: number;
+    /** How long past the timeout the worker may go without answering a `ping`: the cleanup budget. */
+    readonly graceMs: number;
+}
+/** The attempt the last `attempt-deadline` announced has ended, verdict and cleanup included. */
+export interface AttemptEndMessage {
+    readonly type: 'attempt-end';
+}
+/** The answer to `ping`. */
+export interface PongMessage {
+    readonly type: 'pong';
+}
 export interface ResultMessage {
     readonly type: 'result';
     readonly result: WireResultRecord;
@@ -172,6 +212,48 @@ export interface SerialGroupMessage {
     readonly type: 'serial-group';
     readonly group: SerialGroupRecord;
 }
+/**
+ * An attempt of an ordinary or setup pair begins, its realm and `beforeAll`
+ * hooks included. With `attempt`, it tells a crash during an attempt from
+ * one between attempts (an `afterAll` after the last one): only the first
+ * is charged a new attempt, with this index.
+ */
+export interface AttemptStartMessage {
+    readonly type: 'attempt-start';
+    readonly testId: string;
+    readonly agent: string;
+    readonly repeat: number;
+    readonly index: number;
+}
+/**
+ * One finished attempt of an ordinary or setup pair. A pair's result waits
+ * for its last attempt, so each attempt also goes out as it ends: a worker
+ * that dies during a retry must not take the attempts before it along. The
+ * result still carries every attempt; the scheduler keeps these only until
+ * it arrives.
+ */
+export interface AttemptMessage {
+    readonly type: 'attempt';
+    readonly testId: string;
+    readonly agent: string;
+    readonly repeat: number;
+    readonly attempt: AttemptRecord;
+}
+/** One member that finished in the serial group attempt running now; see `AttemptMessage`. */
+export interface SerialMemberMessage {
+    readonly type: 'serial-member';
+    /** The group's report id (`SerialGroupRecord.id`). */
+    readonly groupId: string;
+    readonly attempt: SerialAttemptStart;
+    readonly member: SerialMemberRecord;
+}
+/** One finished serial group attempt; see `AttemptMessage`. */
+export interface SerialAttemptMessage {
+    readonly type: 'serial-attempt';
+    /** The group's report id (`SerialGroupRecord.id`). */
+    readonly groupId: string;
+    readonly run: SerialAttemptRun;
+}
 export interface UnitDoneMessage {
     readonly type: 'unit-done';
     readonly unitId: string;
@@ -206,6 +288,6 @@ export interface RunAbortMessage {
     readonly type: 'run-abort';
     readonly error: SerializedError;
 }
-export type WorkerToMain = ReadyMessage | PairStartMessage | ProgressMessage | OutputMessage | NoticeMessage | ResultMessage | SerialGroupMessage | UnitDoneMessage | ShutdownDoneMessage | FatalMessage | RunAbortMessage;
+export type WorkerToMain = ReadyMessage | PairStartMessage | ProgressMessage | AttemptDeadlineMessage | AttemptEndMessage | PongMessage | OutputMessage | NoticeMessage | ResultMessage | SerialGroupMessage | AttemptStartMessage | AttemptMessage | SerialMemberMessage | SerialAttemptMessage | UnitDoneMessage | ShutdownDoneMessage | FatalMessage | RunAbortMessage;
 /** Reattaches the scheduler's resolved target to a wire result. */
 export declare function decodeResult(wire: WireResultRecord, target: ResolvedTarget): ResultRecord;

package/dist/run/worker/session.d.ts

@@ -35,6 +35,8 @@ export interface TargetWorkerDeps {
     readonly sessionStore: SessionStore;
     readonly runId: string;
     readonly artifactsRoot: string;
+    /** See `TargetExecutorOptions.rerunDir`. */
+    readonly rerunDir: string | undefined;
     readonly headed: boolean;
     /** See `TargetExecutorOptions.workerSlot`. */
     readonly workerSlot: number;

package/dist/run/worker/session.js

@@ -4,6 +4,7 @@
  * in-process) drive this class, so unit execution, interrupt handling, and
  * run-error forwarding exist exactly once.
  */
+import inspector from 'node:inspector';
 import { DebugTrace } from '../../internal/debug.js';
 import { TargetExecutor } from '../execute.js';
 import { encodeResult } from '../records.js';
@@ -46,6 +47,7 @@ export class TargetWorker {
                 target: deps.target,
                 runId: deps.runId,
                 artifactsRoot: deps.artifactsRoot,
+                rerunDir: deps.rerunDir,
                 sessionStore: deps.sessionStore,
                 headed: deps.headed,
                 workerSlot: deps.workerSlot,
@@ -65,6 +67,10 @@ export class TargetWorker {
                             this.countFailure();
                     },
                     onSerialGroup: (group) => this.host.emit({ type: 'serial-group', group }),
+                    onAttemptStart: (pair, index) => this.host.emit({ type: 'attempt-start', testId: pair.test.id, agent: pair.agent, repeat: pair.repeat, index }),
+                    onAttempt: (pair, attempt) => this.host.emit({ type: 'attempt', testId: pair.test.id, agent: pair.agent, repeat: pair.repeat, attempt }),
+                    onSerialMember: (groupId, attempt, member) => this.host.emit({ type: 'serial-member', groupId, attempt, member }),
+                    onSerialAttempt: (groupId, run) => this.host.emit({ type: 'serial-attempt', groupId, run }),
                     onPairStart: (pair) => {
                         this.inFlight = { testId: pair.test.id, agent: pair.agent, repeat: pair.repeat };
                         this.host.emit({
@@ -77,6 +83,23 @@ export class TargetWorker {
                             serialId: pair.test.serialId,
                         });
                     },
+                    onAttemptDeadline: (pair, attempt) => {
+                        // A worker paused at a breakpoint looks blocked; with a debugger attached nothing watches its attempts.
+                        if (inspector.url() !== undefined)
+                            return;
+                        this.host.emit({
+                            type: 'attempt-deadline',
+                            testId: pair.test.id,
+                            agent: pair.agent,
+                            repeat: pair.repeat,
+                            attempt: attempt.index,
+                            attemptId: attempt.id,
+                            startedAt: attempt.startedAt,
+                            timeoutMs: pair.options.timeout,
+                            graceMs: deps.config.cleanupTimeout,
+                        });
+                    },
+                    onAttemptEnd: () => this.host.emit({ type: 'attempt-end' }),
                     onProgress: (pair, progress) => this.host.emit({ type: 'progress', testId: pair.test.id, agent: pair.agent, repeat: pair.repeat, progress }),
                     onNotice: (message) => this.host.emit({ type: 'notice', message }),
                     onRunAbort: (runError) => {
@@ -112,6 +135,12 @@ export class TargetWorker {
             case 'terminate':
                 this.terminate();
                 return;
+            case 'ping':
+                // Answered now, not queued behind the running unit: the answer is the proof the event loop turns.
+                this.host.emit({ type: 'pong' });
+                return;
+            default:
+                message;
         }
     }
     /**

package/dist/telemetry/environment.d.ts

@@ -42,7 +42,8 @@ export declare function fleetName(env: NodeJS.ProcessEnv): string | null;
  * The id the environment states for itself, standing in for a machine that
  * has no preferences file: a fleet by its name, else the CI vendor when `CI`
  * is set. Undefined on a person's machine, where the random per-machine id
- * is the unit; a vendor marker alone, without `CI`, does not make one a runner.
+ * is the unit: a vendor marker without `CI` is a shell on a runner, and `CI`
+ * with a coding agent but no vendor is the agent's shell on a laptop.
  */
 export declare function statedIdentity(env: NodeJS.ProcessEnv): string | undefined;
 export declare function collectEnvironment(options: {

package/dist/telemetry/environment.js

@@ -30,6 +30,10 @@ const CI_VENDORS = [
     ['SEMAPHORE', 'semaphore'],
     ['APPVEYOR', 'appveyor'],
     ['WOODPECKER', 'woodpecker'],
+    ['EAS_BUILD', 'eas'],
+    ['BITRISE_IO', 'bitrise'],
+    ['CM_BUILD_ID', 'codemagic'],
+    ['CI_XCODE_CLOUD', 'xcode-cloud'],
 ];
 /**
  * Environment variables coding agents set in the shells they spawn. The
@@ -99,13 +103,19 @@ export function fleetName(env) {
  * The id the environment states for itself, standing in for a machine that
  * has no preferences file: a fleet by its name, else the CI vendor when `CI`
  * is set. Undefined on a person's machine, where the random per-machine id
- * is the unit; a vendor marker alone, without `CI`, does not make one a runner.
+ * is the unit: a vendor marker without `CI` is a shell on a runner, and `CI`
+ * with a coding agent but no vendor is the agent's shell on a laptop.
  */
 export function statedIdentity(env) {
     const fleet = fleetName(env);
     if (fleet !== null)
         return `fleet:${fleet}`;
-    return isCiMode(env) ? `ci:${ciName(env) ?? 'unknown'}` : undefined;
+    if (!isCiMode(env))
+        return undefined;
+    const vendor = firstMarker(env, CI_VENDORS);
+    if (vendor === undefined && firstMarker(env, CODING_AGENTS) !== undefined)
+        return undefined;
+    return `ci:${vendor ?? 'unknown'}`;
 }
 /** The runtime executing this process: Bun and Deno each announce themselves in `process.versions`. */
 function runtime(versions) {

package/dist/telemetry/events.js

@@ -205,6 +205,7 @@ export function runCompletedEvent(report, context) {
             tests_executed: run.summary.executed,
             tests_passed: run.summary.passed,
             tests_failed: run.summary.failed,
+            tests_interrupted: run.summary.interrupted,
             tests_flaky: run.summary.flaky,
             tests_skipped: run.summary.skipped,
             attempts_total: attempts.reduce((total, count) => total + count, 0),

package/dist/telemetry/project.d.ts

@@ -8,10 +8,9 @@
  * commit, which every clone shares and no one can produce without the
  * repository itself; a commit hash carries no name, path, or remote. A
  * shallow clone has no root to offer: its boundary commits pose as roots and
- * move with every fetch, so it is treated like a directory outside git.
- * There, the project root path is hashed together with the machine's local
- * salt, so the id is stable on that machine and unrecoverable anywhere else.
- * In CI there is no salt, so a runner without a full history has no id: its
- * working directory is not a project.
+ * move with every fetch, so it has no id, like a directory outside git: a
+ * path is the same project on one machine only, so it cannot be told apart
+ * from a scratch directory nobody returns to.
  */
-export declare function anonymousProjectId(projectRoot: string, salt: string | undefined): Promise<string | undefined>;
+/** The hashed root commit of the repository at `projectRoot`; undefined outside git and in a shallow clone. */
+export declare function anonymousProjectId(projectRoot: string): Promise<string | undefined>;

package/dist/telemetry/project.js

@@ -8,11 +8,9 @@
  * commit, which every clone shares and no one can produce without the
  * repository itself; a commit hash carries no name, path, or remote. A
  * shallow clone has no root to offer: its boundary commits pose as roots and
- * move with every fetch, so it is treated like a directory outside git.
- * There, the project root path is hashed together with the machine's local
- * salt, so the id is stable on that machine and unrecoverable anywhere else.
- * In CI there is no salt, so a runner without a full history has no id: its
- * working directory is not a project.
+ * move with every fetch, so it has no id, like a directory outside git: a
+ * path is the same project on one machine only, so it cannot be told apart
+ * from a scratch directory nobody returns to.
  */
 import { COMMIT_HASH, git } from '../internal/git.js';
 import { sha256Hex } from '../internal/ids.js';
@@ -31,11 +29,8 @@ async function rootCommit(cwd) {
         .filter((line) => COMMIT_HASH.test(line))
         .toSorted()[0];
 }
-export async function anonymousProjectId(projectRoot, salt) {
+/** The hashed root commit of the repository at `projectRoot`; undefined outside git and in a shallow clone. */
+export async function anonymousProjectId(projectRoot) {
     const commit = await rootCommit(projectRoot);
-    if (commit !== undefined)
-        return sha256Hex(`git\n${commit}`);
-    if (salt === undefined)
-        return undefined;
-    return sha256Hex(`path\n${salt}\n${projectRoot}`);
+    return commit === undefined ? undefined : sha256Hex(`git\n${commit}`);
 }

package/dist/telemetry/store.d.ts

@@ -2,9 +2,11 @@
  * The user-level telemetry preferences: `~/.config/e2e/telemetry.json`
  * (`$XDG_CONFIG_HOME/e2e` when set, `%APPDATA%\e2e` on Windows). The file
  * holds the opt-out, the random id every event from this machine is
- * attributed to, the salt that keeps a hashed path unrecoverable, and which
- * notice was shown when. Nothing in it names the person or the machine: the
- * id and the salt are random bytes, generated here and never derived.
+ * attributed to, and which notice was shown when. Nothing in it names the
+ * person or the machine: the id is random bytes, generated here and never
+ * derived. A complete file also holds a random salt that nothing is hashed
+ * with anymore: older versions hashed paths with it and replace the id of a
+ * file without one, and a machine often has several versions installed.
  *
  * The store fails closed. `open` completes the file in one write when the id
  * or the salt is missing, and when that write cannot happen there is no
@@ -38,8 +40,6 @@ export declare class TelemetryStore {
     get enabled(): boolean;
     /** The random per-machine id every event from this machine is attributed to. */
     get anonymousId(): string;
-    /** The local salt that keeps a hashed project path unrecoverable; never leaves the machine. */
-    get pathSalt(): string;
     /** Whole days since the ids were generated; undefined for a file from before the time was recorded. */
     ageDays(now?: number): number | undefined;
     /** Saves the choice; false when the file could not be written and the choice stayed in memory. */

package/dist/telemetry/store.js

@@ -2,9 +2,11 @@
  * The user-level telemetry preferences: `~/.config/e2e/telemetry.json`
  * (`$XDG_CONFIG_HOME/e2e` when set, `%APPDATA%\e2e` on Windows). The file
  * holds the opt-out, the random id every event from this machine is
- * attributed to, the salt that keeps a hashed path unrecoverable, and which
- * notice was shown when. Nothing in it names the person or the machine: the
- * id and the salt are random bytes, generated here and never derived.
+ * attributed to, and which notice was shown when. Nothing in it names the
+ * person or the machine: the id is random bytes, generated here and never
+ * derived. A complete file also holds a random salt that nothing is hashed
+ * with anymore: older versions hashed paths with it and replace the id of a
+ * file without one, and a machine often has several versions installed.
  *
  * The store fails closed. `open` completes the file in one write when the id
  * or the salt is missing, and when that write cannot happen there is no
@@ -113,10 +115,6 @@ export class TelemetryStore {
     get anonymousId() {
         return this.preferences.anonymousId;
     }
-    /** The local salt that keeps a hashed project path unrecoverable; never leaves the machine. */
-    get pathSalt() {
-        return this.preferences.salt;
-    }
     /** Whole days since the ids were generated; undefined for a file from before the time was recorded. */
     ageDays(now = Date.now()) {
         const created = this.preferences.createdAt;

package/dist/telemetry/telemetry.d.ts

@@ -43,7 +43,7 @@ export interface TelemetryOptions {
     readonly fetch?: typeof fetch;
     /** Where the notice and the debug output go; stderr when absent. */
     readonly write?: (text: string) => void;
-    /** Resolves the anonymous project id; git and the salted path when absent. */
+    /** Resolves the anonymous project id; the hashed root commit when absent. */
     readonly projectId?: typeof anonymousProjectId;
 }
 export declare class Telemetry {
@@ -114,8 +114,7 @@ export declare class Telemetry {
     record(event: TelemetryEvent): void;
     /**
      * Git is asked for the project id now, while the command runs, so the
-     * flush at the end waits on the network alone. A fleet or CI has no
-     * store, so a path outside git has nothing to salt it and yields no id.
+     * flush at the end waits on the network alone.
      */
     private lookUpProject;
     /** The session event, first in the batch; absent for an invocation that never reached a command. */

package/dist/telemetry/telemetry.js

@@ -187,12 +187,10 @@ export class Telemetry {
     }
     /**
      * Git is asked for the project id now, while the command runs, so the
-     * flush at the end waits on the network alone. A fleet or CI has no
-     * store, so a path outside git has nothing to salt it and yields no id.
+     * flush at the end waits on the network alone.
      */
     lookUpProject() {
-        const store = this.statedId === undefined ? this.store() : undefined;
-        this.project ??= this.projectId(this.cwd, store?.pathSalt);
+        this.project ??= this.projectId(this.cwd);
     }
     /** The session event, first in the batch; absent for an invocation that never reached a command. */
     sessionEvent() {

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. */
@@ -265,6 +265,7 @@ export interface SwipeOptions {
     momentum?: Momentum;
     from?: never;
     to?: never;
+    duration?: never;
 }
 /** A swipe along a path between two viewport points: a touch swipe on a device, a pointer drag on a document platform. */
 export interface SwipePathOptions {
@@ -272,6 +273,8 @@ export interface SwipePathOptions {
     from: Point;
     /** Where it lifts. */
     to: Point;
+    /** Gesture duration in milliseconds; omitted = the engine's default. */
+    duration?: number;
     direction?: never;
     momentum?: never;
 }
@@ -377,9 +380,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. */
@@ -1024,9 +1031,9 @@ export interface StoredArtifact {
     readonly path: string;
     /**
      * How much of the file the runner masked, as the report records it. A
-     * `download` is `incomplete` unless the runner rewrote it as text after a
-     * secret fill; a store that exports only what the runner vouches for reads
-     * this rather than the kind.
+     * `download` is `incomplete` unless the runner ran it as text through the
+     * session's secret values; a store that exports only what the runner
+     * vouches for reads this rather than the kind.
      */
     readonly redaction: 'complete' | 'not-required' | 'incomplete';
     readonly runId: string;
@@ -1250,6 +1257,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. */

package/docs/agent-steps.mdx

@@ -1,6 +1,7 @@
 ---
 title: How agent steps work
 description: What the model sees, what it may do, how a step ends, and what it costs.
+icon: "list-check"
 ---
 
 An agent step is one `agent.act`, `agent.assert`, `agent.waitFor`, or

package/docs/agents.mdx

@@ -1,6 +1,7 @@
 ---
 title: Agents and personas
 description: Configure several agents in one suite, pin tests to them, and run one flow as each persona.
+icon: "users"
 ---
 
 Define named agents in `agents` to give tests different models, instructions,
@@ -109,9 +110,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/api-testing.mdx

@@ -1,6 +1,7 @@
 ---
-title: Testing APIs
+title: API
 description: Check your API with fetch and value matchers, in the same files and run as UI tests.
+icon: "server"
 ---
 
 API tests run in the same files and the same run as UI tests. A test that

package/docs/authentication.mdx

@@ -1,6 +1,7 @@
 ---
 title: Signing in
 description: Sign in once, reuse the session across tests, and pass secrets without exposing them to the model.
+icon: "key"
 ---
 
 Sign in once in a setup test and save a named session. Other tests restore
@@ -164,7 +165,7 @@ runner keeps it away from test code and the model altogether.
 
 A `Secret` has no `.value`. Three sinks accept one: the two below in a
 test, and an engine option that declares it, as
-[`basicAuth`](/starting-your-app#protected-previews) does:
+[`basicAuth`](/web#protected-previews) does:
 
 <Tabs>
   <Tab title="Deterministic">
@@ -211,7 +212,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
@@ -277,7 +280,7 @@ account, a username with the secrets that sign it in, while a secret is one
 value, so `credentials.admin` and `secrets.admin` can both exist.
 
 In `e2e.config.ts`, `secrets.get()` hands an engine option a secret it needs
-before any test runs, such as a [basic-auth password](/starting-your-app#protected-previews).
+before any test runs, such as a [basic-auth password](/web#protected-previews).
 The config load checks the name, and the value is redacted once the engine
 resolves it, together with the base64 `Authorization` credential it becomes.
 The protection is text only: screenshots and the model's pixels are kept, so