e2e 0.16.0 → 0.18.0

package/dist/expect/poll-scope.js

@@ -0,0 +1,113 @@
+/** Which phase of a test owns an `expect.poll`, so one left running fails that phase and nothing later. */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { markAbandonedRejection, relocateStack } from '../internal/abandoned.js';
+import { pollScopesBrand } from '../internal/brands.js';
+import { TestError, withHint } from '../internal/errors.js';
+import { realmSlot } from '../internal/realm-slot.js';
+/**
+ * The polls one phase started: a test body with its fixtures and
+ * `beforeEach` hooks, one teardown, or one suite hook. A poll is not a step
+ * and records nothing; what the scope adds is that a poll the phase did not
+ * await ends with the phase instead of failing whatever runs when it times out.
+ */
+export class PollScope {
+    owner;
+    running = new Set();
+    closed = false;
+    /** `owner` completes "... returned before", as in `the test body`. */
+    constructor(owner) {
+        this.owner = owner;
+    }
+    /**
+     * Runs one poll, owned by this scope until it settles. `work` receives the
+     * signal that cancels it when the scope closes first. A poll started after
+     * the scope closed, by work its phase left running (a body past its
+     * timeout), is cancelled before its first read: it belongs to no phase
+     * that could still fail, and must not fail the one running now.
+     */
+    track(label, stack, work) {
+        const poll = { label, stack, controller: new AbortController(), promise: Promise.resolve(), abandoned: false };
+        if (this.closed)
+            this.cancel(poll);
+        const promise = (async () => {
+            try {
+                return await work(poll.controller.signal);
+            }
+            catch (cause) {
+                if (poll.abandoned)
+                    markAbandonedRejection(cause);
+                throw cause;
+            }
+            finally {
+                this.running.delete(poll);
+            }
+        })();
+        poll.promise = promise;
+        if (poll.abandoned)
+            promise.catch(() => undefined);
+        else
+            this.running.add(poll);
+        return promise;
+    }
+    /**
+     * Ends the scope when its phase has returned: every poll still running is
+     * cancelled and its later rejection observed. Returns the error naming
+     * them, at the line of the first, or nothing when every poll had settled.
+     * A caller whose phase was cut short (a timeout, a throw) may drop the
+     * error: the phase may have been awaiting the poll. Closing twice returns
+     * nothing the second time.
+     */
+    close() {
+        this.closed = true;
+        const polls = [...this.running];
+        const [first] = polls;
+        if (first === undefined)
+            return undefined;
+        for (const poll of polls)
+            this.cancel(poll);
+        const more = polls.length > 1 ? ` and ${polls.length - 1} more` : '';
+        const error = new TestError('STEP_NOT_AWAITED', withHint(`${this.owner} returned before ${first.label}${more} finished`, 'put `await` in front of every expect.poll call'));
+        relocateStack(error, first.stack);
+        return error;
+    }
+    cancel(poll) {
+        this.running.delete(poll);
+        poll.abandoned = true;
+        poll.promise.catch(() => undefined);
+        poll.controller.abort();
+    }
+}
+const storage = new AsyncLocalStorage();
+const scopes = { current: () => storage.getStore()?.scope };
+const slot = realmSlot(pollScopesBrand);
+/** Runs `run` in the lineage `owner` names, publishing the runner's context for a test module's `expect`. */
+function enter(owner, run) {
+    if (slot.get(globalThis) !== scopes)
+        slot.set(globalThis, scopes);
+    return storage.run(owner, run);
+}
+/**
+ * Runs `run` with `scope` owning every poll it starts, however deep in its
+ * async work and however long that work outlives the phase: a poll belongs
+ * to the phase that started it, never to the one running when it is called.
+ */
+export function runInPollScope(scope, run) {
+    return enter({ scope }, run);
+}
+/**
+ * A lineage for work that spans two phases, a fixture: its setup runs in the
+ * body's phase, and the rest of its function after `use` is its teardown's.
+ */
+export function pollLineage() {
+    const owner = { scope: scopes.current() };
+    return {
+        run: (run) => enter(owner, run),
+        handOver: () => {
+            owner.scope = scopes.current();
+        },
+    };
+}
+/** The scope a poll started here belongs to, or undefined outside any phase (a standalone script). */
+export function currentPollScope() {
+    return slot.get(globalThis)?.current();
+}

package/dist/expect/poll.js

@@ -1,10 +1,13 @@
 /** expect.poll: re-reads a value until a synchronous matcher passes. */
-import { ConfigurationError, E2EError, TestError } from '../internal/errors.js';
+import { ConfigurationError, E2EError, isE2EError, TestError } from '../internal/errors.js';
 import { Deadline, POLL_INTERVAL_MS, sleep, withAbort, withTimeout } from '../internal/time.js';
 import { currentAttempt } from './attempt.js';
+import { currentPollScope } from './poll-scope.js';
 import { createValueExpectation } from './values.js';
 /** Outside an attempt (a standalone script) there is no config to read `assertionTimeout` from. */
 const DEFAULT_TIMEOUT_MS = 5000;
+/** Frames kept for the line a poll was called on; the user's line is a few frames up. */
+const CALL_STACK_FRAMES = 20;
 /** `satisfies` keeps this list equal to the ValueExpectation matcher set. */
 const MATCHERS = {
     toBe: true,
@@ -36,7 +39,7 @@ function describeError(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function isNotYet(error) {
-    return error instanceof E2EError && error.code === 'ASSERTION_FAILED';
+    return isE2EError(error) && error.code === 'ASSERTION_FAILED';
 }
 function cancelled() {
     return new E2EError('infrastructure', 'CANCELLED', 'operation cancelled');
@@ -46,7 +49,21 @@ function sample(read, deadline, signal) {
     const bounded = withTimeout((async () => read())(), deadline.remaining(), () => new ReadHung());
     return signal === undefined ? bounded : withAbort(bounded, signal, () => new ReadAborted());
 }
-async function pollMatcher(read, options, negated, name, args) {
+/** The stack at a poll's call, for the error that names it when its phase did not await it. */
+function callStack() {
+    const limit = Error.stackTraceLimit;
+    Error.stackTraceLimit = CALL_STACK_FRAMES;
+    try {
+        return new Error().stack;
+    }
+    finally {
+        Error.stackTraceLimit = limit;
+    }
+}
+function matcherLabel(negated, name) {
+    return `expect.poll(...).${negated ? 'not.' : ''}${name}(...)`;
+}
+async function pollMatcher(read, options, negated, name, args, scopeSignal) {
     const attempt = currentAttempt();
     const timeout = options.timeout ?? attempt?.assertionTimeout ?? DEFAULT_TIMEOUT_MS;
     const interval = options.interval ?? POLL_INTERVAL_MS;
@@ -57,9 +74,14 @@ async function pollMatcher(read, options, negated, name, args) {
     // the moment the attempt is cancelled, so a timed-out test never keeps
     // reading through teardown.
     const deadline = attempt === undefined ? own : Deadline.min(own, attempt.budget.deadline);
-    const signal = attempt?.budget.signal;
+    // The phase that started the poll cancels it when it returns without
+    // awaiting it, so the poll can never fail whatever runs after.
+    const signals = [attempt?.budget.signal, scopeSignal].filter((signal) => signal !== undefined);
+    const signal = signals.length === 0 ? undefined : AbortSignal.any(signals);
     let last;
     while (!deadline.expired()) {
+        if (signal?.aborted === true)
+            throw cancelled();
         let value;
         try {
             value = await sample(read, deadline, signal);
@@ -89,7 +111,7 @@ async function pollMatcher(read, options, negated, name, args) {
         ? `timed out after ${timeout} ms`
         : `stopped at the attempt deadline after ${Date.now() - startedAt} ms`;
     throw new TestError('ASSERTION_FAILED', [
-        `expect.poll(...).${negated ? 'not.' : ''}${name}(...) ${ending}`,
+        `${matcherLabel(negated, name)} ${ending}`,
         ...(options.message === undefined ? [] : [options.message]),
         `last: ${last ?? 'no read completed'}`,
     ].join('\n'));
@@ -107,7 +129,12 @@ function checkOptions(options) {
 function build(read, options, negated) {
     const matchers = Object.fromEntries(Object.keys(MATCHERS).map((name) => [
         name,
-        (...args) => pollMatcher(read, options, negated, name, args),
+        (...args) => {
+            const scope = currentPollScope();
+            if (scope === undefined)
+                return pollMatcher(read, options, negated, name, args, undefined);
+            return scope.track(matcherLabel(negated, name), callStack(), (signal) => pollMatcher(read, options, negated, name, args, signal));
+        },
     ]));
     return {
         ...matchers,

package/dist/expect/values.js

@@ -207,14 +207,21 @@ class ValueExpectationImpl {
         this.check(holds(actual), () => `expected ${actual} to be ${phrase} ${expected}`, () => `expected ${actual} not to be ${phrase} ${expected}`);
     }
 }
-/** Walks `keys` into `value`; `present` says whether the whole path resolved. */
+/**
+ * Walks `keys` into `value`; `present` says whether the whole path resolved.
+ * A primitive on the way is read through its wrapper object, as Jest does,
+ * so a string has its `length` and indices; `null` and `undefined` have no
+ * properties.
+ */
 function lookup(value, keys) {
     let current = value;
     for (const key of keys) {
-        if ((typeof current !== 'object' && typeof current !== 'function') || current === null || !(key in current)) {
+        if (current === null || current === undefined)
             return { present: false, value: undefined };
-        }
-        current = current[key];
+        const holder = Object(current);
+        if (!(key in holder))
+            return { present: false, value: undefined };
+        current = holder[key];
     }
     return { present: true, value: current };
 }

package/dist/internal/abandoned.d.ts

@@ -0,0 +1,11 @@
+/** Work a test left running when its phase returned: steps and polls nobody awaited. */
+/** Records `cause` as the rejection of work already failed as not awaited. */
+export declare function markAbandonedRejection(cause: unknown): void;
+/**
+ * Whether an unhandled rejection is abandoned work's: already recorded as
+ * `STEP_NOT_AWAITED`, reaching the process only because the promise the
+ * test did not await rejected with it. Such a rejection is not a fault.
+ */
+export declare function isAbandonedRejection(cause: unknown): boolean;
+/** Points `error` at the frames of `stack`, keeping its own name and message as the first line. */
+export declare function relocateStack(error: Error, stack: string | undefined): void;

package/dist/internal/abandoned.js

@@ -0,0 +1,23 @@
+/** Work a test left running when its phase returned: steps and polls nobody awaited. */
+/** What abandoned work rejected with. The promise the test holds rejects with the same value, and nobody awaits it. */
+const ABANDONED_REJECTIONS = new WeakSet();
+/** Records `cause` as the rejection of work already failed as not awaited. */
+export function markAbandonedRejection(cause) {
+    if (typeof cause === 'object' && cause !== null)
+        ABANDONED_REJECTIONS.add(cause);
+}
+/**
+ * Whether an unhandled rejection is abandoned work's: already recorded as
+ * `STEP_NOT_AWAITED`, reaching the process only because the promise the
+ * test did not await rejected with it. Such a rejection is not a fault.
+ */
+export function isAbandonedRejection(cause) {
+    return typeof cause === 'object' && cause !== null && ABANDONED_REJECTIONS.has(cause);
+}
+/** Points `error` at the frames of `stack`, keeping its own name and message as the first line. */
+export function relocateStack(error, stack) {
+    if (stack === undefined)
+        return;
+    const frames = stack.split('\n').slice(1).join('\n');
+    error.stack = `${error.name}: ${error.message}\n${frames}`;
+}

package/dist/internal/brands.d.ts

@@ -9,3 +9,5 @@ export declare const locatorBrand: unique symbol;
 export declare const expectationBrand: unique symbol;
 /** Slot on `globalThis` naming the running attempt for `expect.poll`. */
 export declare const attemptBrand: unique symbol;
+/** Slot on `globalThis` holding the runner's view of which phase owns an `expect.poll`. */
+export declare const pollScopesBrand: unique symbol;

package/dist/internal/brands.js

@@ -9,3 +9,5 @@ export const locatorBrand = Symbol.for('e2e.locator');
 export const expectationBrand = Symbol.for('e2e.expectation.v1');
 /** Slot on `globalThis` naming the running attempt for `expect.poll`. */
 export const attemptBrand = Symbol.for('e2e.attempt.v1');
+/** Slot on `globalThis` holding the runner's view of which phase owns an `expect.poll`. */
+export const pollScopesBrand = Symbol.for('e2e.pollScopes.v1');

package/dist/internal/client-identity.d.ts

@@ -0,0 +1,9 @@
+/** How e2e names itself to the vendors it calls. */
+/** `e2e/<version> (<platform>; <arch>)`: what every vendor request identifies as. Never another client's name. */
+export declare const USER_AGENT: string;
+/**
+ * Sent with every model call, whichever provider serves it. The AI SDK appends
+ * its own user agent after ours; `http-referer` and `x-title` are the app
+ * attribution the Vercel AI Gateway and OpenRouter read, and others ignore.
+ */
+export declare const MODEL_REQUEST_HEADERS: Readonly<Record<string, string>>;

package/dist/internal/client-identity.js

@@ -0,0 +1,14 @@
+/** How e2e names itself to the vendors it calls. */
+import { packageVersion } from './package-version.js';
+/** `e2e/<version> (<platform>; <arch>)`: what every vendor request identifies as. Never another client's name. */
+export const USER_AGENT = `e2e/${packageVersion(import.meta.url, '../../package.json', '0.0.0')} (${process.platform}; ${process.arch})`;
+/**
+ * Sent with every model call, whichever provider serves it. The AI SDK appends
+ * its own user agent after ours; `http-referer` and `x-title` are the app
+ * attribution the Vercel AI Gateway and OpenRouter read, and others ignore.
+ */
+export const MODEL_REQUEST_HEADERS = {
+    'user-agent': USER_AGENT,
+    'http-referer': 'https://tester.army/e2e',
+    'x-title': 'e2e',
+};

package/dist/internal/errors.d.ts

@@ -3,6 +3,8 @@ import { type SourceLocation } from './source.ts';
 import { type EngineErrorCode } from '../engine/contract.ts';
 /** Message of an arbitrary thrown value, for diagnostics that must not throw. */
 export declare function errorMessage(cause: unknown): string;
+/** Installs the process-wide redactor `serializeError` uses when none is given; `undefined` clears it. */
+export declare function setErrorRedactor(redact: ((text: string) => string) | undefined): void;
 /**
  * The message of a thrown value led by its code when it is an e2e error, as
  * the CLI prints one: `POLICY_DENIED: forbidden URL scheme: file:`. Any
@@ -107,8 +109,13 @@ export declare class E2EError extends Error {
     readonly [E2E_ERROR_MARKER] = true;
     constructor(category: ErrorCategory, code: string, message: string, options?: E2EErrorOptions);
 }
-/** Detects an E2EError created by another copy of this module. */
-export declare function isForeignE2EError(value: unknown): value is Error & {
+/**
+ * True for an E2EError from this module copy or another. An engine imported by
+ * a config file loads its own copy of the runner, so its errors fail
+ * `instanceof E2EError` and every subclass check; test for runner errors with
+ * this, and read the subclass off `category` and `code`.
+ */
+export declare function isE2EError(value: unknown): value is Error & {
     category: ErrorCategory;
     code: string;
     retryable: boolean;
@@ -159,7 +166,7 @@ export declare function serializeError(error: E2EError, extras?: {
     /**
      * Replaces secret values in the message, the details, and the stack: an
      * assertion that observed a secret on screen, or a message that quoted
-     * one, must not carry it into the report. Identity when omitted.
+     * one, must not carry it into the report. Defaults to `setErrorRedactor`'s.
      */
     redact?: ((text: string) => string) | undefined;
 }): SerializedError;

package/dist/internal/errors.js

@@ -1,18 +1,28 @@
 /** Runner-owned error taxonomy and exit-code mapping. */
 import { stripVTControlCharacters } from 'node:util';
+import { realmSlot } from './realm-slot.js';
 import { sourceLocation } from './source.js';
 import { ENGINE_ERROR_CODES, EngineError, RETRYABLE_ENGINE_ERROR_CODES, } from '../engine/contract.js';
 /** Message of an arbitrary thrown value, for diagnostics that must not throw. */
 export function errorMessage(cause) {
     return cause instanceof Error ? cause.message : String(cause);
 }
+/** The redactor `serializeError` falls back to, on `globalThis` so a project's copy of e2e shares it. */
+const redactorSlot = realmSlot('e2e.error-redactor.v1');
+/** Installs the process-wide redactor `serializeError` uses when none is given; `undefined` clears it. */
+export function setErrorRedactor(redact) {
+    if (redact === undefined)
+        redactorSlot.delete(globalThis);
+    else
+        redactorSlot.set(globalThis, redact);
+}
 /**
  * The message of a thrown value led by its code when it is an e2e error, as
  * the CLI prints one: `POLICY_DENIED: forbidden URL scheme: file:`. Any
  * other value is its message alone.
  */
 export function codedMessage(cause) {
-    const code = cause instanceof E2EError || isForeignE2EError(cause) ? `${cause.code}: ` : '';
+    const code = isE2EError(cause) ? `${cause.code}: ` : '';
     return `${code}${errorMessage(cause)}`;
 }
 /**
@@ -129,8 +139,13 @@ const CATEGORIES = new Set([
     'internal',
     'interrupted',
 ]);
-/** Detects an E2EError created by another copy of this module. */
-export function isForeignE2EError(value) {
+/**
+ * True for an E2EError from this module copy or another. An engine imported by
+ * a config file loads its own copy of the runner, so its errors fail
+ * `instanceof E2EError` and every subclass check; test for runner errors with
+ * this, and read the subclass off `category` and `code`.
+ */
+export function isE2EError(value) {
     return (value instanceof Error &&
         value[E2E_ERROR_MARKER] === true &&
         CATEGORIES.has(value.category) &&
@@ -197,8 +212,8 @@ export function combineExitCodes(codes) {
  * non-retryable infrastructure ENGINE_FAILURE.
  */
 export function translateEngineError(cause, suffix = '') {
-    if (cause instanceof E2EError)
-        return cause;
+    if (isE2EError(cause))
+        return classifyError(cause);
     const engineError = asEngineError(cause);
     if (engineError !== undefined) {
         switch (engineError.code) {
@@ -235,7 +250,7 @@ export function translateEngineError(cause, suffix = '') {
  * `Error` from an installer - is infrastructure.
  */
 export function translateProvisioningError(cause, suffix = '') {
-    if (cause instanceof E2EError || isForeignE2EError(cause))
+    if (isE2EError(cause))
         return classifyError(cause);
     if (asEngineError(cause)?.code === 'CANCELLED')
         return translateEngineError(cause);
@@ -245,7 +260,7 @@ export function translateProvisioningError(cause, suffix = '') {
 export function classifyError(value) {
     if (value instanceof E2EError)
         return value;
-    if (isForeignE2EError(value)) {
+    if (isE2EError(value)) {
         const details = value.details;
         return new E2EError(value.category, value.code, value.message, {
             retryable: value.retryable,
@@ -264,7 +279,7 @@ export function classifyError(value) {
 const MAX_MESSAGE_BYTES = 8192;
 /** Serializes an error into the bounded report-1 error shape. */
 export function serializeError(error, extras = {}) {
-    const redact = extras.redact ?? ((text) => text);
+    const redact = extras.redact ?? redactorSlot.get(globalThis) ?? ((text) => text);
     const serialized = {
         category: error.category,
         code: error.code,

package/dist/internal/node-version.d.ts

@@ -1,9 +1,18 @@
 /**
- * The Node.js floor, checked before the CLI loads anything else. Package
- * managers only warn about `engines`, so an unsupported runtime would
- * otherwise surface as an unrelated TypeError deep inside a run.
+ * The Node.js releases e2e runs on, as a set of release ranges. The CLI checks the floor before it loads
+ * anything else: package managers only warn about `engines`, so an
+ * unsupported runtime would otherwise surface as an unrelated TypeError deep
+ * inside a run.
  */
-/** Mirrors `engines.node` in package.json; a unit test keeps the two in step. */
-export declare const MINIMUM_NODE_VERSION = "22.12.0";
-/** Explains an unsupported runtime, or undefined when `current` meets the floor. */
-export declare function unsupportedNodeMessage(current: string, minimum?: string): string | undefined;
+/** `engines.node` in package.json; a unit test keeps the two in step. */
+export declare const SUPPORTED_NODE_RANGE: string;
+/**
+ * Explains a runtime e2e cannot run on, or undefined for one it can: a
+ * Node.js outside `SUPPORTED_NODE_RANGE`, or a runtime that reports a
+ * supported Node.js version without Node.js's `module.registerHooks` (Bun),
+ * which e2e's TypeScript loader runs on, or Deno.
+ */
+export declare function unsupportedRuntimeMessage(versions?: Pick<NodeJS.ProcessVersions, 'node'> & {
+    readonly bun?: string;
+    readonly deno?: string;
+}, hasRegisterHooks?: boolean): string | undefined;

package/dist/internal/node-version.js

@@ -1,10 +1,10 @@
 /**
- * The Node.js floor, checked before the CLI loads anything else. Package
- * managers only warn about `engines`, so an unsupported runtime would
- * otherwise surface as an unrelated TypeError deep inside a run.
+ * The Node.js releases e2e runs on, as a set of release ranges. The CLI checks the floor before it loads
+ * anything else: package managers only warn about `engines`, so an
+ * unsupported runtime would otherwise surface as an unrelated TypeError deep
+ * inside a run.
  */
-/** Mirrors `engines.node` in package.json; a unit test keeps the two in step. */
-export const MINIMUM_NODE_VERSION = '22.12.0';
+import nodeModule from 'node:module';
 function parse(version) {
     const [major = 0, minor = 0, patch = 0] = version
         .replace(/^v/, '')
@@ -12,16 +12,51 @@ function parse(version) {
         .map((part) => Number.parseInt(part, 10) || 0);
     return [major, minor, patch];
 }
-/** Explains an unsupported runtime, or undefined when `current` meets the floor. */
-export function unsupportedNodeMessage(current, minimum = MINIMUM_NODE_VERSION) {
-    const have = parse(current);
-    const need = parse(minimum);
+function atLeast(have, need) {
     for (let i = 0; i < 3; i += 1) {
-        if (have[i] > need[i])
-            return undefined;
-        if (have[i] < need[i]) {
-            return `e2e requires Node.js ${minimum} or newer; this is Node.js ${current.replace(/^v/, '')}. Upgrade Node.js, or switch versions with your version manager (nvm use 22, fnm use 22, volta pin node@22).`;
-        }
+        if (have[i] !== need[i])
+            return have[i] > need[i];
     }
-    return undefined;
+    return true;
+}
+function within(version, ranges) {
+    const have = parse(version);
+    return ranges.some((range) => ('line' in range ? have[0] === range.line : true) && atLeast(have, range.since));
+}
+/**
+ * Where e2e's TypeScript loader works. It runs on `module.registerHooks`, and
+ * before these releases a CommonJS file an ES module imported cannot
+ * `require()` an ES module the hooks load, such as a project's TypeScript:
+ * Node.js throws reading its own cache (nodejs/node#59679, in 22.22.3 and
+ * 24.8.0). Node.js 23 has no such release.
+ */
+const SUPPORTED = [
+    { line: 22, since: [22, 22, 3] },
+    { since: [24, 8, 0] },
+];
+/** `engines.node` in package.json; a unit test keeps the two in step. */
+export const SUPPORTED_NODE_RANGE = SUPPORTED.map((range) => `${'line' in range ? '^' : '>='}${range.since.join('.')}`).join(' || ');
+/** Explains a Node.js outside `SUPPORTED_NODE_RANGE`, or undefined for one inside it. */
+function unsupportedNodeMessage(current) {
+    if (within(current, SUPPORTED))
+        return undefined;
+    const required = SUPPORTED.map((range) => ('line' in range ? `${range.since.join('.')} or newer on Node.js ${range.line}` : `${range.since.join('.')} or newer`)).join(', or ');
+    return `e2e requires Node.js ${required}; this is Node.js ${current.replace(/^v/, '')}. Upgrade Node.js, or switch versions with your version manager (nvm install 24, fnm install 24, volta install node@24).`;
+}
+/**
+ * Explains a runtime e2e cannot run on, or undefined for one it can: a
+ * Node.js outside `SUPPORTED_NODE_RANGE`, or a runtime that reports a
+ * supported Node.js version without Node.js's `module.registerHooks` (Bun),
+ * which e2e's TypeScript loader runs on, or Deno.
+ */
+export function unsupportedRuntimeMessage(versions = process.versions, hasRegisterHooks = typeof nodeModule.registerHooks === 'function') {
+    // Deno implements module.registerHooks, but not the require() of a native addon from inside a hook that oxc needs.
+    if (versions.deno !== undefined)
+        return `e2e runs on Node.js, not Deno ${versions.deno}: run the CLI with Node.js (npx e2e).`;
+    // Checked before the Node.js version a runtime reports, which upgrading Node.js does not change.
+    if (!hasRegisterHooks) {
+        const runtime = versions.bun !== undefined ? `Bun ${versions.bun}` : 'This runtime';
+        return `e2e runs on Node.js: ${runtime} reports Node.js ${versions.node} but has no module.registerHooks, which e2e's TypeScript loader needs. Run the CLI with Node.js: npx e2e, or bunx e2e (without --bun).`;
+    }
+    return unsupportedNodeMessage(versions.node);
 }

package/dist/internal/package-manager.js

@@ -44,7 +44,7 @@ export function runScriptCommand(manager, name) {
 export function execCommand(manager, command) {
     switch (manager) {
         case 'npm':
-            return `npm exec ${command}`;
+            return `npm exec -- ${command}`;
         case 'pnpm':
             return `pnpm exec ${command}`;
         case 'yarn':

package/dist/internal/realm-slot.d.ts

@@ -1,8 +1,9 @@
 /**
- * Typed accessor for a `Symbol.for` slot on a host object. Test modules load
- * in isolated module realms (tsx), so runner-owned instances are shared
- * through registry symbols instead of module state. All unsafe reads live
- * here; call sites stay fully typed.
+ * Typed accessor for a `Symbol.for` slot on a host object. A project can load
+ * a copy of e2e other than the runner's (a second install, a linked checkout,
+ * a fresh module registry under a test runner), so runner-owned instances are
+ * shared through registry symbols instead of module state. All unsafe reads
+ * live here; call sites stay fully typed.
  */
 export interface RealmSlot<T> {
     set(host: object, value: T): void;

package/dist/internal/redact.d.ts

@@ -37,6 +37,8 @@ export declare class SecretLedger {
     register(name: string, value: string): void;
     /** Bound so it can be handed out as a plain function. */
     readonly redact: (text: string) => string;
+    /** Whether no value is registered, so there is nothing to redact. */
+    get isEmpty(): boolean;
     /** Every registered name and value, in registration order. */
     entries(): readonly (readonly [string, string])[];
     /**
@@ -47,9 +49,12 @@ export declare class SecretLedger {
      * `FRAGMENT_LENGTH` characters, or half of a value shorter than twice that.
      * A cut is one position, so a boundary this short seldom matches plain text
      * by chance. Matched as the value is written, in any case (`caseKey`), as
-     * a CSS `text-transform` shows it: the cut falls on text as the engine read
-     * it, before any serializer spells it. A case mapping that changes length
-     * (`ß` to `SS`) is not followed, nor is collapsed whitespace. The part is found before whole values are
+     * a CSS `text-transform` shows it, and with every whitespace run on both
+     * sides read as one space (`readingKey`) and the value's leading whitespace
+     * dropped where whole-value matching trims it (`valuePattern`), as an
+     * engine that collapses text before cutting it shows it: the cut falls on
+     * text as the engine read it, before any serializer spells it. A case
+     * mapping that changes length (`ß` to `SS`) is not followed. The part is found before whole values are
      * rewritten, so a value that starts with another registered value is not
      * half rewritten as the shorter one, and an occurrence running into the
      * part joins its marker. Bound like `redact`.
@@ -61,7 +66,7 @@ export declare class SecretLedger {
      * becomes its marker. For a recording that keeps what an engine read raw
      * (a Playwright trace holds the page's cut text and selections), where a
      * value cut or selected partway through survives whole-value matching.
-     * Matched as the value is written, in any case, like `redactCut`. A
+     * Matched in any case and with whitespace runs collapsed, like `redactCut`. A
      * base64 or base64url run that decodes to text holding a value or a
      * fragment is rewritten whole (a basic-auth header the engine sent). Bound
      * like `redact`.