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

package/dist/in-page/read-semantics.js

@@ -54,11 +54,11 @@ export const readSemanticsFunction = (element, options) => {
     const PLACEHOLDER_NAMED_INPUT_TYPES = ['text', 'password', 'number', 'search', 'tel', 'email', 'url'];
     /**
      * How the active mode projects one node, expressed as data so `describe`
-     * stays branch-free. Tree mode is the model-bound projection: bounded text,
-     * a bounded attribute projection, hrefs reduced to origin+path, the root
-     * document named by its title, and no value on a checkbox or radio, whose
-     * value attribute is an app token its checked state already says more
-     * than. Node mode is the full locator-read surface.
+     * stays branch-free. Tree mode is the model-bound projection: bounded line
+     * text (`lineTextOf`), a bounded attribute projection, hrefs reduced to
+     * origin+path, the root document named by its title, and no value on a
+     * checkbox or radio, whose value attribute is an app token its checked
+     * state already says more than. Node mode is the full locator-read surface.
      */
     const projection = options.mode.kind === 'tree'
         ? {
@@ -66,7 +66,7 @@ export const readSemanticsFunction = (element, options) => {
             textLimit: options.mode.textLimit,
             nameLimit: options.mode.nameLimit,
             redactHref: true,
-            directTextOnly: true,
+            lineText: true,
             documentRoot: true,
             checkableValue: false,
         }
@@ -75,7 +75,7 @@ export const readSemanticsFunction = (element, options) => {
             textLimit: null,
             nameLimit: null,
             redactHref: false,
-            directTextOnly: false,
+            lineText: false,
             documentRoot: false,
             checkableValue: true,
         };
@@ -111,7 +111,15 @@ export const readSemanticsFunction = (element, options) => {
      * HTML-AAM scopes it to sectioning content and to the ARIA roles that stand
      * for it, so a `<div role="article">` scopes it like an `<article>`.
      */
-    const isPageLevel = (el) => el.closest(SECTIONING_SCOPE) === null;
+    const isPageLevel = (el) => {
+        for (let candidate = el; candidate !== null;) {
+            if (candidate.closest(SECTIONING_SCOPE) !== null)
+                return false;
+            const root = candidate.getRootNode();
+            candidate = root instanceof ShadowRoot ? root.host : null;
+        }
+        return true;
+    };
     /**
      * The root of a contenteditable region: editable itself, under a parent that
      * is not. A rich-text editor (ProseMirror, TipTap, Lexical, Slate) renders
@@ -368,7 +376,7 @@ export const readSemanticsFunction = (element, options) => {
     /** An element's `::after` contribution, once per read. */
     const afterContentOf = memoized((el) => generatedContentOf(el, '::after'));
     /** True for a subtree the name computation drops: aria-hidden, or hidden by style as innerText leaves it out. */
-    const isNameHidden = (el, style) => el.getAttribute('aria-hidden') === 'true' ||
+    const isNameHidden = (el, style) => (el.getAttribute('aria-hidden') ?? '').toLowerCase() === 'true' ||
         (style !== undefined && (style.display === 'none' || style.visibility === 'hidden'));
     /** `alt` of an element HTML-AAM names by it: an `<img>` or an `<input type="image">`. */
     const altOf = (el) => {
@@ -399,7 +407,7 @@ export const readSemanticsFunction = (element, options) => {
      * under an `aria-hidden` ancestor, which excludes it from the tree as
      * surely as its own attribute would.
      */
-    const isReferenceHidden = (el) => isHidden(el) || el.closest('[aria-hidden="true"]') !== null;
+    const isReferenceHidden = (el) => isHidden(el) || el.closest('[aria-hidden="true" i]') !== null;
     /**
      * The element an id names for `el`, looked up in `el`'s own tree: an IDREF
      * resolves in the tree scope it is written in, so a shadow tree's ids are
@@ -682,6 +690,121 @@ export const readSemanticsFunction = (element, options) => {
         }
         return out.replace(/\s+/g, ' ').trim();
     });
+    /**
+     * Elements whose content is not text in a line: a form control's options
+     * or value, a picture, a frame, a drawn surface. Like a line break, each
+     * separates the words around it.
+     */
+    const LINE_BREAKING_TAGS = [...SKIP_TAGS, ...OPAQUE_TAGS, 'iframe', 'img', 'input', 'select', 'textarea', 'br'];
+    /**
+     * True when an element's text flows in its parent's line: a visible
+     * inline-level box (`inline`, `inline-block`, `ruby`), or `display:
+     * contents`, whose children lay out as the parent's own. Visible as the
+     * walk reads it (`isHidden`): a box with no size shows no words. A slot
+     * has no box and shows the nodes assigned to it, so only its visibility
+     * counts: a hidden one hides the text they inherit it with, and a child
+     * that shows itself again is listed on its own.
+     */
+    const flowsInLine = memoized((el) => {
+        if (LINE_BREAKING_TAGS.indexOf(el.tagName.toLowerCase()) !== -1 || isEditingHost(el))
+            return false;
+        const style = styleOf(el);
+        if (style === undefined || hidesSubtree(el, style))
+            return false;
+        if (el instanceof HTMLSlotElement ? style.visibility !== 'visible' : isHidden(el, style))
+            return false;
+        return isInlineLevel(style);
+    });
+    /** True for a box laid out in its parent's line, or for `display: contents`, which lays out none of its own. */
+    const isInlineLevel = (style) => style.display.startsWith('inline') || style.display.startsWith('ruby') || style.display === 'contents';
+    /**
+     * The nodes an element renders in its place, as the walk reaches them: a
+     * shadow host's shadow tree (a closed one through the record), a slot's
+     * assigned nodes or else its fallback content, any other element's children.
+     */
+    const renderedChildrenOf = (el) => {
+        const shadow = shadowRootOf(el);
+        if (shadow !== null)
+            return Array.from(shadow.childNodes);
+        if (el instanceof HTMLSlotElement) {
+            const assigned = el.assignedNodes();
+            if (assigned.length > 0)
+                return assigned;
+        }
+        return Array.from(el.childNodes);
+    };
+    /**
+     * An element's rendered text with each inline descendant's text in place.
+     * Anything else in the line reads as a space, except a hidden inline
+     * element (a `<wbr>`, a zero-size span), which shows nothing.
+     */
+    const lineRunOf = (el) => {
+        let out = '';
+        for (const child of renderedChildrenOf(el)) {
+            if (child.nodeType === 3)
+                out += child.nodeValue ?? '';
+            if (child.nodeType !== 1)
+                continue;
+            const inner = child;
+            if (flowsInLine(inner)) {
+                out += lineRunOf(inner);
+                continue;
+            }
+            const style = styleOf(inner);
+            if (style === undefined || hidesSubtree(inner, style))
+                continue;
+            const breaking = LINE_BREAKING_TAGS.indexOf(inner.tagName.toLowerCase()) !== -1;
+            if (breaking || !isInlineLevel(style) || !isHidden(inner, style))
+                out += ' ';
+        }
+        return out;
+    };
+    /**
+     * The text an element owns, read as a person reads its line: its own text
+     * with every inline descendant's text in place, so `<p>Read our <a>privacy
+     * policy</a> for details.</p>` reads as the whole sentence while the link
+     * stays a node of its own. Block-level descendants are nodes of their own
+     * and only separate words. An element with no text of its own owns none: a
+     * wrapper of elements leaves them to say what they say (`ownsLine`).
+     */
+    const lineTextOf = memoized((el) => ownsLine(el) ? lineRunOf(el).replace(/\s+/g, ' ').trim() : '');
+    /**
+     * True when an element reads its own line: it has text of its own, or it
+     * offers an action inside an ancestor's line, where its words are what a
+     * person aims at.
+     */
+    const ownsLine = (el) => directTextOf(el) !== '' || (offersAction(el) && isReadInLine(el));
+    /**
+     * True when an element with no role still says it can be acted on: it is
+     * focusable through `tabindex`, it has a click handler set as an attribute
+     * or a property (`onclick`), or it is an `<a>` with no `href`, which an app
+     * wires up by script. Such an element stays listed inside a line, so it
+     * keeps an id to act on. A handler added with `addEventListener` leaves
+     * nothing the page can read.
+     */
+    const offersAction = memoized((el) => {
+        const tabindex = el.getAttribute('tabindex');
+        if (tabindex !== null && /^\s*[-+]?\d/.test(tabindex))
+            return true;
+        if (el.tagName.toLowerCase() === 'a' || el.hasAttribute('onclick'))
+            return true;
+        return el instanceof HTMLElement && el.onclick !== null;
+    });
+    /**
+     * True when an element's text is already read in an ancestor's line
+     * (`lineTextOf`), so the element has nothing to add on text alone. A line
+     * longer than the projection's text bound is cut, so its inline
+     * descendants stay listed and nothing past the cut is lost.
+     */
+    const isReadInLine = memoized((el) => {
+        const parent = el.assignedSlot ?? parentOrHostOf(el);
+        if (parent === null || !flowsInLine(el))
+            return false;
+        if (!ownsLine(parent))
+            return isReadInLine(parent);
+        const fits = projection.textLimit === null || lineTextOf(parent).length <= projection.textLimit;
+        return fits && !isHidden(parent);
+    });
     const accessibleName = memoized((el) => {
         // accname reads a labelledby reference (2B) before the element's own aria-label (2C).
         const referenced = referencedNamesOf(el, nameWalk([], true));
@@ -905,7 +1028,7 @@ export const readSemanticsFunction = (element, options) => {
      * edges. The walk goes on through both and only the element itself stays
      * unlisted.
      */
-    const hidesSubtree = (el, style) => el.getAttribute('aria-hidden') === 'true' ||
+    const hidesSubtree = (el, style) => (el.getAttribute('aria-hidden') ?? '').toLowerCase() === 'true' ||
         isInert(el, style) ||
         style === undefined ||
         style.display === 'none' ||
@@ -1194,7 +1317,7 @@ export const readSemanticsFunction = (element, options) => {
         if (selectedState === null) {
             const ariaSelected = el.getAttribute('aria-selected');
             if (ariaSelected !== null)
-                selectedState = ariaSelected === 'true';
+                selectedState = ariaSelected.toLowerCase() === 'true';
         }
         const disabled = isDisabled(el);
         const ariaExpanded = el.getAttribute('aria-expanded');
@@ -1238,8 +1361,8 @@ export const readSemanticsFunction = (element, options) => {
         let text;
         if (secure)
             text = '';
-        else if (projection.directTextOnly)
-            text = directTextOf(el);
+        else if (projection.lineText)
+            text = lineTextOf(el);
         else
             text = textOf(el);
         if (projection.textLimit !== null)
@@ -1334,7 +1457,9 @@ export const readSemanticsFunction = (element, options) => {
             return true;
         if (accessibleName(el) !== null)
             return true;
-        return directTextOf(el) !== '';
+        if (offersAction(el) && isReadInLine(el))
+            return lineTextOf(el) !== '';
+        return directTextOf(el) !== '' && !isReadInLine(el);
     };
     const walk = (el, parent) => {
         if (truncated)

package/dist/init-scripts.js

@@ -7,7 +7,7 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { ConfigurationError, TestError, validateJsonValue } from 'e2e/engine';
-import { KEEP_NAMES_HELPER } from './evaluation.js';
+import { KEEP_NAMES_HELPER, pageFunctionSource } from './evaluation.js';
 import { message } from './support.js';
 /** Refuses, at config load, a `web({ initScripts })` value that is not a list of scripts. */
 export function validateInitScripts(scripts) {
@@ -93,7 +93,7 @@ async function initScriptSource(script, arg, resolvePath) {
     if (typeof script === 'string')
         return script;
     if (typeof script === 'function') {
-        return `(() => {\n${KEEP_NAMES_HELPER}\n(${script.toString()}\n)(${arg === undefined ? '' : `JSON.parse(${JSON.stringify(JSON.stringify(arg))})`});\n})();`;
+        return `(() => {\n${KEEP_NAMES_HELPER}\n(${pageFunctionSource(script)}\n)(${arg === undefined ? '' : `JSON.parse(${JSON.stringify(JSON.stringify(arg))})`});\n})();`;
     }
     const file = resolvePath(script.path);
     try {

package/dist/observation-capture.d.ts

@@ -2,10 +2,9 @@
 import type { Page } from 'playwright-core';
 import { type EngineObserveOptions, type OperationContext } from 'e2e/engine';
 import { RefRegistry, type CapturedObservation } from './refs.ts';
-interface CaptureSettings {
+export interface CaptureSettings {
     readonly testIdAttribute: string;
     readonly site: string | undefined;
 }
 /** Captures under one deadline, retaining no refs from a failed or abandoned document. */
 export declare function captureObservation(page: Page, refs: RefRegistry, settings: CaptureSettings, operation: OperationContext, options: EngineObserveOptions | undefined): Promise<CapturedObservation>;
-export {};

package/dist/observation.d.ts

@@ -59,4 +59,20 @@ export interface CapturedDocument {
  * observation. The node budget is shared across all documents.
  */
 export declare function captureDocument(deps: CaptureDeps, host: DocumentHost, options: CaptureOptions): Promise<CapturedDocument>;
+type Rect = NonNullable<SemanticNode['rect']>;
+/**
+ * Where a frame element's content box, the box its document's viewport
+ * fills, sits inside its border box: past the border and the padding. Runs in
+ * the page.
+ */
+export declare function frameContentInset(element: Element): Rect;
+/** A frame element's content box, from its border box and `frameContentInset`. */
+export declare function contentBox(border: Rect, inset: Rect): Rect;
+/**
+ * A box a child document measured against its own viewport, in the top-level
+ * viewport's space: shifted by the frame's box and clipped to it; undefined
+ * when nothing of it is inside the frame.
+ */
+export declare function placeRectInFrame(rect: Rect, frame: Rect): Rect | undefined;
 export declare function toSemanticNode(ref: NodeRef, raw: RawNodeData, children?: readonly SemanticNode[], framePath?: readonly string[]): SemanticNode;
+export {};

package/dist/observation.js

@@ -129,6 +129,11 @@ async function captureInto(deps, scope, stage, host, framePath, budget, signal)
             truncated = true;
             continue;
         }
+        const inset = await scope.read(() => elements[index].evaluate(frameContentInset).catch(() => undefined));
+        if (inset === undefined) {
+            truncated = true;
+            continue;
+        }
         const child = await scope.read(() => captureDocument({ ...deps, commit: stage }, frame, {
             framePath: [...framePath, selector],
             budget: remaining,
@@ -139,7 +144,7 @@ async function captureInto(deps, scope, stage, host, framePath, budget, signal)
             truncated = true;
             continue;
         }
-        frameChildren.set(index, child.tree);
+        frameChildren.set(index, { tree: child.tree, inset });
         nodeCount += child.nodeCount;
         truncated ||= child.truncated;
     }
@@ -205,16 +210,16 @@ function assembleTree(nodes, ids, framePath, frameChildren) {
     for (let index = nodes.length - 1; index >= 0; index -= 1) {
         const raw = nodes[index];
         const embedded = frameChildren.get(index);
-        // A child document measured its nodes against its own viewport. Shifted by
-        // the boundary element's box and clipped to it, every box in the tree is
-        // in the top-level viewport's CSS pixels, the space the screenshot and a
-        // point tap share, and a child that overflows its frame cannot claim a
-        // point over the page around it. The shift is the frame's border box; a
-        // bordered iframe is off by its border width, which is within a tap
-        // target. A frame under a CSS transform is not unwound: its boxes are
-        // where the untransformed frame would put them.
-        if (embedded !== undefined && raw.rect !== null)
-            childLists[index].unshift(placeInFrame(embedded, raw.rect));
+        // A child document measured its nodes against its own viewport, which
+        // starts at the frame element's content box. Shifted by that box and
+        // clipped to it, every box in the tree is in the top-level viewport's CSS
+        // pixels, the space the screenshot and a point tap share, and a child that
+        // overflows its frame cannot claim a point over the page around it. A
+        // frame under a CSS transform is not unwound: its boxes are where the
+        // untransformed frame would put them.
+        if (embedded !== undefined && raw.rect !== null) {
+            childLists[index].unshift(placeInFrame(embedded.tree, contentBox(raw.rect, embedded.inset)));
+        }
         const node = toSemanticNode({ id: ids[index], revision: '' }, raw, childLists[index], framePath);
         built[index] = node;
         if (raw.parent >= 0)
@@ -222,16 +227,46 @@ function assembleTree(nodes, ids, framePath, frameChildren) {
     }
     return built[0];
 }
+/**
+ * Where a frame element's content box, the box its document's viewport
+ * fills, sits inside its border box: past the border and the padding. Runs in
+ * the page.
+ */
+export function frameContentInset(element) {
+    const style = getComputedStyle(element);
+    const left = Number.parseFloat(style.paddingLeft) || 0;
+    const top = Number.parseFloat(style.paddingTop) || 0;
+    const right = Number.parseFloat(style.paddingRight) || 0;
+    const bottom = Number.parseFloat(style.paddingBottom) || 0;
+    return {
+        x: element.clientLeft + left,
+        y: element.clientTop + top,
+        width: Math.max(0, element.clientWidth - left - right),
+        height: Math.max(0, element.clientHeight - top - bottom),
+    };
+}
+/** A frame element's content box, from its border box and `frameContentInset`. */
+export function contentBox(border, inset) {
+    return { x: border.x + inset.x, y: border.y + inset.y, width: inset.width, height: inset.height };
+}
 /** The tree with every box translated into the frame's space and clipped to its box; a box left empty by the clip is dropped. */
 function placeInFrame(node, frame) {
     const { rect, ...rest } = node;
-    const placed = rect === undefined ? undefined : clipRect(offsetRect(rect, frame), frame);
+    const placed = rect === undefined ? undefined : placeRectInFrame(rect, frame);
     return {
         ...rest,
         ...(placed === undefined ? {} : { rect: placed }),
         ...(node.children === undefined ? {} : { children: node.children.map((child) => placeInFrame(child, frame)) }),
     };
 }
+/**
+ * A box a child document measured against its own viewport, in the top-level
+ * viewport's space: shifted by the frame's box and clipped to it; undefined
+ * when nothing of it is inside the frame.
+ */
+export function placeRectInFrame(rect, frame) {
+    return clipRect(offsetRect(rect, frame), frame);
+}
 function offsetRect(rect, by) {
     return { x: rect.x + by.x, y: rect.y + by.y, width: rect.width, height: rect.height };
 }

package/dist/operation-budget.js

@@ -11,8 +11,8 @@ export function connectionAbort(signal, label) {
  * fires: its error names what blocked an action, or that the input was
  * already dispatched, and this lead lets that answer arrive before the
  * deadline does. The deadline is for the calls Playwright never answers: an
- * evaluate, which takes no timeout, and every call while a trace snapshots a
- * page whose renderer is stuck in a script. A budget shorter than twice the
+ * evaluate, which takes no timeout, and a point tap on a page whose renderer
+ * is stuck in a script. A budget shorter than twice the
  * lead splits in half.
  */
 const PLAYWRIGHT_TIMEOUT_LEAD_MS = 250;

package/dist/provider-video.d.ts

@@ -13,8 +13,6 @@ export declare class ProviderVideo implements AttemptVideo {
     private readonly artifactsDir;
     /** The recording covers the browser, so no page starts a segment of its own. */
     readonly isArmed = false;
-    /** The provider records the browser from outside; the page's screencast stays the trace's. */
-    readonly startsScreencast = false;
     private started;
     /** The stop in flight, shared: a close that retries while a timed-out stop is still running waits for it instead of stopping twice. */
     private stopping;

package/dist/provider-video.js

@@ -13,8 +13,6 @@ export class ProviderVideo {
     artifactsDir;
     /** The recording covers the browser, so no page starts a segment of its own. */
     isArmed = false;
-    /** The provider records the browser from outside; the page's screencast stays the trace's. */
-    startsScreencast = false;
     started;
     /** The stop in flight, shared: a close that retries while a timed-out stop is still running waits for it instead of stopping twice. */
     stopping;

package/dist/surface.d.ts

@@ -107,8 +107,7 @@ export interface WebOptions {
      * page, deterministic and agent-driven alike. Injecting headers routes
      * every request of the attempt, which turns the browser's HTTP cache off
      * and blocks service workers (a worker's requests bypass routing, so a
-     * page it controlled would reach the gate bare), and a Playwright trace
-     * records request headers.
+     * page it controlled would reach the gate bare).
      */
     readonly headers?: Readonly<Record<string, string>>;
     /**
@@ -187,6 +186,10 @@ export declare class PlaywrightSurface {
     private projectRoot;
     private headed;
     private artifactsDir;
+    /** Navigations the engine has in flight, which the app log leaves to the step that started them. */
+    private ownNavigations;
+    /** What the attempt tells its trace beside the app log; absent between attempts. */
+    private trace;
     private artifactCounter;
     /**
      * Attempt-scoped network routes. Registered on the
@@ -261,8 +264,8 @@ export declare 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.
      */
     dispose(context: EngineCleanupContext): Promise<void>;
     /** Returns the active attempt, including its connection generation and references. */
@@ -277,6 +280,12 @@ export declare class PlaywrightSurface {
     projectPath(file: string): string;
     /** Removes one registered route from the attempt and the current context. */
     unroute(predicate: RoutePredicate, handler: RouteHandler): Promise<void>;
+    /**
+     * 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.
+     */
+    private openPage;
     requirePage(): Page;
     requireContext(): BrowserContext;
     /**
@@ -308,6 +317,10 @@ export declare class PlaywrightSurface {
     /** Opens one URL the harness resolved; the attempt's page is created on first use. */
     open(url: string, operation: OperationContext): Promise<void>;
     back(operation: OperationContext): Promise<void>;
+    /** Runs one navigation the engine itself makes, so the app log leaves it to the step that asked for it. */
+    navigating<T>(work: () => Promise<T>): Promise<T>;
+    /** Resolves with what an action resolved with once the trace has the screen it left (`TraceFeed.screenAfterAction`); an action that failed leaves none. */
+    private acted;
     /** Restarts the document while retaining this attempt's context and storage. */
     restart(operation: OperationContext): Promise<void>;
     /** Replaces the context with a clean one and opens its blank page. */
@@ -356,9 +369,12 @@ export declare 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.
      */
-    private validateFrames;
+    private frameBox;
     /**
      * Reserves one artifact path under the attempt directory: a per-attempt
      * counter keeps names unique, the label keeps them readable.
@@ -369,11 +385,7 @@ export declare class PlaywrightSurface {
     };
     /** Redacted at the source: secure fields in every frame are masked, as in observation pixels. */
     screenshot(label: string | undefined, operation: OperationContext): Promise<string>;
-    /** Starts tracing the current attempt. */
-    startTrace(operation: OperationContext): Promise<void>;
-    /** Returns every trace segment finalized by the current attempt. */
-    stopTrace(operation: OperationContext): Promise<string | readonly string[]>;
-    /** Starts the attempt's video before a trace chooses its screencast dimensions. */
+    /** Starts the attempt's video. */
     startVideo(operation: OperationContext): Promise<void>;
     /** Finishes the attempt's recording and returns its finalized segments. */
     stopVideo(operation: OperationContext): Promise<readonly VideoSegment[]>;