@e2e-dev/web 0.13.0 → 0.14.0-nightly-20261008205824

package/dist/surface.js

@@ -14,14 +14,16 @@ import { classifyActionError, classifyInputError, dispatchLocatorAction, dispatc
 import { BrowserConnection, connectCdp } from './browser-connection.js';
 import { AttemptSession } from './attempt-session.js';
 import { LeasedBrowsers } from './provider.js';
+import { installAppLog } from './app-log.js';
+import { TraceFeed } from './trace-feed.js';
 import { DialogRouter } from './dialogs.js';
 import { ensureBrowsersInstalled } from './install.js';
 import { applyPostSteps, frameSelectors, projectExpression } from './locators.js';
-import { ROOT_NODE_ID, toSemanticNode } from './observation.js';
+import { contentBox, frameContentInset, placeRectInFrame, ROOT_NODE_ID, toSemanticNode } from './observation.js';
 import { captureObservation } from './observation-capture.js';
 import { maskOptions, secureFieldMasks } from './observe.js';
 import { connectionAbort, withOperationDeadline } from './operation-budget.js';
-import { CLOSED_SHADOW_ROOTS_INIT_SCRIPT } from './closed-shadow.js';
+import { CLOSED_SHADOW_ROOTS_INIT_SCRIPT, CLOSED_SHADOW_ROOTS_KEY } from './closed-shadow.js';
 import { ConfiguredInitScripts } from './init-scripts.js';
 import { SECURE_FIELD_SELECTOR } from './read-node.js';
 import { readSelector, takeReadsFunction } from './read-selector.js';
@@ -72,6 +74,10 @@ export class PlaywrightSurface {
     projectRoot = '';
     headed = false;
     artifactsDir = '';
+    /** Navigations the engine has in flight, which the app log leaves to the step that started them. */
+    ownNavigations = 0;
+    /** What the attempt tells its trace beside the app log; absent between attempts. */
+    trace;
     artifactCounter = 0;
     /**
      * Attempt-scoped network routes. Registered on the
@@ -235,6 +241,7 @@ export class PlaywrightSurface {
         const persistent = await this.persistentBinding(context);
         this.artifactsDir = context.artifactsDir;
         this.artifactCounter = 0;
+        this.trace = new TraceFeed(context, () => this.openPage(), () => this.session?.refs, { testIdAttribute: this.testIdAttribute, site: this.app.site });
         const routes = [];
         const initScripts = this.configuredInitScripts.forAttempt();
         this.latch = new ErrorLatch();
@@ -262,6 +269,11 @@ export class PlaywrightSurface {
                     await target.addInitScript(script);
                 target.setDefaultTimeout(CONTEXT_DEFAULT_TIMEOUT_MS);
                 target.on('dialog', (dialog) => { void dialogs.dispatch(dialog); });
+                installAppLog(target, context.appLog, {
+                    navigated: context.navigation,
+                    ownNavigation: () => this.ownNavigations > 0,
+                    testPage: () => this.openPage(),
+                });
                 await installSiteHeaders(target, this.app.site, this.headers);
                 for (const stored of routes)
                     await target.route(stored.predicate, stored.handler);
@@ -301,8 +313,8 @@ export class PlaywrightSurface {
      * Releases attempt resources, the worker's shared browser process, and a
      * lease the worker acquired for itself: three independent tasks, in that
      * order, every one attempted whatever the earlier ones did, and the first
-     * failure reported once all ran. A billed browser outlives a failed trace
-     * flush otherwise.
+     * failure reported once all ran. A billed browser outlives a failed
+     * recording flush otherwise.
      */
     async dispose(context) {
         const tasks = [
@@ -358,6 +370,20 @@ export class PlaywrightSurface {
         await context.unroute(predicate, handler);
     }
     // --- page access shared with the browser fixture ---
+    /**
+     * The attempt's open page, or undefined, for a reader beside the test (the
+     * trace): unlike `requirePage`, it leaves an error a handler latched for
+     * the test's next operation to throw.
+     */
+    openPage() {
+        try {
+            const page = this.session?.current().page ?? null;
+            return page === null || page.isClosed() ? undefined : page;
+        }
+        catch {
+            return undefined;
+        }
+    }
     requirePage() {
         this.latch.throwPending();
         const page = this.requireSession().current().page;
@@ -415,15 +441,33 @@ export class PlaywrightSurface {
     // --- steering: the session hooks ---
     /** Opens one URL the harness resolved; the attempt's page is created on first use. */
     open(url, operation) {
-        return this.guard(operation, 'navigation', async (currentOperation) => {
+        return this.acted(operation, this.guard(operation, 'navigation', (currentOperation) => this.navigating(async () => {
             const page = await this.ensurePage();
             await page.goto(url, { waitUntil: 'load', timeout: currentOperation.timeoutMs });
-        });
+        })));
     }
     back(operation) {
-        return this.guard(operation, 'navigation', async (currentOperation) => {
+        return this.acted(operation, this.guard(operation, 'navigation', (currentOperation) => this.navigating(async () => {
             await this.requirePage().goBack({ waitUntil: 'load', timeout: currentOperation.timeoutMs });
-        });
+        })));
+    }
+    /** Runs one navigation the engine itself makes, so the app log leaves it to the step that asked for it. */
+    async navigating(work) {
+        this.ownNavigations += 1;
+        try {
+            const result = await work();
+            this.trace?.tellEnvironment();
+            return result;
+        }
+        finally {
+            this.ownNavigations -= 1;
+        }
+    }
+    /** 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;
+        await this.trace?.screenAfterAction(operation);
+        return result;
     }
     /** Restarts the document while retaining this attempt's context and storage. */
     restart(operation) {
@@ -453,7 +497,7 @@ export class PlaywrightSurface {
             const token = session.token();
             const refs = session.refs;
             const page = this.requirePage();
-            await this.validateFrames(expression);
+            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
@@ -525,7 +569,7 @@ export class PlaywrightSurface {
                 // 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 toSemanticNode({ id, revision: '' }, raw);
+                return inFrame(toSemanticNode({ id, revision: '' }, raw), frame);
             });
         }, staleOr);
     }
@@ -536,21 +580,21 @@ export class PlaywrightSurface {
      * on the root acts on the document element the root stands for.
      */
     perform(ref, action, operation) {
-        return this.guard(operation, action.kind, (currentOperation) => {
+        return this.acted(operation, this.guard(operation, action.kind, (currentOperation) => {
             const page = this.requirePage();
             if (action.kind === 'swipe' && ref.id === ROOT_NODE_ID) {
                 this.requireSession().requireObservation();
                 return performViewportSwipe(page, action.direction, action.momentum ?? 'none');
             }
-            return dispatchLocatorAction(this.requireSession().refs.lookup(ref), action, currentOperation.timeoutMs, (other) => this.requireSession().refs.lookup(other));
-        }, (cause) => classifyActionError(cause, action));
+            return dispatchLocatorAction(this.requireSession().refs.lookup(ref), action, currentOperation, (other) => this.requireSession().refs.lookup(other));
+        }, (cause) => classifyActionError(cause, action)));
     }
     /** One pointer action at a viewport point in CSS pixels, with nothing resolved behind it; see `dispatchPointerAction`. */
     performAt(point, action, operation) {
-        return this.guard(operation, `${action.kind} at point`, (currentOperation) => {
+        return this.acted(operation, this.guard(operation, `${action.kind} at point`, (currentOperation) => {
             this.requireSession().requireObservation();
             return dispatchPointerAction(this.requirePage(), point, action, currentOperation.signal);
-        }, classifyInputError);
+        }, classifyInputError));
     }
     /**
      * Types into whatever holds focus. Keystrokes into a document body are
@@ -560,7 +604,7 @@ export class PlaywrightSurface {
      * scoped by the browser to the whole editing host, so it is opt-in.
      */
     typeText(text, options, operation) {
-        return this.guard(operation, 'keyboard.type', async (currentOperation) => {
+        return this.acted(operation, this.guard(operation, 'keyboard.type', async (currentOperation) => {
             const session = this.requireSession();
             session.requireObservation();
             const token = session.token();
@@ -580,14 +624,14 @@ export class PlaywrightSurface {
                 checkpoint();
             }
             await page.keyboard.type(text);
-        }, classifyInputError);
+        }, classifyInputError));
     }
     /** Sends one key to whatever holds focus, in the contract's key grammar Playwright shares. */
     pressKey(key, operation) {
-        return this.guard(operation, 'keyboard.press', () => {
+        return this.acted(operation, this.guard(operation, 'keyboard.press', () => {
             this.requireSession().requireObservation();
             return this.requirePage().keyboard.press(key);
-        }, classifyInputError);
+        }, classifyInputError));
     }
     /**
      * Refuses focused typing when nothing that takes keystrokes has focus, in
@@ -599,8 +643,16 @@ export class PlaywrightSurface {
      */
     async requireEditableFocus(page) {
         const editable = await Promise.all(page.frames().map((frame) => frame
-            .evaluate(() => {
-            const active = document.activeElement;
+            .evaluate((key) => {
+            const recorded = Reflect.get(globalThis, Symbol.for(key));
+            let active = document.activeElement;
+            while (active !== null) {
+                const root = active.shadowRoot ?? (recorded instanceof WeakMap ? recorded.get(active) : undefined);
+                const leaf = root?.activeElement;
+                if (leaf === undefined || leaf === null)
+                    break;
+                active = leaf;
+            }
             if (active === null || active === document.body || active === document.documentElement)
                 return false;
             if (active instanceof HTMLInputElement) {
@@ -608,11 +660,12 @@ export class PlaywrightSurface {
             }
             if (active instanceof HTMLTextAreaElement)
                 return !active.disabled && !active.readOnly;
-            if (active instanceof HTMLSelectElement || active instanceof HTMLButtonElement || active instanceof HTMLAnchorElement) {
+            if (active instanceof HTMLSelectElement || active instanceof HTMLButtonElement || active instanceof HTMLAnchorElement ||
+                active instanceof HTMLIFrameElement || active instanceof HTMLFrameElement) {
                 return false;
             }
             return true;
-        })
+        }, CLOSED_SHADOW_ROOTS_KEY)
             .catch(() => false)));
         if (!editable.some(Boolean)) {
             throw new EngineError('NOT_ACTIONABLE', 'nothing that takes keystrokes has focus: the typed text would reach no field. Tap the field first, or type into a listed input by id.', { retryable: false });
@@ -622,10 +675,14 @@ export class PlaywrightSurface {
      * Checks that every frame selector along the expression matches exactly one
      * element, each counted inside the frame before it, the way `project` walks
      * 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.
+     * 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.
      */
-    async validateFrames(expression) {
+    async frameBox(expression) {
         let scope = this.requirePage();
+        let element;
         for (const selector of frameSelectors(expression)) {
             let count;
             try {
@@ -644,8 +701,18 @@ export class PlaywrightSurface {
                     retryable: false,
                 });
             }
+            element = scope.locator(selector);
             scope = scope.frameLocator(selector);
         }
+        if (element === undefined)
+            return undefined;
+        try {
+            const border = await element.boundingBox();
+            return border === null ? null : contentBox(border, await element.evaluate(frameContentInset));
+        }
+        catch (cause) {
+            throw translatePwError(cause, 'frame resolution');
+        }
     }
     // --- artifacts ---
     /**
@@ -673,15 +740,7 @@ export class PlaywrightSurface {
             return relative;
         });
     }
-    /** Starts tracing the current attempt. */
-    startTrace(operation) {
-        return this.guard(operation, 'trace', () => this.requireSession().startTrace());
-    }
-    /** Returns every trace segment finalized by the current attempt. */
-    stopTrace(operation) {
-        return this.requireSession().collectTrace(operation);
-    }
-    /** Starts the attempt's video before a trace chooses its screencast dimensions. */
+    /** Starts the attempt's video. */
     startVideo(operation) {
         return this.guard(operation, 'video', (current) => this.requireSession().startVideo(current.signal));
     }
@@ -756,3 +815,15 @@ export class PlaywrightSurface {
         }
     }
 }
+/**
+ * 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
+ * when the frame has no box or the node lies outside it.
+ */
+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 };
+}

package/dist/trace-feed.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What the web engine tells the harness for an attempt's trace, apart from
+ * the app log: the screen an action left (`EngineAttemptContext.screen`),
+ * and the browser and user agent the attempt runs on (`environment`). One
+ * feed per attempt; it never fails what the test does.
+ */
+import type { Page } from 'playwright-core';
+import type { EngineAttemptContext, OperationContext } from 'e2e/engine';
+import { type CaptureSettings } from './observation-capture.ts';
+import { RefRegistry } from './refs.ts';
+export declare class TraceFeed {
+    private readonly context;
+    private readonly page;
+    private readonly refs;
+    private readonly settings;
+    /** Whether the feed told the harness what the attempt runs on. */
+    private environmentTold;
+    /**
+     * `page` reads the attempt's open page without touching the error latch;
+     * `refs` is the registry a screen is captured against, then let go.
+     */
+    constructor(context: Pick<EngineAttemptContext, 'screen' | 'environment'>, page: () => Page | undefined, refs: () => RefRegistry | undefined, settings: CaptureSettings);
+    /**
+     * Tells the harness, once an attempt, the browser and the user agent its
+     * page reports. Best effort and not awaited: nothing the test does waits
+     * on it.
+     */
+    tellEnvironment(): void;
+    /** The browser and the user agent the page reports, within a second; undefined without a page or a browser to ask. */
+    private environmentFacts;
+    /**
+     * Hands the harness the screen an action left. The read is on the action's
+     * path, as the `screen` contract allows, and only when the attempt keeps a
+     * trace (the harness hands no `screen` otherwise). The screen is captured
+     * like an observation but never published, so every ref a test or model
+     * holds stays valid; a page that cannot answer within a second leaves the
+     * step without one.
+     */
+    screenAfterAction(operation: OperationContext): Promise<void>;
+}

package/dist/trace-feed.js

@@ -0,0 +1,93 @@
+/**
+ * What the web engine tells the harness for an attempt's trace, apart from
+ * the app log: the screen an action left (`EngineAttemptContext.screen`),
+ * and the browser and user agent the attempt runs on (`environment`). One
+ * feed per attempt; it never fails what the test does.
+ */
+import { captureObservation } from './observation-capture.js';
+import { withOperationDeadline } from './operation-budget.js';
+import { RefRegistry } from './refs.js';
+/** How long the screen an action left may take for the trace before the step goes without one. */
+const TRACE_SCREEN_TIMEOUT_MS = 1_000;
+/** How long the page may take to report its user agent before the trace names the browser alone. */
+const ENVIRONMENT_TIMEOUT_MS = 1_000;
+export class TraceFeed {
+    context;
+    page;
+    refs;
+    settings;
+    /** Whether the feed told the harness what the attempt runs on. */
+    environmentTold = false;
+    /**
+     * `page` reads the attempt's open page without touching the error latch;
+     * `refs` is the registry a screen is captured against, then let go.
+     */
+    constructor(context, page, refs, settings) {
+        this.context = context;
+        this.page = page;
+        this.refs = refs;
+        this.settings = settings;
+    }
+    /**
+     * Tells the harness, once an attempt, the browser and the user agent its
+     * page reports. Best effort and not awaited: nothing the test does waits
+     * on it.
+     */
+    tellEnvironment() {
+        if (this.environmentTold)
+            return;
+        const sink = this.context.environment;
+        void this.environmentFacts().then((facts) => {
+            try {
+                if (facts !== undefined)
+                    sink(facts);
+            }
+            catch {
+                // The harness's sink never fails the attempt.
+            }
+        });
+    }
+    /** The browser and the user agent the page reports, within a second; undefined without a page or a browser to ask. */
+    async environmentFacts() {
+        try {
+            const page = this.page();
+            if (page === undefined)
+                return undefined;
+            this.environmentTold = true;
+            const browser = page.context().browser();
+            const facts = browser === null ? {} : { browser: `${browser.browserType().name()} ${browser.version()}` };
+            const budget = { signal: AbortSignal.timeout(ENVIRONMENT_TIMEOUT_MS), timeoutMs: ENVIRONMENT_TIMEOUT_MS };
+            const userAgent = await withOperationDeadline(budget, 'user agent', () => page.evaluate(() => navigator.userAgent)).catch(() => undefined);
+            return typeof userAgent === 'string' ? { ...facts, 'user agent': userAgent } : facts;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Hands the harness the screen an action left. The read is on the action's
+     * path, as the `screen` contract allows, and only when the attempt keeps a
+     * trace (the harness hands no `screen` otherwise). The screen is captured
+     * like an observation but never published, so every ref a test or model
+     * holds stays valid; a page that cannot answer within a second leaves the
+     * step without one.
+     */
+    async screenAfterAction(operation) {
+        const sink = this.context.screen;
+        const refs = this.refs();
+        if (sink === undefined || operation.signal.aborted || refs === undefined)
+            return;
+        try {
+            const page = this.page();
+            if (page === undefined)
+                return;
+            const budget = { signal: operation.signal, timeoutMs: TRACE_SCREEN_TIMEOUT_MS };
+            const captured = await withOperationDeadline(budget, 'trace screen', (remaining) => captureObservation(page, refs, this.settings, { ...operation, ...remaining() }, undefined));
+            RefRegistry.dispose(captured.generation);
+            sink(captured.snapshot);
+        }
+        catch {
+            // A screen the page could not give in time is no evidence the trace claims.
+        }
+    }
+}

package/dist/video.d.ts

@@ -26,8 +26,6 @@ import type { WebScreencastOptions } from './surface.ts';
 export interface AttemptVideo {
     /** True while pages the attempt opens start segments of their own. */
     readonly isArmed: boolean;
-    /** True when `arm` would start a screencast on the page, which a running trace sized for itself. */
-    readonly startsScreencast: boolean;
     arm(page: Page, signal: AbortSignal): Promise<void>;
     pageOpened(page: Page): Promise<void>;
     pageClosing(): Promise<void>;
@@ -50,8 +48,6 @@ export declare class VideoRecorder implements AttemptVideo {
     constructor(artifactsDir: string, options?: WebScreencastOptions);
     /** True between `arm` and `stop`: a page the attempt opens then starts a segment. */
     get isArmed(): boolean;
-    /** True while no segment records: `arm` then starts one on the page it is given. */
-    get startsScreencast(): boolean;
     /** Starts the recording on `page`, unless a segment already records, and arms it. */
     arm(page: Page): Promise<void>;
     /** A page the attempt opened: the next segment, when armed. */

package/dist/video.js

@@ -17,6 +17,14 @@ import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { EngineError } from 'e2e/engine';
 import { currentViewport, message } from './support.js';
+/**
+ * How long a segment that has not received a frame yet waits for one before
+ * it ends. A screencast sends a frame only when the page repaints, and on
+ * Linux the frame of a page that just painted arrives after the paint: a
+ * segment stopped right after a navigation would otherwise end with no frame,
+ * which Playwright writes as a white video.
+ */
+const FIRST_FRAME_WAIT_MS = 1_000;
 export class VideoRecorder {
     artifactsDir;
     options;
@@ -37,10 +45,6 @@ export class VideoRecorder {
     get isArmed() {
         return this.armed;
     }
-    /** True while no segment records: `arm` then starts one on the page it is given. */
-    get startsScreencast() {
-        return this.current === null;
-    }
     /** Starts the recording on `page`, unless a segment already records, and arms it. */
     async arm(page) {
         if (this.current === null)
@@ -90,12 +94,15 @@ export class VideoRecorder {
         mkdirSync(path.dirname(absolute), { recursive: true });
         const { quality } = this.options;
         const size = this.options.size ?? await currentViewport(page);
+        let framedOnce = () => undefined;
+        const framed = new Promise((resolve) => (framedOnce = resolve));
         await page.screencast.start({
             path: absolute,
             size: { width: size.width, height: size.height },
             ...(quality === undefined ? {} : { quality }),
+            onFrame: () => framedOnce(),
         });
-        this.current = { page, relative, absolute, startedAt: new Date().toISOString() };
+        this.current = { page, relative, absolute, startedAt: new Date().toISOString(), framed };
     }
     /**
      * Ends the segment in progress. A stop that failed but left a file keeps
@@ -108,6 +115,7 @@ export class VideoRecorder {
         if (segment === null)
             return;
         this.current = null;
+        await waitForFrame(segment, FIRST_FRAME_WAIT_MS);
         try {
             await segment.page.screencast.stop();
         }
@@ -122,3 +130,13 @@ export class VideoRecorder {
         }
     }
 }
+/** Waits up to `timeoutMs` for the segment's first frame. */
+async function waitForFrame(segment, timeoutMs) {
+    let timer;
+    try {
+        await Promise.race([segment.framed, new Promise((resolve) => (timer = setTimeout(resolve, timeoutMs)))]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e2e-dev/web",
-  "version": "0.13.0",
+  "version": "0.14.0-nightly-20261008205824",
   "description": "Web engine for e2e agentic end-to-end testing, built on Playwright",
   "keywords": [
     "e2e",
@@ -50,11 +50,11 @@
     "playwright-core": "1.63.0"
   },
   "peerDependencies": {
-    "e2e": ">=0.18.0 <1"
+    "e2e": "0.19.0-nightly-20261008205824"
   },
   "devDependencies": {
     "@types/node": "26.6.2",
-    "e2e": "0.18.0",
+    "e2e": "0.19.0-nightly-20261008205824",
     "@types/pngjs": "6.0.5",
     "pngjs": "7.0.0",
     "typescript": "7.0.2",