e2e 0.16.0 → 0.18.0

package/dist/internal/redact.js

@@ -63,24 +63,31 @@ function compile(values) {
     });
     // `split` on a capturing pattern returns the markers at the odd indexes; those pass through untouched.
     const redact = (text) => text.split(known).map((piece, index) => (index % 2 === 1 ? piece : rewrite(piece))).join('');
-    const valueKeys = entries.map(([, value]) => caseKey(value));
+    const valueKeys = entries.map(([, value]) => readingKey(value).key);
+    // A reader trims a value's leading whitespace as it trims any text's, so a cut part may begin past it.
+    const leadingForms = entries.map(([, value], index) => {
+        const key = valueKeys[index] ?? '';
+        return secretLength(value.trim()) >= MIN_SECRET_LENGTH && key.trimStart() !== key ? [key, key.trimStart()] : [key];
+    });
     const redactCut = (text) => {
         // Only what follows the last marker can end in a value cut short.
         const tail = text.split(known).at(-1) ?? '';
-        const tailKey = caseKey(tail);
+        const tailKey = readingKey(tail);
         let cut = 0;
         let marker = '';
-        valueKeys.forEach((value, index) => {
-            const length = leadingPartAtEnd(tailKey, value, Math.min(FRAGMENT_LENGTH, Math.ceil(value.length / 2)));
-            if (length > cut) {
-                cut = length;
-                marker = markers[index] ?? '';
+        leadingForms.forEach((forms, index) => {
+            for (const value of forms) {
+                const length = leadingPartAtEnd(tailKey.key, value, Math.min(FRAGMENT_LENGTH, Math.ceil(value.length / 2)));
+                if (length > cut) {
+                    cut = length;
+                    marker = markers[index] ?? '';
+                }
             }
         });
         if (cut === 0)
             return redact(text);
         // An occurrence the whole-value pass would rewrite across the fragment's start joins the fragment.
-        let start = tail.length - cut;
+        let start = tailKey.at(tailKey.key.length - cut);
         pattern.lastIndex = 0;
         for (let match = pattern.exec(tail); match !== null && match.index < start; match = pattern.exec(tail)) {
             if (match.index + match[0].length > start) {
@@ -221,6 +228,87 @@ function caseKey(text) {
         out += ch.charCodeAt(0) < 128 ? ch.toLowerCase() : caseKeyOf(ch);
     return out;
 }
+/** Whitespace a reader rewrites: a run of two or more, or one character other than a plain space. */
+const COLLAPSIBLE = /\s\s|[^\S ]/u;
+/** UTF-16 units joined into one string at a time when the key is rebuilt. */
+const KEY_CHUNK = 8192;
+/**
+ * `text` as a cut or a fragment of a value is compared: `caseKey`, with each
+ * whitespace run read as one space, as an engine that collapses whitespace
+ * (`normalizeText`) shows it before cutting. A value holding a line break, a
+ * tab, a CRLF, a no-break space, or a run of spaces then agrees with what a
+ * collapsed text keeps of it, and a stretch of the key maps back to the text
+ * through `at`. `caseKey` keeps every index, so text with nothing to collapse
+ * is its own key. Otherwise the key is rebuilt unit by unit into a typed
+ * array, and `at` keeps one pair of offsets per collapsed run: a trace text
+ * of many megabytes costs a few times its size, never an object per unit.
+ */
+function readingKey(text) {
+    const cased = caseKey(text);
+    if (!COLLAPSIBLE.test(cased))
+        return { key: cased, at: (index) => index };
+    const units = new Uint16Array(cased.length);
+    // Pairs of where a stretch after a collapsed run starts, in the key and in the text.
+    let breaks = new Int32Array(64);
+    let pairs = 0;
+    let length = 0;
+    for (let index = 0; index < cased.length; index += 1) {
+        const unit = cased.charCodeAt(index);
+        if (!isWhitespace(unit)) {
+            units[length++] = unit;
+            continue;
+        }
+        let end = index + 1;
+        while (end < cased.length && isWhitespace(cased.charCodeAt(end)))
+            end += 1;
+        units[length++] = 0x20;
+        if (end - index > 1 || unit !== 0x20) {
+            if (2 * pairs + 2 > breaks.length) {
+                const grown = new Int32Array(breaks.length * 2);
+                grown.set(breaks);
+                breaks = grown;
+            }
+            breaks[2 * pairs] = length;
+            breaks[2 * pairs + 1] = end;
+            pairs += 1;
+        }
+        index = end - 1;
+    }
+    const chunks = [];
+    for (let start = 0; start < length; start += KEY_CHUNK) {
+        chunks.push(String.fromCharCode(...units.subarray(start, Math.min(length, start + KEY_CHUNK))));
+    }
+    return {
+        key: chunks.join(''),
+        at: (index) => {
+            // The last stretch starting at or before `index`; before the first run the key and the text agree.
+            let low = -1;
+            let high = pairs - 1;
+            while (low < high) {
+                const middle = (low + high + 1) >> 1;
+                if ((breaks[2 * middle] ?? 0) <= index)
+                    low = middle;
+                else
+                    high = middle - 1;
+            }
+            return low === -1 ? index : (breaks[2 * low + 1] ?? 0) + index - (breaks[2 * low] ?? 0);
+        },
+    };
+}
+/** Whether a UTF-16 unit is one `\s` matches: what `normalizeText` collapses. */
+function isWhitespace(unit) {
+    return (unit === 0x20 ||
+        (unit >= 0x09 && unit <= 0x0d) ||
+        unit === 0xa0 ||
+        unit === 0x1680 ||
+        (unit >= 0x2000 && unit <= 0x200a) ||
+        unit === 0x2028 ||
+        unit === 0x2029 ||
+        unit === 0x202f ||
+        unit === 0x205f ||
+        unit === 0x3000 ||
+        unit === 0xfeff);
+}
 /** One non-ASCII character's `caseKey`, the same length as `ch`. */
 function caseKeyOf(ch) {
     const upper = sameLength(ch.toUpperCase(), ch);
@@ -306,8 +394,9 @@ function leadingPartAtEnd(text, value, minimum) {
 /**
  * Every run of `FRAGMENT_LENGTH` characters of every value, mapped to the
  * index of the first value holding it; values come longest first, so a run
- * two values share names the longer one. The values come as `caseKey`
- * reads them, so a run in any case finds its owner.
+ * two values share names the longer one. The values come as `readingKey`
+ * reads them, so a run in any case or with its whitespace collapsed finds
+ * its owner.
  */
 function fragmentOwners(values) {
     const owners = new Map();
@@ -323,29 +412,30 @@ function fragmentOwners(values) {
 /**
  * `text` with every stretch whose windows of `FRAGMENT_LENGTH` characters
  * each occur in a value replaced by the marker of the value owning its first
- * window. Windows are looked up by `caseKey`, as `owners` is keyed, so a
- * fragment in another case is one too. The stretch grows one window at a time, so the
- * scan is linear in the text and a run spanning two values becomes one
- * marker.
+ * window. Windows are looked up by `readingKey`, as `owners` is keyed, so a
+ * fragment in another case or with another whitespace run is one too, and
+ * the stretch is cut back out of `text` whole, its whitespace runs included.
+ * The stretch grows one window at a time, so the scan is linear in the text
+ * and a run spanning two values becomes one marker.
  */
 function rewriteFragments(text, owners, markers) {
     if (owners.size === 0)
         return text;
-    const key = caseKey(text);
+    const { key, at } = readingKey(text);
     let out = '';
     let kept = 0;
     let start = 0;
-    while (start + FRAGMENT_LENGTH <= text.length) {
+    while (start + FRAGMENT_LENGTH <= key.length) {
         const owner = owners.get(key.slice(start, start + FRAGMENT_LENGTH));
         if (owner === undefined) {
             start += 1;
             continue;
         }
         let end = start + FRAGMENT_LENGTH;
-        while (end < text.length && owners.has(key.slice(end + 1 - FRAGMENT_LENGTH, end + 1)))
+        while (end < key.length && owners.has(key.slice(end + 1 - FRAGMENT_LENGTH, end + 1)))
             end += 1;
-        out += `${text.slice(kept, start)}${markers[owner] ?? ''}`;
-        kept = end;
+        out += `${text.slice(kept, at(start))}${markers[owner] ?? ''}`;
+        kept = at(end);
         start = end;
     }
     return out + text.slice(kept);
@@ -437,6 +527,10 @@ export class SecretLedger {
     }
     /** Bound so it can be handed out as a plain function. */
     redact = (text) => this.compile().redact(text);
+    /** Whether no value is registered, so there is nothing to redact. */
+    get isEmpty() {
+        return this.values.length === 0;
+    }
     /** Every registered name and value, in registration order. */
     entries() {
         return this.values.map(([name, value]) => [name, value]);
@@ -449,9 +543,12 @@ export 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`.
@@ -463,7 +560,7 @@ export 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`.

package/dist/internal/time.d.ts

@@ -12,6 +12,15 @@ export declare class Deadline {
 export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
 /** Canonical polling cadence for locator and assertion loops. */
 export declare const POLL_INTERVAL_MS = 100;
+/**
+ * Whether `cause` is a read a wait's deadline cut off: an operation timeout
+ * of a read that started with less than one poll tick of the wait left, so
+ * it timed out because the wait did, not because the app stopped answering.
+ * A read that started with more and still timed out hung, and its timeout is
+ * the failure. Reads the engine error a locator failure wraps as well as a
+ * bare one.
+ */
+export declare function cutOffAtDeadline(cause: unknown, startedWithMs: number): boolean;
 /** How long a negated assertion must hold before it passes. */
 export declare const NEGATION_GRACE_MS = 1000;
 export interface PollConditionOptions {
@@ -19,17 +28,30 @@ export interface PollConditionOptions {
     readonly signal: AbortSignal;
     readonly negated: boolean;
     /**
-     * Evaluates the positive condition once. Returns undefined when the
-     * condition cannot be evaluated yet: the positive poll keeps waiting and
-     * the negation grace window resets.
+     * Evaluates the positive condition once, every read bounded by
+     * `deadline`: a read on a longer budget outlasts the poll. Returns
+     * undefined when the condition cannot be evaluated yet: the positive poll
+     * keeps waiting and the negation grace window resets.
      */
     evaluate(): Promise<boolean | undefined>;
-    onTimeout(): Error | Promise<Error>;
+    /** Builds the poll's failure; `cause` is the read the deadline cut off, when one did. */
+    onTimeout(cause?: unknown): Error | Promise<Error>;
 }
 /**
  * Polls a condition until it holds (or, when negated, until its negation has
  * held continuously for the negation grace window), throwing the caller's
  * error at the deadline.
+ *
+ * A negation holds from the moment the read that first saw it was issued, so
+ * a slow read counts toward the window. A budget shorter than the window
+ * still has to be satisfiable: the negation then only needs to hold for the
+ * whole budget, and passes at the deadline on what it has seen, since a read
+ * past the deadline has no budget left. A read the deadline cut off (see
+ * `cutOffAtDeadline`) after an earlier one completed saw nothing: the poll
+ * ends there. A negation then passes if it has held long enough by the
+ * time the read is cut off: the read left less than one poll tick unseen, no
+ * more than the gap between any two reads, so a short budget still passes at
+ * its deadline on what it saw.
  */
 export declare function pollCondition(options: PollConditionOptions): Promise<void>;
 /** Races a promise against a timeout; on timeout invokes onTimeout to build the error. */

package/dist/internal/time.js

@@ -1,5 +1,5 @@
 /** Deadline and cancellation helpers. */
-import { E2EError } from './errors.js';
+import { asEngineError, E2EError } from './errors.js';
 export class Deadline {
     endsAt;
     constructor(timeoutMs, now = Date.now()) {
@@ -41,35 +41,79 @@ export function sleep(ms, signal) {
 }
 /** Canonical polling cadence for locator and assertion loops. */
 export const POLL_INTERVAL_MS = 100;
+/**
+ * Whether `cause` is a read a wait's deadline cut off: an operation timeout
+ * of a read that started with less than one poll tick of the wait left, so
+ * it timed out because the wait did, not because the app stopped answering.
+ * A read that started with more and still timed out hung, and its timeout is
+ * the failure. Reads the engine error a locator failure wraps as well as a
+ * bare one.
+ */
+export function cutOffAtDeadline(cause, startedWithMs) {
+    if (startedWithMs >= POLL_INTERVAL_MS)
+        return false;
+    const engineError = asEngineError(cause) ?? asEngineError(cause instanceof Error ? cause.cause : undefined);
+    return engineError?.code === 'OPERATION_TIMEOUT';
+}
 /** How long a negated assertion must hold before it passes. */
 export const NEGATION_GRACE_MS = 1000;
 /**
  * Polls a condition until it holds (or, when negated, until its negation has
  * held continuously for the negation grace window), throwing the caller's
  * error at the deadline.
+ *
+ * A negation holds from the moment the read that first saw it was issued, so
+ * a slow read counts toward the window. A budget shorter than the window
+ * still has to be satisfiable: the negation then only needs to hold for the
+ * whole budget, and passes at the deadline on what it has seen, since a read
+ * past the deadline has no budget left. A read the deadline cut off (see
+ * `cutOffAtDeadline`) after an earlier one completed saw nothing: the poll
+ * ends there. A negation then passes if it has held long enough by the
+ * time the read is cut off: the read left less than one poll tick unseen, no
+ * more than the gap between any two reads, so a short budget still passes at
+ * its deadline on what it saw.
  */
 export async function pollCondition(options) {
-    // A budget shorter than the grace window still has to be satisfiable: the
-    // negation then only needs to hold for the budget itself.
-    const grace = Math.min(NEGATION_GRACE_MS, Math.max(0, options.deadline.remaining()));
-    let negatedTrueSince;
+    const { deadline, negated } = options;
+    const startedAt = Date.now();
+    const grace = Math.min(NEGATION_GRACE_MS, deadline.remaining(startedAt));
+    let readAt = startedAt;
+    let holdingSince;
+    const holds = (now) => holdingSince !== undefined && now - holdingSince >= grace;
+    let sampled = false;
     for (;;) {
-        const value = await options.evaluate();
-        if (!options.negated) {
-            if (value === true)
+        const startedWithMs = deadline.remaining(readAt);
+        let value;
+        try {
+            value = await options.evaluate();
+            sampled = true;
+        }
+        catch (cause) {
+            if (!sampled || !cutOffAtDeadline(cause, startedWithMs))
+                throw cause;
+            if (negated && holds(Math.min(Date.now(), deadline.endsAt)))
                 return;
+            throw await options.onTimeout(cause);
         }
-        else if (value === false) {
-            negatedTrueSince ??= Date.now();
-            if (Date.now() - negatedTrueSince >= grace)
+        if (!negated) {
+            if (value === true)
                 return;
         }
         else {
-            negatedTrueSince = undefined;
+            holdingSince = value === false ? (holdingSince ?? readAt) : undefined;
         }
-        if (options.deadline.expired())
+        const now = Date.now();
+        if (holds(now))
+            return;
+        if (deadline.expired(now))
             throw await options.onTimeout();
-        await sleep(POLL_INTERVAL_MS, options.signal);
+        await sleep(negated ? Math.min(POLL_INTERVAL_MS, deadline.remaining(now)) : POLL_INTERVAL_MS, options.signal);
+        readAt = Date.now();
+        if (negated && deadline.expired(readAt)) {
+            if (holds(readAt))
+                return;
+            throw await options.onTimeout();
+        }
     }
 }
 /** Races a promise against a timeout; on timeout invokes onTimeout to build the error. */

package/dist/internal/urls.d.ts

@@ -23,10 +23,12 @@ export declare function isLoopbackHost(hostname: string): boolean;
 /** True when environment may default to `test` (loopback, .localhost, .test hosts). */
 export declare function isImplicitTestHost(hostname: string): boolean;
 /**
- * Resolves a navigation URL against the base and refuses the schemes no test
- * may open. Returns the absolute URL string. Any http(s) origin is admitted:
- * a click can reach one just as well, so a gate on typed navigation alone
- * would guard nothing.
+ * Resolves a navigation URL against the base and refuses every scheme but
+ * http(s), except the exact `about:blank`. Returns the absolute URL string.
+ * Any http(s) origin is admitted: a click can reach one just as well, so a
+ * gate on typed navigation alone would guard nothing. The rule is an
+ * allowlist because a browser wraps and nests schemes (`view-source:file:`,
+ * `blob:`, `filesystem:`), and a list of forbidden ones misses the wrapper.
  */
 export declare function resolveNavigationUrl(input: string, base: NormalizedBaseUrl | undefined): {
     url: string;
@@ -53,5 +55,7 @@ export declare function sameSite(url: string | URL, site: string): boolean;
  * Relative expected strings resolve against the base URL; string comparison is
  * exact after WHATWG serialization; regexps test the complete serialized URL.
  * Anything else is `INVALID_ARGUMENT`, the `toTextPattern` rule.
+ * `ignoreCase` is Playwright's: `true` compares a string case-insensitively
+ * and adds the `i` flag to a regexp, `false` removes it.
  */
-export declare function urlMatches(current: string, expected: string | RegExp, baseHref: string): boolean;
+export declare function urlMatches(current: string, expected: string | RegExp, baseHref: string, ignoreCase?: boolean): boolean;

package/dist/internal/urls.js

@@ -1,7 +1,7 @@
 /** URL normalization and origin policy helpers. */
 import { ConfigurationError } from './errors.js';
 import { testPattern } from './regexp.js';
-import { toTextPattern } from './text.js';
+import { toTextPattern, withIgnoreCase } from './text.js';
 /**
  * Parses and normalizes the app base URL. Rejects userinfo, query, and
  * fragment. WHATWG parsing handles IDNA ASCII hosts, dot segments, and
@@ -94,12 +94,16 @@ export function isLoopbackHost(hostname) {
 export function isImplicitTestHost(hostname) {
     return isLoopbackHost(hostname) || hostname.endsWith('.test');
 }
-const FORBIDDEN_PROTOCOLS = new Set(['file:', 'data:', 'javascript:']);
+const NAVIGABLE_PROTOCOLS = new Set(['http:', 'https:']);
+/** The one non-http(s) page navigation opens: empty, with no local or inline content. */
+const BLANK_PAGE = 'about:blank';
 /**
- * Resolves a navigation URL against the base and refuses the schemes no test
- * may open. Returns the absolute URL string. Any http(s) origin is admitted:
- * a click can reach one just as well, so a gate on typed navigation alone
- * would guard nothing.
+ * Resolves a navigation URL against the base and refuses every scheme but
+ * http(s), except the exact `about:blank`. Returns the absolute URL string.
+ * Any http(s) origin is admitted: a click can reach one just as well, so a
+ * gate on typed navigation alone would guard nothing. The rule is an
+ * allowlist because a browser wraps and nests schemes (`view-source:file:`,
+ * `blob:`, `filesystem:`), and a list of forbidden ones misses the wrapper.
  */
 export function resolveNavigationUrl(input, base) {
     let url;
@@ -114,7 +118,7 @@ export function resolveNavigationUrl(input, base) {
         }
         throw new ConfigurationError('POLICY_DENIED', `malformed URL: ${input}`);
     }
-    if (FORBIDDEN_PROTOCOLS.has(url.protocol)) {
+    if (!NAVIGABLE_PROTOCOLS.has(url.protocol) && url.href !== BLANK_PAGE) {
         throw new ConfigurationError('POLICY_DENIED', `forbidden URL scheme: ${url.protocol}`);
     }
     return { url: url.href };
@@ -160,9 +164,11 @@ export function sameSite(url, site) {
  * Relative expected strings resolve against the base URL; string comparison is
  * exact after WHATWG serialization; regexps test the complete serialized URL.
  * Anything else is `INVALID_ARGUMENT`, the `toTextPattern` rule.
+ * `ignoreCase` is Playwright's: `true` compares a string case-insensitively
+ * and adds the `i` flag to a regexp, `false` removes it.
  */
-export function urlMatches(current, expected, baseHref) {
-    const pattern = toTextPattern(expected);
+export function urlMatches(current, expected, baseHref, ignoreCase) {
+    const pattern = withIgnoreCase(toTextPattern(expected), ignoreCase);
     if (pattern.kind === 'regexp') {
         return testPattern(pattern.source, pattern.flags, serializeForComparison(current));
     }
@@ -173,7 +179,10 @@ export function urlMatches(current, expected, baseHref) {
     catch {
         return false;
     }
-    return serializeForComparison(current) === expectedUrl.href;
+    const actual = serializeForComparison(current);
+    return ignoreCase === true
+        ? actual.toLowerCase() === expectedUrl.href.toLowerCase()
+        : actual === expectedUrl.href;
 }
 function serializeForComparison(url) {
     try {

package/dist/locator/engine.d.ts

@@ -18,6 +18,11 @@ export declare function attributeOf(node: SemanticNode, name: string): string |
  * empty or absent.
  */
 export declare function denySecureRead(nodes: readonly SemanticNode[], label: string): void;
+/**
+ * What a frame the engine reports missing means to a resolve: `wait` treats
+ * it like a node that is not there yet, `empty` answers zero matches.
+ */
+type MissingFrame = 'wait' | 'empty';
 interface LocatorEngineOptions {
     readonly session: TargetSession;
     /** The running phase's signal and deadline, read per operation. */
@@ -95,8 +100,13 @@ export declare class LocatorEngine {
     /** Reads every current match at once, for `allTextContents`: a missing frame reads as no matches. */
     readAllNow(expression: LocatorExpression): Promise<readonly SemanticNode[]>;
     private readEvery;
-    /** Reads one node for polling surfaces; returns null while zero matches. */
-    tryRead(expression: LocatorExpression, deadline: Deadline): Promise<{
+    /**
+     * Reads one node for polling surfaces; returns null while zero matches.
+     * A poll that waits for absence passes `missingFrame: 'empty'`: nothing
+     * under a frame that is not in the document is attached, so the sample is
+     * zero matches rather than a wait for the frame.
+     */
+    tryRead(expression: LocatorExpression, deadline: Deadline, missingFrame?: MissingFrame): Promise<{
         node: SemanticNode | null;
         count: number;
     }>;

package/dist/locator/engine.js

@@ -3,7 +3,7 @@ import {} from '../engine/surface.js';
 import { asEngineError, ConfigurationError, E2EError, TestError, translateEngineError, } from '../internal/errors.js';
 import { requireKey } from '../internal/keys.js';
 import { describeExpression, expressionHints } from './expression.js';
-import { Deadline, POLL_INTERVAL_MS, sleep } from '../internal/time.js';
+import { cutOffAtDeadline, Deadline, POLL_INTERVAL_MS, sleep } from '../internal/time.js';
 /** Canonical visibility predicate over a semantic node snapshot. */
 export function isNodeVisible(node) {
     return node !== null && node.states?.hidden !== true;
@@ -96,16 +96,22 @@ export class LocatorEngine {
      * matches, and a read that promised not to wait must not wait for it.
      */
     async resolveOnce(expression, deadline, missingFrame = 'wait') {
+        let retried;
         for (;;) {
+            const startedWithMs = deadline.remaining();
             try {
                 return await this.session.locate(expression, this.operationWithin(deadline));
             }
             catch (cause) {
+                // A retry the deadline cut off saw nothing new: the wait ends on the failure it was retrying.
+                if (retried !== undefined && cutOffAtDeadline(cause, startedWithMs))
+                    throw translateLocatorError(retried, expression);
                 const engineError = asEngineError(cause);
                 if (engineError?.retryable === true) {
                     if (missingFrame === 'empty' && engineError.code === 'FRAME_NOT_FOUND')
                         return [];
                     if (!deadline.expired()) {
+                        retried = cause;
                         await sleep(POLL_INTERVAL_MS, this.signal);
                         continue;
                     }
@@ -120,15 +126,31 @@ export class LocatorEngine {
      */
     async resolveExactlyOne(expression, deadline) {
         const startedMs = Date.now();
+        // The wait as it happened: a deadline capped by the test's remaining
+        // budget waited less than the action timeout, and the report says so.
+        const notFound = (cause) => new TestError('LOCATOR_NOT_FOUND', `locator matched no nodes within ${describeExpression(expression)}`, {
+            details: locatorDetails(expression, Date.now() - startedMs),
+            ...(cause === undefined ? {} : { cause }),
+        });
+        let sampled = false;
         for (;;) {
-            const ref = assertSingle(await this.resolveOnce(expression, deadline), expression);
+            const startedWithMs = deadline.remaining();
+            let refs;
+            try {
+                refs = await this.resolveOnce(expression, deadline);
+            }
+            catch (cause) {
+                // A resolve the deadline cut off, after one that matched nothing, is the wait running out.
+                if (sampled && cutOffAtDeadline(cause, startedWithMs))
+                    throw notFound(cause);
+                throw cause;
+            }
+            sampled = true;
+            const ref = assertSingle(refs, expression);
             if (ref !== null)
                 return ref;
-            if (deadline.expired()) {
-                // The wait as it happened: a deadline capped by the test's remaining
-                // budget waited less than the action timeout, and the report says so.
-                throw new TestError('LOCATOR_NOT_FOUND', `locator matched no nodes within ${describeExpression(expression)}`, { details: locatorDetails(expression, Date.now() - startedMs) });
-            }
+            if (deadline.expired())
+                throw notFound();
             await sleep(POLL_INTERVAL_MS, this.signal);
         }
     }
@@ -213,9 +235,14 @@ export class LocatorEngine {
             }
         }
     }
-    /** Reads one node for polling surfaces; returns null while zero matches. */
-    async tryRead(expression, deadline) {
-        return this.readOne(expression, deadline, 'wait');
+    /**
+     * Reads one node for polling surfaces; returns null while zero matches.
+     * A poll that waits for absence passes `missingFrame: 'empty'`: nothing
+     * under a frame that is not in the document is attached, so the sample is
+     * zero matches rather than a wait for the frame.
+     */
+    async tryRead(expression, deadline, missingFrame = 'wait') {
+        return this.readOne(expression, deadline, missingFrame);
     }
     /**
      * Reads the one current match at once, for `isVisible` and `isHidden`:
@@ -270,16 +297,30 @@ export class LocatorEngine {
         if (this.session.actions.has('scrollIntoView')) {
             await this.performUntil(expression, { kind: 'scrollIntoView' }, deadline);
         }
+        const notVisible = (cause) => new TestError('LOCATOR_NOT_FOUND', `locator did not become visible with a box to act within: ${describeExpression(expression)}`, {
+            details: locatorDetails(expression, Date.now() - startedMs),
+            ...(cause === undefined ? {} : { cause }),
+        });
+        let sampled = false;
         for (;;) {
-            const { node } = await this.tryRead(expression, deadline);
+            const startedWithMs = deadline.remaining();
+            let node;
+            try {
+                ({ node } = await this.tryRead(expression, deadline));
+            }
+            catch (cause) {
+                if (sampled && cutOffAtDeadline(cause, startedWithMs))
+                    throw notVisible(cause);
+                throw cause;
+            }
+            sampled = true;
             const rect = isNodeVisible(node) ? node.rect : undefined;
             if (rect !== undefined) {
                 await this.dispatchAt({ x: rect.x + offset.x, y: rect.y + offset.y }, action, deadline);
                 return;
             }
-            if (deadline.expired()) {
-                throw new TestError('LOCATOR_NOT_FOUND', `locator did not become visible with a box to act within: ${describeExpression(expression)}`, { details: locatorDetails(expression, Date.now() - startedMs) });
-            }
+            if (deadline.expired())
+                throw notVisible();
             await sleep(POLL_INTERVAL_MS, this.signal);
         }
     }