e2e 0.16.0 → 0.18.0

package/dist/config/tsconfig.d.ts

@@ -0,0 +1,56 @@
+/**
+ * What the loader reads about the project besides the modules themselves:
+ * the tsconfig.json that governs a file (the nearest one above it, the way
+ * `tsc` finds it, with `extends` applied, or the project it references that
+ * includes the file) and which candidate files exist.
+ *
+ * Both are kept with the module graph that read them, the way the graph's
+ * modules are: a fresh graph (a config loaded with `graph: true`, which
+ * carries `e2e-graph` on every project file) reads its tsconfig.json and
+ * file lookups once, as they are when it loads. Every other load in the
+ * process shares one view, whose tsconfig.json is read once (collecting
+ * fifty test files reads the `extends` chain once) and whose file lookups
+ * ask the disk each time, as Node.js's own resolution does, so a test file
+ * imported again sees files added or removed since.
+ */
+import { type PathsMatcher, type TsConfigJson } from 'get-tsconfig';
+export type CompilerOptions = TsConfigJson.CompilerOptions;
+export interface ProjectTsconfig {
+    readonly compilerOptions: CompilerOptions;
+    /** The candidate files a bare specifier maps to through `paths` or `baseUrl`; null when it sets neither. */
+    readonly paths: PathsMatcher | null;
+}
+/** Carries the tsconfig.json files the runner warned about to its workers, so each file is reported once per run. */
+export declare const WARNED_TSCONFIGS_ENV = "E2E_WARNED_TSCONFIGS";
+/** The tsconfig.json files warned about so far, as the value of `WARNED_TSCONFIGS_ENV` for a worker. */
+export declare function warnedTsconfigs(): string;
+/** The project as one module graph sees it. */
+export declare class ProjectView {
+    /** The nearest tsconfig.json of each directory looked up so far; undefined where none is above it. */
+    private readonly nearest;
+    /** Each tsconfig.json read so far; undefined for one that could not be read. */
+    private readonly read;
+    /** get-tsconfig's own cache of the files it read. */
+    private readonly reads;
+    /** File lookups answered so far, for a graph's view; undefined where the disk is asked each time. */
+    private readonly files;
+    constructor(memoizeFiles: boolean);
+    /**
+     * The tsconfig that governs `file`, or undefined when no readable
+     * tsconfig.json is above it. A solution-style tsconfig.json (`files: []`
+     * and `references`, as Vite writes) hands a file to the referenced
+     * tsconfig that includes it, the way TypeScript's editor support does.
+     */
+    tsconfigFor(file: string): ProjectTsconfig | undefined;
+    /**
+     * `tsconfigPath` read with its `extends` chain, or undefined when it
+     * cannot be, with a warning: an `extends` naming a package that is not
+     * installed (`@tsconfig/node22`) should not stop a run, so TypeScript
+     * compiles with default settings and no `paths` instead.
+     */
+    private readTsconfig;
+    /** Whether `file` is a regular file. */
+    isFile(file: string): boolean;
+}
+/** The view of the module graph `graph` names (the `e2e-graph` value of a URL), or the shared one for null. */
+export declare function projectView(graph: string | null): ProjectView;

package/dist/config/tsconfig.js

@@ -0,0 +1,115 @@
+/**
+ * What the loader reads about the project besides the modules themselves:
+ * the tsconfig.json that governs a file (the nearest one above it, the way
+ * `tsc` finds it, with `extends` applied, or the project it references that
+ * includes the file) and which candidate files exist.
+ *
+ * Both are kept with the module graph that read them, the way the graph's
+ * modules are: a fresh graph (a config loaded with `graph: true`, which
+ * carries `e2e-graph` on every project file) reads its tsconfig.json and
+ * file lookups once, as they are when it loads. Every other load in the
+ * process shares one view, whose tsconfig.json is read once (collecting
+ * fifty test files reads the `extends` chain once) and whose file lookups
+ * ask the disk each time, as Node.js's own resolution does, so a test file
+ * imported again sees files added or removed since.
+ */
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { createFilesMatcher, createPathsMatcher, findTsconfig, parseTsconfig } from 'get-tsconfig';
+/** Carries the tsconfig.json files the runner warned about to its workers, so each file is reported once per run. */
+export const WARNED_TSCONFIGS_ENV = 'E2E_WARNED_TSCONFIGS';
+/** The tsconfig.json files a warning was printed for: in this process, or in the runner that spawned it. */
+const warned = new Set((process.env[WARNED_TSCONFIGS_ENV] ?? '').split(path.delimiter).filter((file) => file !== ''));
+/** The tsconfig.json files warned about so far, as the value of `WARNED_TSCONFIGS_ENV` for a worker. */
+export function warnedTsconfigs() {
+    return [...warned].join(path.delimiter);
+}
+/** The tsconfig.json a project reference names: the file, or `tsconfig.json` in the directory. */
+function referencedTsconfig(owner, reference) {
+    const target = path.resolve(path.dirname(owner), reference);
+    return target.endsWith('.json') ? target : path.join(target, 'tsconfig.json');
+}
+/** The project as one module graph sees it. */
+export class ProjectView {
+    /** The nearest tsconfig.json of each directory looked up so far; undefined where none is above it. */
+    nearest = new Map();
+    /** Each tsconfig.json read so far; undefined for one that could not be read. */
+    read = new Map();
+    /** get-tsconfig's own cache of the files it read. */
+    reads = new Map();
+    /** File lookups answered so far, for a graph's view; undefined where the disk is asked each time. */
+    files;
+    constructor(memoizeFiles) {
+        this.files = memoizeFiles ? new Map() : undefined;
+    }
+    /**
+     * The tsconfig that governs `file`, or undefined when no readable
+     * tsconfig.json is above it. A solution-style tsconfig.json (`files: []`
+     * and `references`, as Vite writes) hands a file to the referenced
+     * tsconfig that includes it, the way TypeScript's editor support does.
+     */
+    tsconfigFor(file) {
+        const directory = path.dirname(file);
+        if (!this.nearest.has(directory))
+            this.nearest.set(directory, findTsconfig(directory, 'tsconfig.json', this.reads));
+        const nearest = this.nearest.get(directory);
+        const root = nearest === undefined ? undefined : this.readTsconfig(nearest);
+        if (root === undefined || root.references.length === 0 || root.includes(file) !== undefined)
+            return root?.tsconfig;
+        for (const reference of root.references) {
+            const referenced = this.readTsconfig(reference);
+            if (referenced !== undefined && referenced.includes(file) !== undefined)
+                return referenced.tsconfig;
+        }
+        return root.tsconfig;
+    }
+    /**
+     * `tsconfigPath` read with its `extends` chain, or undefined when it
+     * cannot be, with a warning: an `extends` naming a package that is not
+     * installed (`@tsconfig/node22`) should not stop a run, so TypeScript
+     * compiles with default settings and no `paths` instead.
+     */
+    readTsconfig(tsconfigPath) {
+        if (this.read.has(tsconfigPath))
+            return this.read.get(tsconfigPath);
+        let read;
+        try {
+            const result = { path: tsconfigPath, config: parseTsconfig(tsconfigPath, this.reads) };
+            read = {
+                tsconfig: { compilerOptions: result.config.compilerOptions ?? {}, paths: createPathsMatcher(result) },
+                includes: createFilesMatcher(result),
+                references: (result.config.references ?? []).map((reference) => referencedTsconfig(tsconfigPath, reference.path)),
+            };
+        }
+        catch (cause) {
+            if (!warned.has(tsconfigPath)) {
+                warned.add(tsconfigPath);
+                const reason = cause instanceof Error ? cause.message : String(cause);
+                process.emitWarning(`e2e ignores ${tsconfigPath}, which it cannot read (${reason}): TypeScript compiles with default settings and no paths`);
+            }
+        }
+        this.read.set(tsconfigPath, read);
+        return read;
+    }
+    /** Whether `file` is a regular file. */
+    isFile(file) {
+        let known = this.files?.get(file);
+        if (known === undefined) {
+            known = statSync(file, { throwIfNoEntry: false })?.isFile() === true;
+            this.files?.set(file, known);
+        }
+        return known;
+    }
+}
+/** One view per graph key; the empty key is every load outside a fresh graph. */
+const views = new Map();
+/** The view of the module graph `graph` names (the `e2e-graph` value of a URL), or the shared one for null. */
+export function projectView(graph) {
+    const key = graph ?? '';
+    let view = views.get(key);
+    if (view === undefined) {
+        view = new ProjectView(graph !== null);
+        views.set(key, view);
+    }
+    return view;
+}

package/dist/config/typescript.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Compiles a TypeScript or JSX file to JavaScript this Node.js runs, with
+ * oxc. The output carries an inline source map, so stack traces, a test's
+ * location, and failure code frames point at the source. Syntax the running
+ * Node.js lacks (`using`, for one) is lowered for it, with helpers from e2e's
+ * own copy of `@oxc-project/runtime`, which the project need not install.
+ * The caller passes the compiler options that change what runs: JSX, legacy
+ * decorators, class field semantics, and import elision.
+ */
+import { type CompiledExtension } from './compiled-files.ts';
+import type { CompilerOptions } from './tsconfig.ts';
+/**
+ * `source`, the content of `file` as the next loader handed it over,
+ * compiled to JavaScript for its kind with `compilerOptions`, with an
+ * inline source map. When an earlier loader already compiled the file and
+ * left its own inline map, the two are composed, so positions still lead to
+ * the file on disk.
+ */
+export declare function compileTypeScript(file: string, source: string, kind: CompiledExtension, compilerOptions: CompilerOptions): string;

package/dist/config/typescript.js

@@ -0,0 +1,253 @@
+/**
+ * Compiles a TypeScript or JSX file to JavaScript this Node.js runs, with
+ * oxc. The output carries an inline source map, so stack traces, a test's
+ * location, and failure code frames point at the source. Syntax the running
+ * Node.js lacks (`using`, for one) is lowered for it, with helpers from e2e's
+ * own copy of `@oxc-project/runtime`, which the project need not install.
+ * The caller passes the compiler options that change what runs: JSX, legacy
+ * decorators, class field semantics, and import elision.
+ */
+import remapping, {} from '@jridgewell/remapping';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { InfrastructureError } from '../internal/errors.js';
+import { HOOKED_REQUIRE_KEY } from './compiled-files.js';
+const ownRequire = createRequire(import.meta.url);
+/** oxc's transformer and parser, loaded on first use. */
+let compiler;
+/**
+ * oxc, loaded when the first file compiles rather than when e2e loads, so
+ * a command that compiles nothing (`--version`, `--help`) still runs
+ * without oxc's native binding. npm leaves that binding out with
+ * `--omit=optional`, and from a lockfile written on another platform
+ * (npm/cli#4828); the error names it and the way back.
+ */
+function oxc() {
+    if (compiler !== undefined)
+        return compiler;
+    try {
+        compiler = { transform: ownRequire('oxc-transform'), parser: ownRequire('oxc-parser') };
+    }
+    catch (cause) {
+        const reason = (cause instanceof Error ? cause.message : String(cause)).split('\n')[0];
+        // napi-rs's loader says so when no platform package is installed.
+        const missingBinding = /Cannot find native binding/.test(String(cause?.message));
+        const platform = `${process.platform}-${process.arch}`;
+        const fix = missingBinding
+            ? `its native bindings for ${platform} (@oxc-transform/binding-${platform}* and @oxc-parser/binding-${platform}*) are not installed. npm skips it with --omit=optional, or when package-lock.json was written on another platform (npm/cli#4828): install again without --omit=optional, or delete package-lock.json and node_modules and run npm install`
+            : `it could not be loaded (${reason})`;
+        throw new InfrastructureError('TYPESCRIPT_COMPILER_UNAVAILABLE', `e2e compiles TypeScript with oxc, and ${fix}`, { cause });
+    }
+    return compiler;
+}
+/** The first ECMAScript edition that defines class fields rather than assigning them. */
+const DEFINED_FIELDS_SINCE = 2022;
+/** JSX as the tsconfig asks for it; classic `React.createElement` when it names no automatic runtime. */
+function jsxOptions(options) {
+    if (options.jsx === 'react-jsx' || options.jsx === 'react-jsxdev') {
+        return { runtime: 'automatic', importSource: options.jsxImportSource ?? 'react', development: options.jsx === 'react-jsxdev' };
+    }
+    return {
+        runtime: 'classic',
+        pragma: options.jsxFactory ?? 'React.createElement',
+        pragmaFrag: options.jsxFragmentFactory ?? 'React.Fragment',
+    };
+}
+/**
+ * The ECMAScript year a tsconfig `target` names, or undefined for `ESNext`
+ * and an unset target. `ES6` is 2015; `ES3` and `ES5` count as 2009, the
+ * year of ES5.
+ */
+function targetYear(target) {
+    const edition = /^es(\d+)$/i.exec(target ?? '')?.[1];
+    if (edition === undefined)
+        return undefined;
+    const number = Number(edition);
+    if (number === 6)
+        return 2015;
+    return number < 2015 ? 2009 : number;
+}
+/**
+ * `useDefineForClassFields` as TypeScript reads it: explicit, or false for a
+ * target below ES2022. An unset target keeps define semantics, as esbuild did.
+ */
+function definesClassFields(options) {
+    if (options.useDefineForClassFields !== undefined)
+        return options.useDefineForClassFields;
+    const year = targetYear(options.target);
+    return year === undefined || year >= DEFINED_FIELDS_SINCE;
+}
+/** The oxc options a tsconfig's compiler options call for. */
+function transformOptions(options) {
+    const assignsFields = !definesClassFields(options);
+    return {
+        jsx: jsxOptions(options),
+        typescript: {
+            onlyRemoveTypeImports: options.verbatimModuleSyntax === true,
+            removeClassFieldsWithoutInitializer: assignsFields,
+        },
+        assumptions: { setPublicClassFields: assignsFields },
+        ...(options.experimentalDecorators === true
+            ? { decorator: { legacy: true, emitDecoratorMetadata: options.emitDecoratorMetadata === true } }
+            : {}),
+    };
+}
+/** `file:line:column: message` for one oxc-transform error; it counts UTF-8 bytes, an editor counts characters. */
+function describeError(file, source, error) {
+    const start = error.labels[0]?.start;
+    if (start === undefined)
+        return `${file}: ${error.message}`;
+    return `${file}:${position(source.subarray(0, start).toString('utf8'))}: ${error.message}`;
+}
+/** `line:column` just past `text`, both counted from 1. */
+function position(text) {
+    const lines = text.split('\n');
+    return `${lines.length}:${lines.at(-1).length + 1}`;
+}
+/**
+ * Syntax oxc 0.152 passes through unchanged that Node.js cannot run, found
+ * before compiling so the error names the line and the fix instead of a
+ * bare `SyntaxError` from Node.js with no location. Each check only parses
+ * a file whose text could hold the construct.
+ */
+function rejectUnsupportedSyntax(file, source, kind, options) {
+    const legacyDecorators = options.experimentalDecorators === true;
+    const commonJs = kind.format === 'commonjs';
+    // A decorator's `@` starts a line or follows whitespace or punctuation, which rules out a package import ('@scope/pkg').
+    const mayHold = (commonJs && /\b(?:import|export)\b/.test(source)) || /\baccessor\b/.test(source) || (!legacyDecorators && /(?:^|[\s(,;{}])@[A-Za-z_$]/m.test(source));
+    if (!mayHold)
+        return;
+    const parsed = oxc().parser.parseSync(file, source, { lang: kind.lang, sourceType: kind.format });
+    const problems = [];
+    if (commonJs) {
+        for (const declaration of parsed.module.staticImports) {
+            if (declaration.entries.length === 0 || declaration.entries.some((entry) => !entry.isType)) {
+                problems.push({ start: declaration.start, message: 'a .cts file is CommonJS, and e2e does not turn an import declaration into require(): write `import name = require(...)`, or `import type` for types' });
+            }
+        }
+        for (const declaration of parsed.module.staticExports) {
+            // `export interface`, `export type`, and `export declare` emit nothing, as tsc allows in .cts.
+            if (declaration.entries.every((entry) => entry.isType))
+                continue;
+            problems.push({ start: declaration.start, message: 'a .cts file is CommonJS, and e2e does not turn an export declaration into module.exports: write `export = ...`' });
+        }
+    }
+    const { Visitor } = oxc().parser;
+    new Visitor({
+        AccessorProperty(node) {
+            problems.push({ start: node.start, message: '`accessor` class fields (auto-accessors) are not supported: oxc, which compiles e2e\'s TypeScript, does not lower them yet; write a getter and setter over a private field' });
+        },
+        Decorator(node) {
+            if (!legacyDecorators) {
+                problems.push({ start: node.start, message: 'decorators need `"experimentalDecorators": true` in tsconfig.json: e2e compiles TypeScript\'s legacy decorators, and Node.js does not run standard decorators yet' });
+            }
+        },
+    }).visit(parsed.program);
+    if (problems.length > 0) {
+        throw new SyntaxError(problems.map(({ start, message }) => `${file}:${position(source.slice(0, start))}: ${message}`).join('\n'));
+    }
+}
+/**
+ * A `require` that runs resolve hooks, for compiled CommonJS. The `require`
+ * Node.js hands a CommonJS module an ES module imported skips them: before
+ * nodejs/node#62920 (24.18.0, 26.2.0; not in Node.js 22), and on every
+ * version once a `module.register` loader is in the chain too (Yarn PnP,
+ * tsx through NODE_OPTIONS). Without it, `require('./helper')` from such a
+ * module misses `helper.ts`, a tsconfig alias, and the helpers compiled code
+ * requires from e2e's install. The loader puts the function on `globalThis`
+ * when it registers (`esm-hooks.ts`): the `require` such a module starts
+ * with cannot load another ES module, e2e's included.
+ */
+const HOOKED_REQUIRE = `require = globalThis[Symbol.for(${JSON.stringify(HOOKED_REQUIRE_KEY)})](__filename);`;
+/**
+ * Compiled CommonJS as Node.js can run it, read from oxc's own parse of
+ * the output:
+ * - Oxc keeps a file whose only imports were type-only a module by printing
+ *   `export {};`, even for CommonJS, where that statement is a syntax error
+ *   and TypeScript emits nothing. It is an oxc bug, not yet reported
+ *   upstream (oxc 0.152.0, `crates/oxc_transformer/src/typescript/
+ *   annotations.rs`, the `no_modules_remaining && some_modules_deleted`
+ *   branch). The statement is blanked out, so nothing after it moves.
+ * - `HOOKED_REQUIRE` follows the last directive on
+ *   its line, so the prologue stays first and no mapped position moves; with
+ *   no directive it takes a line of its own at the top (after a hashbang),
+ *   and the source map gains an unmapped line there.
+ */
+function runnableCommonJs(file, code, mappings) {
+    const { program } = oxc().parser.parseSync(file, code, { lang: 'js', sourceType: 'commonjs' });
+    let runnable = code;
+    for (const statement of program.body) {
+        if (statement.type === 'ExportNamedDeclaration' && statement.declaration === null && statement.source === null && statement.specifiers.length === 0) {
+            runnable = `${runnable.slice(0, statement.start)}${' '.repeat(statement.end - statement.start)}${runnable.slice(statement.end)}`;
+        }
+    }
+    const directives = program.body.filter((statement) => statement.type === 'ExpressionStatement' && typeof statement.directive === 'string');
+    const last = directives.at(-1);
+    if (last !== undefined)
+        return { code: `${runnable.slice(0, last.end)} ${HOOKED_REQUIRE}${runnable.slice(last.end)}`, mappings };
+    const line = program.hashbang === null ? 0 : 1;
+    const lines = runnable.split('\n');
+    lines.splice(line, 0, HOOKED_REQUIRE);
+    const mappedLines = mappings.split(';');
+    mappedLines.splice(line, 0, '');
+    return { code: lines.join('\n'), mappings: mappedLines.join(';') };
+}
+/** Each helper's file in e2e's copy of `@oxc-project/runtime`, resolved once. */
+const helperFiles = new Map();
+/**
+ * The compiled code with each runtime helper it imports or requires taken
+ * from e2e's own copy: by URL for `import`, by path for `require`. Oxc 0.152
+ * has no option to name the helper source, so the import and require
+ * specifiers it printed (`helpersUsed`) are rewritten; a redirect of the
+ * package name in the resolver would also catch a project's own
+ * `@oxc-project/runtime` imports.
+ */
+function withOwnHelpers(code, helpers, format) {
+    let rewritten = code;
+    for (const specifier of new Set(Object.values(helpers))) {
+        let file = helperFiles.get(specifier);
+        if (file === undefined) {
+            file = ownRequire.resolve(specifier);
+            helperFiles.set(specifier, file);
+        }
+        const written = JSON.stringify(specifier);
+        rewritten =
+            format === 'module'
+                ? rewritten.replaceAll(` from ${written};`, ` from ${JSON.stringify(pathToFileURL(file).href)};`)
+                : rewritten.replaceAll(`require(${written})`, `require(${JSON.stringify(file)})`);
+    }
+    return rewritten;
+}
+/** An inline source map at the end of `source`, as another loader earlier in the chain leaves one. */
+const INLINE_MAP = /\n\/\/# sourceMappingURL=data:application\/json(?:;charset=utf-8)?;base64,([A-Za-z0-9+/=]+)\s*$/;
+/**
+ * `source`, the content of `file` as the next loader handed it over,
+ * compiled to JavaScript for its kind with `compilerOptions`, with an
+ * inline source map. When an earlier loader already compiled the file and
+ * left its own inline map, the two are composed, so positions still lead to
+ * the file on disk.
+ */
+export function compileTypeScript(file, source, kind, compilerOptions) {
+    rejectUnsupportedSyntax(file, source, kind, compilerOptions);
+    const result = oxc().transform.transformSync(file, source, {
+        ...transformOptions(compilerOptions),
+        lang: kind.lang,
+        sourceType: kind.format,
+        target: `node${process.versions.node}`,
+        sourcemap: true,
+    });
+    const errors = result.errors.filter((error) => error.severity === 'Error');
+    if (errors.length > 0) {
+        const bytes = Buffer.from(source, 'utf8');
+        throw new SyntaxError(errors.map((error) => describeError(file, bytes, error)).join('\n'));
+    }
+    let code = withOwnHelpers(result.code, result.helpersUsed, kind.format);
+    let mappings = result.map?.mappings ?? '';
+    if (kind.format === 'commonjs')
+        ({ code, mappings } = runnableCommonJs(file, code, mappings));
+    // Absolute, so a frame names the file without the loader's query, whatever characters its name holds.
+    const own = { version: 3, mappings, names: result.map?.names ?? [], sources: [pathToFileURL(file).href] };
+    const incoming = INLINE_MAP.exec(source)?.[1];
+    const map = incoming === undefined ? own : remapping([own, JSON.parse(Buffer.from(incoming, 'base64').toString('utf8'))], () => null);
+    return `${code}\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(JSON.stringify(map)).toString('base64')}\n`;
+}

package/dist/engine/contract.d.ts

@@ -297,6 +297,7 @@ export type PointerAction = {
 } | {
     readonly kind: 'swipeTo';
     readonly target: ViewportPoint;
+    readonly durationMs?: number;
 };
 /** Every pointer action kind; what an engine declares in `pointerActions`. */
 export type PointerActionKind = PointerAction['kind'];

package/dist/engine/index.d.ts

@@ -147,8 +147,8 @@ export interface EngineFixtureContext {
         /**
          * Resolves a navigation target against the base URL. Throws
          * `APP_URL_REQUIRED` when the target declares no URL and `POLICY_DENIED`
-         * for a `file:`, `data:`, or `javascript:` scheme, so a fixture never
-         * re-implements the rule the harness owns.
+         * for any scheme but `http:` and `https:` (`about:blank` aside), so a
+         * fixture never re-implements the rule the harness owns.
          */
         resolveUrl(url: string): string;
     };
@@ -362,6 +362,8 @@ export interface EnginePrepareInfo {
      * fail every test behind it.
      */
     readonly signal: AbortSignal;
+    /** Whether the run asked for a visible surface (`--headed`), as `EngineInitInfo` declares it. */
+    readonly headed: boolean;
     /**
      * Reports one line of progress. The runner streams it as a `notice` run
      * event, so it reaches the reporter and every host sink instead of being

package/dist/engine/session.js

@@ -11,7 +11,7 @@
  * a non-retryable `ENGINE_FAILURE`, so a crashed engine is an infrastructure
  * failure everywhere and never a retry-eligible test failure.
  */
-import { asEngineError, ConfigurationError, E2EError, errorMessage, isForeignE2EError, TestError, } from '../internal/errors.js';
+import { asEngineError, ConfigurationError, errorMessage, isE2EError, TestError, } from '../internal/errors.js';
 import { requireKey } from '../internal/keys.js';
 import { EngineError, } from './surface.js';
 /** Located refs are pruned oldest-first past this bound so the map cannot grow unboundedly. */
@@ -45,7 +45,7 @@ function countSecure(node) {
  * engine failing outside its contract, reported as infrastructure.
  */
 function normalize(cause, label) {
-    if (cause instanceof E2EError || isForeignE2EError(cause) || asEngineError(cause) !== undefined) {
+    if (isE2EError(cause) || asEngineError(cause) !== undefined) {
         throw cause;
     }
     throw new EngineError('ENGINE_FAILURE', `${label} failed: ${errorMessage(cause)}`, {

package/dist/expect/async.js

@@ -106,7 +106,7 @@ class AsyncExpectationImpl {
                         return undefined;
                     return spec.predicate(sample);
                 },
-                onTimeout: () => {
+                onTimeout: (cause) => {
                     const expected = `${this.negated ? 'not ' : ''}${spec.describeExpected}`;
                     const observed = spec.observed(lastSample);
                     return new TestError('ASSERTION_FAILED', [
@@ -117,6 +117,7 @@ class AsyncExpectationImpl {
                     ].join('\n'), {
                         // The same facts, one per field, for a reporter that lays them out.
                         details: { locator: this.label, expected, observed, matches: lastSample.count },
+                        ...(cause === undefined ? {} : { cause }),
                     });
                 },
             });
@@ -144,7 +145,8 @@ class AsyncExpectationImpl {
             const refs = await engine.resolveAll(this.internals.expression, deadline);
             return { count: refs.length, node: null, nodes: [] };
         }
-        const { node, count } = await engine.tryRead(this.internals.expression, deadline);
+        const missingFrame = spec.evaluableWithoutNode === true ? 'empty' : 'wait';
+        const { node, count } = await engine.tryRead(this.internals.expression, deadline, missingFrame);
         return { count, node, nodes: [] };
     }
     /** A state matcher; its Playwright flag set to `false` expects the opposite state. */

package/dist/expect/poll-scope.d.ts

@@ -0,0 +1,52 @@
+/** Which phase of a test owns an `expect.poll`, so one left running fails that phase and nothing later. */
+import { TestError } from '../internal/errors.ts';
+/**
+ * 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 declare class PollScope {
+    private readonly owner;
+    private readonly running;
+    private closed;
+    /** `owner` completes "... returned before", as in `the test body`. */
+    constructor(owner: string);
+    /**
+     * 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<T>(label: string, stack: string | undefined, work: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    /**
+     * 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(): TestError | undefined;
+    private cancel;
+}
+/**
+ * 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 declare function runInPollScope<T>(scope: PollScope, run: () => T): T;
+/** One lineage of async work whose polls go to the scope current where it started, until `handOver`. */
+export interface PollLineage {
+    run<T>(run: () => T): T;
+    /** Sends the lineage's polls from now on to the scope current at this call. */
+    handOver(): void;
+}
+/**
+ * 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 declare function pollLineage(): PollLineage;
+/** The scope a poll started here belongs to, or undefined outside any phase (a standalone script). */
+export declare function currentPollScope(): PollScope | undefined;