@e2e-dev/web 0.15.5-nightly-20261104030231 → 0.15.5

package/dist/surface.js

@@ -8,7 +8,7 @@
  */
 import { mkdirSync } from 'node:fs';
 import path from 'node:path';
-import { EngineError, obj, raceAbort, TestError, withinCleanupBudget, } from 'e2e/engine';
+import { Deadline, EngineError, obj, raceAbort, TestError, withinCleanupBudget, } from 'e2e/engine';
 import { matchesText } from 'e2e/engine';
 import { classifyActionError, classifyInputError, dispatchLocatorAction, dispatchPointerAction } from './actions.js';
 import { BrowserConnection, connectCdp } from './browser-connection.js';
@@ -19,9 +19,10 @@ import { TraceFeed } from './trace-feed.js';
 import { DialogRouter } from './dialogs.js';
 import { browserCheck, ensureBrowsersInstalled } from './install.js';
 import { applyPostSteps, frameSelectors, projectExpression } from './locators.js';
-import { contentBox, frameContentInset, placeRectInFrame, ROOT_NODE_ID, toSemanticNode } from './observation.js';
+import { contentBox, frameContentInset, placeBoxInFrame, ROOT_NODE_ID, toSemanticNode } from './observation.js';
 import { captureObservation } from './observation-capture.js';
 import { maskOptions, secureFieldMasks } from './observe.js';
+import { SHOWN_SELECTOR } from './shown-selector.js';
 import { withHiddenCaret } from './screenshot-caret.js';
 import { connectionAbort, withOperationDeadline } from './operation-budget.js';
 import { CLOSED_SHADOW_ROOTS_INIT_SCRIPT, CLOSED_SHADOW_ROOTS_KEY } from './closed-shadow.js';
@@ -30,7 +31,7 @@ import { SECURE_FIELD_SELECTOR } from './read-node.js';
 import { readSelector, takeReadsFunction } from './read-selector.js';
 import { httpCredentials, installSiteHeaders, lowercaseNames, siteHeadersFor } from './protected-app.js';
 import { RefRegistry } from './refs.js';
-import { cancelled, DEFAULT_VIEWPORT, ErrorLatch, invalidState, message, navigationStaleOr, performViewportSwipe, sanitizeFilename, staleOr, translatePwError, } from './support.js';
+import { cancelled, DEFAULT_VIEWPORT, ErrorLatch, invalidState, isClassified, isPwTimeout, message, navigationStaleOr, performViewportSwipe, sanitizeFilename, pageScriptFailure, staleOr, translatePwError, } from './support.js';
 /** Browser launch budget when the harness init budget is not otherwise expressed. */
 const BROWSER_LAUNCH_TIMEOUT_MS = 60_000;
 const STATE_FORMAT = 'playwright-storage-state';
@@ -79,6 +80,8 @@ export class PlaywrightSurface {
     artifactsDir = '';
     /** Navigations the engine has in flight, which the app log leaves to the step that started them. */
     ownNavigations = 0;
+    /** One entry per navigation in flight, set to the URL of a document request a test route aborted during it. */
+    navigationAborts = new Set();
     /** What the attempt tells its trace beside the app log; absent between attempts. */
     trace;
     artifactCounter = 0;
@@ -131,7 +134,7 @@ export class PlaywrightSurface {
             return [...scripts, { id: 'browser', status: 'skip', message: `browsers come from the "${this.leases.name}" provider` }];
         if (this.connect !== undefined)
             return [...scripts, { id: 'browser', status: 'skip', message: 'the browser is attached over CDP' }];
-        return [...scripts, ...browserCheck(this.browserName, info.env, info.headed)];
+        return [...scripts, ...(await browserCheck(this.browserName, info.env, info.headed))];
     }
     /** Releases the browsers `prepare` leased; a local launch or a `connect` has nothing to release. */
     async finish(info) {
@@ -462,6 +465,9 @@ export class PlaywrightSurface {
                 : await this.session.run(operation, label, fn, bound);
         }
         catch (cause) {
+            // A handler error latched while the operation ran is its cause: a route
+            // that refused its own arguments aborts the request the step waited on.
+            this.latch.throwPending();
             throw translate(cause, label);
         }
     }
@@ -482,18 +488,44 @@ export class PlaywrightSurface {
     resize(size, operation) {
         return this.acted(operation, this.guard(operation, 'resize', () => this.setViewport(size)));
     }
-    /** Runs one navigation the engine itself makes, so the app log leaves it to the step that asked for it. */
+    /**
+     * Runs one navigation the engine itself makes, so the app log leaves it to
+     * the step that asked for it. A navigation that fails after a test route
+     * aborted its document request failed because the test aborted it: an
+     * action failure, not an engine fault.
+     */
     async navigating(work) {
         this.ownNavigations += 1;
+        const watch = {};
+        this.navigationAborts.add(watch);
         try {
             const result = await work();
             this.trace?.tellEnvironment();
             return result;
         }
+        catch (cause) {
+            if (watch.url === undefined || isClassified(cause) || isPwTimeout(cause))
+                throw cause;
+            throw new TestError('ACTION_FAILED', `navigation failed: a route aborted the request for ${watch.url}: ${message(cause)}`, { cause });
+        }
         finally {
+            this.navigationAborts.delete(watch);
             this.ownNavigations -= 1;
         }
     }
+    /**
+     * Records a request a test route is about to abort, when it loads the
+     * document of the attempt's page. Never throws: the abort must follow.
+     */
+    noteRouteAbort(request) {
+        if (this.navigationAborts.size === 0 || !request.isNavigationRequest())
+            return;
+        const main = this.openPage()?.mainFrame();
+        if (main === undefined || frameOf(request) !== main)
+            return;
+        for (const watch of this.navigationAborts)
+            watch.url ??= request.url();
+    }
     /** Resolves with what an action resolved with once the trace has the screen it left (`TraceFeed.screenAfterAction`); an action that failed leaves none. */
     async acted(operation, work) {
         const result = await work;
@@ -524,86 +556,104 @@ export class PlaywrightSurface {
      */
     locate(expression, operation) {
         return this.guard(operation, 'locate', async (currentOperation) => {
-            const session = this.requireSession();
-            const token = session.token();
-            const refs = session.refs;
-            const page = this.requirePage();
-            const frame = await this.frameBox(expression);
-            const projected = projectExpression(page, expression, this.testIdAttribute);
-            const { displayValue, name, steps } = projected;
-            // Every match is read by the `e2e-read` selector engine in the task that finds it, so a
-            // page that replaces it a frame later cannot detach it before the read. A
-            // predicate-filtered match is one element among many candidates (every input with a
-            // value, every control the label engine kept). Re-resolving it by position at action
-            // time would act on a neighbor whenever the page inserted or removed an element in
-            // between, so such matches are pinned to the handles of the elements the query returned,
-            // and their reads are taken back from those very handles: what was read and what is
-            // acted on are one set of elements by construction.
-            const read = readSelector({ testIdAttribute: this.testIdAttribute, secureFieldSelector: SECURE_FIELD_SELECTOR });
-            const reading = projected.locator.locator(read.selector);
-            const handles = displayValue !== null || name !== null
-                ? (await reading.elementHandles())
-                : null;
-            /** Disposes every handle this locate took, on the paths that hand none of them out. */
-            const releaseHandles = () => {
-                for (const handle of handles ?? [])
-                    void handle.dispose().catch(() => undefined);
-            };
-            const first = handles?.[0];
-            const taken = handles === null
-                ? await reading.evaluateAll(takeReadsFunction, { token: read.token })
-                : first === undefined
-                    ? []
-                    : await first.evaluate(takeReadsFunction, { token: read.token, elements: handles });
-            const reads = taken.filter((raw) => raw !== null);
-            if (reads.length !== taken.length) {
-                releaseHandles();
-                throw new TestError('INVALID_LOCATOR', 'a selector that captures with * (*css=article >> text=Hello) is not supported: use filter({ has }) instead');
-            }
-            const candidates = reads.flatMap((raw, index) => (projected.visible && raw.states.hidden ? [] : [{ raw, index }]));
-            // An exact label query matches any of the control's labels as the engine's reader names
-            // them, so text a label marks aria-hidden (a required-field marker) never hides a field,
-            // and an aria-label override or a second label does not either.
-            const predicate = displayValue !== null
-                ? (raw) => matchesText(raw.value ?? '', displayValue)
-                : name !== null
-                    ? (raw) => raw.labels !== null && raw.labels.some((label) => matchesText(label, name))
-                    : null;
-            const matches = predicate === null
-                ? candidates
-                : await applyPostSteps(candidates.filter(({ raw }) => predicate(raw)), steps, 
-                // A filter after a position runs on that one element alone.
-                async ({ index }, options) => (await projected.locator.nth(index).filter(options).count()) > 0);
-            if (currentOperation.signal.aborted) {
-                releaseHandles();
-                throw cancelled('locate cancelled');
-            }
             try {
-                session.check(token);
+                return await this.locateNow(expression, currentOperation);
             }
             catch (cause) {
-                releaseHandles();
-                throw cause;
-            }
-            if (handles !== null) {
-                // Only the matches keep their handles; the rest would otherwise live until the page goes.
-                const kept = new Set(matches.map(({ index }) => index));
-                for (const [index, handle] of handles.entries()) {
-                    if (!kept.has(index))
-                        void handle.dispose().catch(() => undefined);
-                }
+                throw (await pageScriptFailure(this.frameScope(expression), cause, 'locate', currentOperation.timeoutMs)) ?? cause;
             }
-            return matches.map(({ raw, index }) => {
-                const pinned = handles?.[index];
-                // A single match keeps the strict locator, so a ref that turns
-                // ambiguous between locate and perform is stale instead of acting
-                // on whichever element is first.
-                const locator = reads.length === 1 ? projected.locator : projected.locator.nth(index);
-                const id = refs.storeLocated(pinned === undefined ? { kind: 'locator', locator } : { kind: 'element', element: pinned });
-                return inFrame(toSemanticNode({ id, revision: '' }, raw), frame);
-            });
         }, staleOr);
     }
+    /** The body of `locate`, inside its guard. */
+    async locateNow(expression, currentOperation) {
+        const session = this.requireSession();
+        const token = session.token();
+        const refs = session.refs;
+        const page = this.requirePage();
+        const frame = await this.frameOf(expression);
+        const projected = projectExpression(page, expression, { testIdAttribute: this.testIdAttribute, frameHidden: frame.hidden });
+        const { displayValue, name, steps } = projected;
+        // Every match is read by the `e2e-read` selector engine in the task that finds it, so a
+        // page that replaces it a frame later cannot detach it before the read. A
+        // predicate-filtered match is one element among many candidates (every input with a
+        // value, every control the label engine kept). Re-resolving it by position at action
+        // time would act on a neighbor whenever the page inserted or removed an element in
+        // between, so such matches are pinned to the handles of the elements the query returned,
+        // and their reads are taken back from those very handles: what was read and what is
+        // acted on are one set of elements by construction.
+        const read = readSelector({ testIdAttribute: this.testIdAttribute, secureFieldSelector: SECURE_FIELD_SELECTOR });
+        const reading = projected.locator.locator(read.selector);
+        const handles = displayValue !== null || name !== null
+            ? (await reading.elementHandles())
+            : null;
+        /** Disposes every handle this locate took, on the paths that hand none of them out. */
+        const releaseHandles = () => {
+            for (const handle of handles ?? [])
+                void handle.dispose().catch(() => undefined);
+        };
+        const first = handles?.[0];
+        const taken = handles === null
+            ? await reading.evaluateAll(takeReadsFunction, { token: read.token })
+            : first === undefined
+                ? []
+                : await first.evaluate(takeReadsFunction, { token: read.token, elements: handles });
+        const reads = taken
+            .filter((raw) => raw !== null)
+            .map((raw) => (frame.hidden ? { ...raw, states: { ...raw.states, hidden: true } } : raw));
+        if (reads.length !== taken.length) {
+            releaseHandles();
+            throw new TestError('INVALID_LOCATOR', 'a selector that captures with * (*css=article >> text=Hello) is not supported: use filter({ has }) instead');
+        }
+        const candidates = reads.flatMap((raw, index) => (projected.visible && raw.states.hidden ? [] : [{ raw, index }]));
+        // An exact label query matches any of the control's labels as the engine's reader names
+        // them, so text a label marks aria-hidden (a required-field marker) never hides a field,
+        // and an aria-label override or a second label does not either.
+        const predicate = displayValue !== null
+            ? (raw) => matchesText(raw.value ?? '', displayValue)
+            : name !== null
+                ? (raw) => raw.labels !== null && raw.labels.some((label) => matchesText(label, name))
+                : null;
+        const matches = predicate === null
+            ? candidates
+            : await applyPostSteps(candidates.filter(({ raw }) => predicate(raw)), steps, 
+            // A filter after a position runs on that one element alone.
+            async ({ index }, options) => (await projected.locator.nth(index).filter(options).count()) > 0);
+        if (currentOperation.signal.aborted) {
+            releaseHandles();
+            throw cancelled('locate cancelled');
+        }
+        try {
+            session.check(token);
+        }
+        catch (cause) {
+            releaseHandles();
+            throw cause;
+        }
+        if (handles !== null) {
+            // Only the matches keep their handles; the rest would otherwise live until the page goes.
+            const kept = new Set(matches.map(({ index }) => index));
+            for (const [index, handle] of handles.entries()) {
+                if (!kept.has(index))
+                    void handle.dispose().catch(() => undefined);
+            }
+        }
+        return matches.map(({ raw, index }) => {
+            const pinned = handles?.[index];
+            // A single match keeps the strict locator, so a ref that turns
+            // ambiguous between locate and perform is stale instead of acting
+            // on whichever element is first.
+            const locator = reads.length === 1 ? projected.locator : projected.locator.nth(index);
+            const id = refs.storeLocated(pinned === undefined ? { kind: 'locator', locator } : { kind: 'element', element: pinned });
+            return inFrame(toSemanticNode({ id, revision: '' }, raw), frame.box);
+        });
+    }
+    /** The page or frame an expression's frame selectors lead to, unresolved. */
+    frameScope(expression) {
+        let scope = this.requirePage();
+        for (const selector of frameSelectors(expression))
+            scope = scope.frameLocator(selector);
+        return scope;
+    }
     /**
      * One action on a located or observed node. A `swipe` on the observation
      * root is the viewport swipe: a wheel gesture sized by the viewport, with no
@@ -617,7 +667,11 @@ export class PlaywrightSurface {
                 this.requireSession().requireObservation();
                 return performViewportSwipe(page, action.direction, action.momentum ?? 'none');
             }
-            return dispatchLocatorAction(this.requireSession().refs.lookup(ref), action, currentOperation, (other) => this.requireSession().refs.lookup(other));
+            const { refs } = this.requireSession();
+            return refs.lookup(ref).then((target) => {
+                currentOperation.signal.throwIfAborted();
+                return dispatchLocatorAction(target, action, currentOperation, (other) => refs.lookup(other));
+            });
         }, (cause) => classifyActionError(cause, action)));
     }
     /** One pointer action at a viewport point in CSS pixels, with nothing resolved behind it; see `dispatchPointerAction`. */
@@ -708,16 +762,22 @@ export class PlaywrightSurface {
      * the same chain; a frame-scoped `count` is 0 until that frame's document
      * has loaded, which is what makes `FRAME_NOT_FOUND` worth retrying. Returns
      * the innermost frame's content box in the top-level viewport, where its
-     * document's viewport starts: undefined for an expression in the main
-     * document, null for a frame with no box.
+     * document's viewport starts (undefined for an expression in the main
+     * document, null for a frame with no box), and
+     * whether a frame along the chain is hidden: a frame element's own `hidden`
+     * state, read in the document around it, so a cross-origin frame reads too.
+     * Every node in a hidden frame is hidden, and so are the frames under it.
      */
-    async frameBox(expression) {
+    async frameOf(expression) {
         let scope = this.requirePage();
         let element;
+        let hidden = false;
         for (const selector of frameSelectors(expression)) {
             let count;
             try {
                 count = await scope.locator(selector).count();
+                if (count === 1 && !hidden)
+                    hidden = (await scope.locator(selector).locator(SHOWN_SELECTOR).count()) === 0;
             }
             catch (cause) {
                 throw translatePwError(cause, 'frame resolution');
@@ -736,10 +796,10 @@ export class PlaywrightSurface {
             scope = scope.frameLocator(selector);
         }
         if (element === undefined)
-            return undefined;
+            return { box: undefined, hidden };
         try {
             const border = await element.boundingBox();
-            return border === null ? null : contentBox(border, await element.evaluate(frameContentInset));
+            return { box: border === null ? null : contentBox(border, await element.evaluate(frameContentInset)), hidden };
         }
         catch (cause) {
             throw translatePwError(cause, 'frame resolution');
@@ -761,15 +821,39 @@ export class PlaywrightSurface {
     /** Redacted at the source: secure fields in every frame are masked, and the caret is hidden without editing styles, as in observation pixels. */
     screenshot(label, operation) {
         return this.guard(operation, 'screenshot', async (currentOperation) => {
-            const page = this.requirePage();
             const { relative, absolute } = this.artifactPath('screenshots', label, '.png');
-            await withHiddenCaret(page, () => page.screenshot({
-                path: absolute,
-                timeout: currentOperation.timeoutMs,
-                caret: 'initial',
-                ...maskOptions(secureFieldMasks(page)),
-            }));
-            return relative;
+            const deadline = new Deadline(currentOperation.timeoutMs);
+            // The masks are resolved in the document showing when the capture
+            // starts. A capture that fails while the page replaces that document
+            // is taken of the replacing one, masked by the same rule, within the
+            // step's own deadline.
+            for (;;) {
+                const page = this.requirePage();
+                const documents = watchDocuments(page);
+                try {
+                    const masks = await secureFieldMasks(page);
+                    await withHiddenCaret(page, () => page.screenshot({
+                        path: absolute,
+                        timeout: Math.max(1, deadline.remaining()),
+                        caret: 'initial',
+                        ...maskOptions(masks),
+                    }));
+                    return relative;
+                }
+                catch (cause) {
+                    if (!documents.replaced() || isPwTimeout(cause) || currentOperation.signal.aborted)
+                        throw cause;
+                    if (deadline.expired()) {
+                        throw new EngineError('OPERATION_TIMEOUT', `screenshot timed out: the page replaced its document during every capture for ${currentOperation.timeoutMs}ms`, {
+                            retryable: false,
+                            cause,
+                        });
+                    }
+                }
+                finally {
+                    documents.stop();
+                }
+            }
         });
     }
     /** Starts the attempt's video. */
@@ -806,8 +890,9 @@ export class PlaywrightSurface {
     // --- observation ---
     /**
      * Captures one atomic semantic observation. Secure fields are masked in the
-     * page before the tree leaves the engine, and every node keeps a live
-     * element handle valid until the next observation replaces the generation.
+     * page before the tree leaves the engine, and every node stays reachable
+     * through its document's element list until the next observation replaces
+     * the generation; an action makes the node's handle on first use.
      *
      * With `options.pixels`, masked viewport pixels are captured alongside the
      * tree rather than after it, so the image and the node geometry describe the
@@ -819,9 +904,13 @@ export class PlaywrightSurface {
         // within the same deadline instead of failing the call.
         return this.guard(operation, 'observe', (currentOperation) => this.captureObservation(currentOperation, options), navigationStaleOr);
     }
-    /** Captures privately, then publishes only into the page and ref generation that requested it. */
-    async captureObservation(operation, options) {
+    /** Captures privately in the session's turn, then publishes only into the page and ref generation that requested it. */
+    captureObservation(operation, options) {
         const session = this.requireSession();
+        return session.observeInTurn(operation, (turn) => this.captureInTurn(session, turn, options));
+    }
+    /** One observation that holds the session's turn. */
+    async captureInTurn(session, operation, options) {
         const token = session.token();
         const refs = session.refs;
         const page = this.requirePage();
@@ -847,6 +936,31 @@ export class PlaywrightSurface {
         }
     }
 }
+/** Watches `page` until `stop` for a frame that commits a new document or detaches, either of which replaces a document a capture is reading. */
+function watchDocuments(page) {
+    let replaced = false;
+    const mark = () => {
+        replaced = true;
+    };
+    page.on('framenavigated', mark);
+    page.on('framedetached', mark);
+    return {
+        replaced: () => replaced,
+        stop: () => {
+            page.off('framenavigated', mark);
+            page.off('framedetached', mark);
+        },
+    };
+}
+/** The frame a request belongs to; undefined for a popup's first navigation, which Playwright issues before the popup's frame exists. */
+function frameOf(request) {
+    try {
+        return request.frame();
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * A located node in the top-level viewport's space, as the observation tree
  * reports it: its box shifted by the frame's and clipped to it, and dropped
@@ -855,7 +969,6 @@ export class PlaywrightSurface {
 function inFrame(node, frame) {
     if (frame === undefined || node.rect === undefined)
         return node;
-    const { rect, ...rest } = node;
-    const placed = frame === null ? undefined : placeRectInFrame(rect, frame);
-    return placed === undefined ? rest : { ...rest, rect: placed };
+    const { rect, origin, ...rest } = node;
+    return frame === null ? rest : { ...rest, ...placeBoxInFrame(rect, origin, frame) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e2e-dev/web",
-  "version": "0.15.5-nightly-20261104030231",
+  "version": "0.15.5",
   "description": "Web engine for e2e agentic end-to-end testing, built on Playwright",
   "keywords": [
     "e2e",
@@ -50,12 +50,12 @@
     "playwright-core": "1.64.1"
   },
   "peerDependencies": {
-    "e2e": "0.22.1-nightly-20261104030231"
+    "e2e": ">=0.22.1 <1"
   },
   "devDependencies": {
     "@types/node": "26.6.6",
     "@types/pngjs": "6.0.5",
-    "e2e": "0.22.1-nightly-20261104030231",
+    "e2e": "0.23.0",
     "pngjs": "7.0.0",
     "typescript": "7.0.2",
     "vitest": "5.1.0"