@e2e-dev/web 0.11.1 → 0.12.0

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

@@ -9,11 +9,10 @@
  * Serialized into the page by Playwright. Must stay self-contained: no outer
  * captures beyond its two arguments.
  *
- * `mode.kind === 'node'` reads exactly one element for locator reads. An
- * element no longer in its document reads as detached with its value alone:
- * a handle taken a moment earlier can point at a node the page has since
- * replaced, and what such a node reports (no boxes, so hidden) describes
- * nothing on screen.
+ * `mode.kind === 'node'` reads exactly one element for locator reads, in
+ * the selector engine's task that found it (`read-selector.ts`,
+ * `label-selector.ts`), so the element is always in its document.
+ * `mode.kind === 'hidden'` answers that one element's `states.hidden` alone.
  * `mode.kind === 'tree'` walks the subtree for one agent observation and
  * returns live element handles aligned with the flattened node list. The two
  * modes also project nodes differently; those differences are data (see
@@ -56,8 +55,10 @@ export const readSemanticsFunction = (element, options) => {
     /**
      * 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, and the root
-     * document named by its title. Node mode is the full locator-read surface.
+     * 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'
         ? {
@@ -67,6 +68,7 @@ export const readSemanticsFunction = (element, options) => {
             redactHref: true,
             directTextOnly: true,
             documentRoot: true,
+            checkableValue: false,
         }
         : {
             attributes: null,
@@ -75,6 +77,7 @@ export const readSemanticsFunction = (element, options) => {
             redactHref: false,
             directTextOnly: false,
             documentRoot: false,
+            checkableValue: true,
         };
     /**
      * Per-element memo for the facts several passes need. A tree walk asks for
@@ -148,6 +151,10 @@ export const readSemanticsFunction = (element, options) => {
                 return 'textbox';
             case 'img':
                 return el.getAttribute('alt') === '' ? 'presentation' : 'image';
+            // An inline icon is a picture whether or not anything names it, as
+            // Playwright reads it; Chrome ignores an unnamed one.
+            case 'svg':
+                return 'image';
             case 'nav':
                 return 'navigation';
             case 'main':
@@ -260,11 +267,11 @@ export const readSemanticsFunction = (element, options) => {
     /** Computed style of any element, SVG included, or undefined in a document with no view. */
     const styleOf = (el) => el.ownerDocument.defaultView?.getComputedStyle(el);
     /** A walk from the top, with the elements that may not contribute again already visited. */
-    const nameWalk = (visited, generated) => ({
+    const nameWalk = (visited, accessible) => ({
         inReference: false,
         hiddenAllowed: false,
         visited: new Set(visited),
-        generated,
+        accessible,
     });
     /**
      * Private-use code points: icon-font glyphs (Font Awesome's `\f090`) that
@@ -355,6 +362,24 @@ export const readSemanticsFunction = (element, options) => {
         const alt = named ? el.getAttribute('alt') : null;
         return alt !== null && alt.trim() !== '' ? alt.trim() : null;
     };
+    /**
+     * The `<title>` child an SVG element is named by (SVG-AAM), as Playwright
+     * reads it: `<svg><title>Close</title></svg>` is the image "Close". An svg
+     * marked `presentation` or `none` takes no name of its own from it, though
+     * the title still names a link or button around it.
+     */
+    const svgTitleOf = (el) => {
+        if (!(el instanceof SVGElement))
+            return null;
+        const title = Array.from(el.children).find((child) => child instanceof SVGTitleElement);
+        const text = (title?.textContent ?? '').replace(/\s+/g, ' ').trim();
+        return text === '' ? null : text;
+    };
+    /** True for an element whose role removes its semantics: `presentation` or `none`. */
+    const isPresentational = (el) => {
+        const role = implicitRole(el);
+        return role === 'presentation' || role === 'none';
+    };
     /**
      * True for a referenced target accname 2A reads whole: hidden itself, or
      * under an `aria-hidden` ancestor, which excludes it from the tree as
@@ -395,21 +420,86 @@ export const readSemanticsFunction = (element, options) => {
                 inReference: true,
                 hiddenAllowed: isReferenceHidden(target),
                 visited: walk.visited,
-                generated: walk.generated,
+                accessible: walk.accessible,
             }));
         }
         if (contributions.join(' ') === '')
             return null;
         return contributions.map((text) => text.replace(/\s+/g, ' ').trim()).filter((name) => name !== '');
     };
+    /**
+     * What an embedded control contributes to a name computed through another
+     * element (accname 2C), by the rules Playwright's role selector applies, so
+     * `<button>Flash the screen <input value="3"> times</button>` is the button
+     * "Flash the screen 3 times": a textbox or searchbox its current value (an
+     * editable element its text), a combobox or listbox its selected options'
+     * names (a native select with none selected its first option, a text field
+     * with none its value), and a range widget its `aria-valuetext`, else its
+     * `aria-valuenow`, else its `value` attribute. A menu contributes nothing,
+     * and neither does a secure field, whose value no name may carry. Null for
+     * any other element, and for one its own `aria-labelledby` names, which is
+     * named, not embedded.
+     */
+    const embeddedControlNameOf = (el, walk) => {
+        const role = implicitRole(el);
+        if (role === null)
+            return null;
+        if (el.id !== '' && (el.getAttribute('aria-labelledby') ?? '').trim().split(/\s+/).indexOf(el.id) !== -1)
+            return null;
+        if (el.matches(options.secureFieldSelector))
+            return '';
+        if (role === 'textbox' || role === 'searchbox') {
+            return el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement ? el.value : el.textContent ?? '';
+        }
+        if (role === 'combobox' || role === 'listbox') {
+            let selected;
+            if (el instanceof HTMLSelectElement) {
+                selected = Array.from(el.selectedOptions);
+                if (selected.length === 0 && el.options.length > 0)
+                    selected.push(el.options[0]);
+            }
+            else {
+                const listbox = role === 'combobox' ? ariaOwnedOf(el).find((owned) => implicitRole(owned) === 'listbox') : el;
+                selected = listbox === undefined
+                    ? []
+                    : ariaOwnedOf(listbox).filter((owned) => owned.getAttribute('aria-selected') === 'true' && implicitRole(owned) === 'option');
+            }
+            if (selected.length === 0 && el instanceof HTMLInputElement)
+                return el.value;
+            return selected.map((option) => contentNameOf(option, styleOf(option), walk)).join(' ');
+        }
+        if (role === 'progressbar' || role === 'scrollbar' || role === 'slider' || role === 'spinbutton' || role === 'meter') {
+            if (el.hasAttribute('aria-valuetext'))
+                return el.getAttribute('aria-valuetext') ?? '';
+            if (el.hasAttribute('aria-valuenow'))
+                return el.getAttribute('aria-valuenow') ?? '';
+            return el.getAttribute('value') ?? '';
+        }
+        return role === 'menu' ? '' : null;
+    };
+    /**
+     * Every element under `el` and every element its `aria-owns` names, with
+     * theirs: what a composite widget owns, as Playwright's role selector
+     * collects a combobox's listbox and a listbox's options.
+     */
+    const ariaOwnedOf = (el) => {
+        const owned = Array.from(el.querySelectorAll('*'));
+        for (const id of (el.getAttribute('aria-owns') ?? '').trim().split(/\s+/)) {
+            const target = id === '' ? null : referencedElementOf(el, id);
+            if (target !== null)
+                owned.push(target, ...Array.from(target.querySelectorAll('*')));
+        }
+        return owned;
+    };
     /**
      * What one element contributes to a name computed through another: as an
      * aria-labelledby target (accname 2B) or as a descendant read for name from
-     * content (2F). Its own references, else its `aria-label`, its `alt`, its
-     * children, then its `title`. So `<button><img alt="Search"></button>` is
-     * the button "Search", an icon whose only child is
+     * content (2F). Its own references, else its value as an embedded control,
+     * its `aria-label`, its `alt`, its children, then its `title`. So
+     * `<button><img alt="Search"></button>` is the button "Search", an icon
+     * whose only child is
      * `<svg aria-labelledby="t"><title id="t">Close</title></svg>` is "Close",
-     * and a hidden `<span>` a button references still names it. A form
+     * and a hidden `<span>` a button references still names it. Any other form
      * control's content is its value, not label text, so it contributes nothing.
      * The title is the fallback only for empty content, untrimmed as Playwright
      * reads it: the spaces a block-level child adds count, so a flex container's
@@ -425,12 +515,15 @@ export const readSemanticsFunction = (element, options) => {
         const referenced = referencedNamesOf(el, walk);
         if (referenced !== null)
             return referenced.join(' ');
+        const embedded = walk.accessible ? embeddedControlNameOf(el, walk) : null;
+        if (embedded !== null)
+            return embedded;
         const ariaLabel = el.getAttribute('aria-label');
         if (ariaLabel !== null && ariaLabel.trim() !== '')
             return ariaLabel.trim();
-        const alt = altOf(el);
-        if (alt !== null)
-            return alt;
+        const alternative = altOf(el) ?? svgTitleOf(el);
+        if (alternative !== null)
+            return alternative;
         if (NAME_OPAQUE_TAGS.has(el.tagName))
             return '';
         const content = childrenNameOf(el, walk);
@@ -449,7 +542,7 @@ export const readSemanticsFunction = (element, options) => {
      * `.next::after { content: " \2192" }` is the button "Go →".
      */
     const childrenNameOf = (el, walk) => {
-        let out = walk.generated ? beforeContentOf(el) : '';
+        let out = walk.accessible ? beforeContentOf(el) : '';
         for (const child of contentChildrenOf(el)) {
             if (child.nodeType === 3) {
                 out += child.nodeValue ?? '';
@@ -462,7 +555,7 @@ export const readSemanticsFunction = (element, options) => {
             const block = child.tagName === 'BR' || (style?.display ?? 'inline') !== 'inline';
             out += block ? ` ${token} ` : token;
         }
-        return walk.generated ? out + afterContentOf(el) : out;
+        return walk.accessible ? out + afterContentOf(el) : out;
     };
     /**
      * The nodes a name from content reads under an element, in the order the
@@ -496,15 +589,17 @@ export const readSemanticsFunction = (element, options) => {
      * its descendants' contributions, hidden and aria-hidden subtrees dropped (a
      * required-field marker, a decorative glyph), whitespace collapsed. The
      * element's own attributes are `accessibleName`'s business; this reads what
-     * is inside it. `generated` reads CSS generated content too, as an
-     * accessible name does and label text does not.
+     * is inside it. `accessible` reads CSS generated content and embedded
+     * controls' values too, as an accessible name does and label text does not.
+     * `named` is the element the text names when that is not `el` (a control
+     * read through its `<label>`), which never contributes to its own name.
      */
-    const nameTextOf = (el, generated) => {
+    const nameTextOf = (el, accessible, named = el) => {
         if (isNameHidden(el, styleOf(el)))
             return '';
         if (NAME_OPAQUE_TAGS.has(el.tagName))
             return '';
-        return childrenNameOf(el, nameWalk([el], generated)).replace(/\s+/g, ' ').trim();
+        return childrenNameOf(el, nameWalk([el, named], accessible)).replace(/\s+/g, ' ').trim();
     };
     const NAME_OPAQUE_TAGS = new Set(['TEXTAREA', 'SELECT', 'INPUT', 'SCRIPT', 'STYLE']);
     /**
@@ -558,8 +653,14 @@ export const readSemanticsFunction = (element, options) => {
         const shown = labels.map(withoutGlyphs).filter((label) => label !== '');
         return shown.length === 0 ? null : shown;
     };
-    /** Text owned directly by an element, excluding descendant elements. */
+    /**
+     * Text owned directly by an element, excluding descendant elements. An
+     * element with `content-visibility: hidden` renders none of it, as its
+     * `innerText` reads empty, so it owns none.
+     */
     const directTextOf = memoized((el) => {
+        if (styleOf(el)?.getPropertyValue('content-visibility') === 'hidden')
+            return '';
         let out = '';
         for (const child of Array.from(el.childNodes)) {
             if (child.nodeType === 3)
@@ -578,15 +679,15 @@ export const readSemanticsFunction = (element, options) => {
         const labels = associatedLabels(el);
         if (labels.length > 0) {
             const joined = labels
-                .map((label) => nameTextOf(label, true))
+                .map((label) => nameTextOf(label, true, el))
                 .join(' ')
                 .trim();
             if (joined !== '')
                 return joined;
         }
-        const alt = altOf(el);
-        if (alt !== null)
-            return alt;
+        const alternative = altOf(el) ?? (isPresentational(el) ? null : svgTitleOf(el));
+        if (alternative !== null)
+            return alternative;
         const captionTag = NAMING_CHILD_TAGS[el.tagName.toLowerCase()];
         if (captionTag !== undefined) {
             const caption = Array.from(el.children).find((child) => child.tagName.toLowerCase() === captionTag);
@@ -732,25 +833,42 @@ export const readSemanticsFunction = (element, options) => {
         return false;
     };
     /**
-     * The visibility Playwright's `toBeHidden` reads, so a semantic `hidden`
-     * state and the platform's own filter agree: `aria-hidden` on the element,
+     * True when an ancestor in the flat tree has `content-visibility: hidden`:
+     * it keeps its own box and skips rendering everything under it, slotted
+     * and shadow content included, as `checkVisibility()` reads it. Memoized,
+     * so siblings under one ancestor share the walk up.
+     */
+    const isSkippedContent = memoized((el) => {
+        const parent = el.assignedSlot ?? parentOrHostOf(el);
+        if (parent === null)
+            return false;
+        return styleOf(parent)?.getPropertyValue('content-visibility') === 'hidden' || isSkippedContent(parent);
+    });
+    /**
+     * Render visibility, the one Playwright's `toBeVisible` and `toBeHidden`
+     * read, so a semantic `hidden` state and the platform's own filter agree:
      * `display: none` or a `visibility` other than `visible` on any element (an
-     * SVG included), content a closed `<details>` folds away, and a box with no
-     * width or no height. `display: contents` generates no box of its own while
-     * every child still paints (Shopify's one-page checkout form is one), so
-     * such an element is shown when some child element or text is, and hidden
-     * when nothing under it is.
+     * SVG included), content a `content-visibility: hidden` ancestor skips or a
+     * closed `<details>` folds away, and a box with no width or no height.
+     * `aria-hidden` is not in it: it removes a node from the accessibility tree
+     * (`hidesSubtree`, a role query) while the node still paints, as a spinner
+     * marked decorative does. `display: contents` generates no box of its own
+     * while every child still paints (Shopify's one-page checkout form is one),
+     * so such an element is shown when some child element or text is, and
+     * hidden when nothing under it is. Its text paints in its own `visibility`,
+     * which a range's box does not reflect, so text under a hidden one is
+     * hidden, where Playwright calls it visible.
      */
     const isHidden = (el, style = styleOf(el)) => {
-        if (el.getAttribute('aria-hidden') === 'true')
-            return true;
         if (style === undefined)
             return true;
+        if (isSkippedContent(el))
+            return true;
         if (style.display === 'contents') {
             for (let child = el.firstChild; child !== null; child = child.nextSibling) {
                 if (child instanceof Element && !isHidden(child))
                     return false;
-                if (child.nodeType === Node.TEXT_NODE && isVisibleText(child))
+                if (child.nodeType === Node.TEXT_NODE && style.visibility === 'visible' && isVisibleText(child))
                     return false;
             }
             return true;
@@ -763,18 +881,20 @@ export const readSemanticsFunction = (element, options) => {
         return !(rect.width > 0 && rect.height > 0);
     };
     /**
-     * The part of `isHidden` that holds for everything under the element too,
-     * which is what lets the tree walk stop there. A box with no size is not in
-     * it: a zero-height `<html>` or wrapper still shows the fixed, absolute, and
-     * overflowing descendants laid out past its edges, so the walk goes on
-     * through it and only the element itself stays unlisted. An inert element
-     * is in it too (`isInert`).
+     * What takes the element and everything under it out of the tree walk: an
+     * `aria-hidden` or inert subtree, which the accessibility tree drops though
+     * it may paint (`isInert`), and `display: none` or a closed `<details>`
+     * body, which no descendant can undo. A `visibility` other than `visible`
+     * is not in it, since a descendant may set `visibility: visible` and paint
+     * again; nor is a box with no size: a zero-height `<html>` or wrapper still
+     * shows the fixed, absolute, and overflowing descendants laid out past its
+     * edges. The walk goes on through both and only the element itself stays
+     * unlisted.
      */
     const hidesSubtree = (el, style) => el.getAttribute('aria-hidden') === 'true' ||
         isInert(el, style) ||
         style === undefined ||
         style.display === 'none' ||
-        (style.display !== 'contents' && style.visibility !== 'visible') ||
         isInClosedDetails(el);
     /**
      * Inert content takes no input and is hidden from assistive technology, as
@@ -1014,9 +1134,13 @@ export const readSemanticsFunction = (element, options) => {
         let checked = null;
         let selectedState = null;
         if (el instanceof HTMLInputElement) {
-            if (el.type === 'checkbox' || el.type === 'radio')
+            // A checkbox or radio submits its value attribute (`on` by default)
+            // whatever its checked state, so a locator read reports both; the tree
+            // drops that token as it drops an option's.
+            const checkable = el.type === 'checkbox' || el.type === 'radio';
+            if (checkable)
                 checked = el.checked;
-            else
+            if (!checkable || projection.checkableValue)
                 value = el.value;
         }
         else if (el instanceof HTMLTextAreaElement) {
@@ -1114,7 +1238,10 @@ export const readSemanticsFunction = (element, options) => {
         const isDocumentRoot = projection.documentRoot && tag === 'html';
         if (isDocumentRoot)
             name = el.ownerDocument.title;
-        const rect = el.getBoundingClientRect();
+        // No layout box at all (`display: none`, an empty `display: contents`) is
+        // no rect, as Playwright's `boundingBox()` answers null; a box with no
+        // size, or one `visibility: hidden` keeps, is still a rect.
+        const rect = el.getClientRects().length === 0 ? null : el.getBoundingClientRect();
         const role = isDocumentRoot ? 'document' : roleOf(el, tag);
         let level = null;
         if (role === 'heading') {
@@ -1148,13 +1275,15 @@ export const readSemanticsFunction = (element, options) => {
             level,
             attributes,
             testId: el.getAttribute(options.testIdAttribute),
-            rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+            rect: rect === null ? null : { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
         };
     };
     // The conditional return type resolves per call site; inside the body the
-    // discriminant narrows the value but not the generic, hence the two casts.
+    // discriminant narrows the value but not the generic, hence the casts.
+    if (options.mode.kind === 'hidden')
+        return isHidden(element);
     if (options.mode.kind === 'node') {
-        return (element.isConnected ? describe(element) : { detached: true, value: describe(element).value });
+        return describe(element);
     }
     const maxNodes = options.mode.maxNodes;
     const nodes = [];
@@ -1187,8 +1316,7 @@ export const readSemanticsFunction = (element, options) => {
     const isInteresting = (el) => {
         if (el.hasAttribute(options.testIdAttribute))
             return true;
-        const role = implicitRole(el);
-        if (role !== null && role !== 'presentation' && role !== 'none')
+        if (implicitRole(el) !== null && !isPresentational(el))
             return true;
         if (accessibleName(el) !== null)
             return true;
@@ -1261,6 +1389,9 @@ export const readSemanticsFunction = (element, options) => {
         }
         if (OPAQUE_TAGS.indexOf(tag) !== -1)
             return;
+        // The element keeps its box, and nothing under it renders (`isSkippedContent`).
+        if (style?.getPropertyValue('content-visibility') === 'hidden')
+            return;
         for (const child of Array.from(el.children))
             walk(child, nextParent);
         // A shadow root is part of what the user sees, so it is part of what the
@@ -1284,4 +1415,3 @@ export const readSemanticsFunction = (element, options) => {
         walk(child, 0);
     return { nodes, elements, ids, truncated };
 };
-//# sourceMappingURL=read-semantics.js.map

package/dist/index.d.ts

@@ -8,10 +8,11 @@ import type { Browser } from './browser.ts';
 export { web, surfaceOf } from './engine.ts';
 export type { PlaywrightLiveSurface } from './engine.ts';
 export type { WebBasicAuth, WebConnectOptions, WebOptions, WebScreencastOptions } from './surface.ts';
+export type { WebInitScript } from './init-scripts.ts';
 export type { BrowserDownloadContext, BrowserLease, BrowserProvider, BrowserProviderDownloads, BrowserProviderScope, BrowserReleaseContext, BrowserRequest, } from './provider.ts';
 export type { BrowserName } from './browser-connection.ts';
 export type { Dialog, DialogHandler } from './dialogs.ts';
-export type { Browser, BrowserExpectation, Cookie, CookieFields, FrameScreen, RouteFulfillResponse, WebResponse, WebRoute, } from './browser.ts';
+export type { Browser, BrowserExpectation, Cookie, CookieFields, FrameScreen, RouteContinueOverrides, RouteFulfillResponse, WebResponse, WebRoute, } from './browser.ts';
 /**
  * `test` typed with this engine's contributed `browser` fixture. The same
  * runtime `test` as `e2e`'s; only the fixture types differ.
@@ -28,4 +29,3 @@ export declare const describe: {
 }>) => void, afterEach: (fn: import("e2e").TestHookFn<import("e2e").TestFixtures & {
     browser: Browser;
 }>) => void, beforeAll: (fn: import("e2e").SuiteHookFn) => void, afterAll: (fn: import("e2e").SuiteHookFn) => void;
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -13,4 +13,3 @@ export { web, surfaceOf } from './engine.js';
 export const test = base.extend();
 /** `describe` and the hooks, the same functions as `test.describe` and `test.beforeEach`, typed with the `browser` fixture. */
 export const { describe, beforeEach, afterEach, beforeAll, afterAll } = test;
-//# sourceMappingURL=index.js.map

package/dist/init-scripts.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One init script: a string of JavaScript source, a `{ path }` to a file of
+ * it relative to the project root, or a function serialized into the page,
+ * which can close over nothing from the test process.
+ */
+export type WebInitScript = string | {
+    readonly path: string;
+} | (() => unknown);
+/** Refuses, at config load, a `web({ initScripts })` value that is not a list of scripts. */
+export declare function validateInitScripts(scripts: unknown): void;
+/** The configured `initScripts`, read into page source once per process and handed to each attempt as the start of its own list. */
+export declare class ConfiguredInitScripts {
+    private readonly scripts;
+    private sources;
+    constructor(scripts: readonly WebInitScript[]);
+    /** Reads every script, a `path` against the project root; a file that cannot be read is `INVALID_CONFIG`. */
+    load(projectRoot: string): Promise<void>;
+    /** A new attempt's init scripts: the configured ones, to which `browser.addInitScript` appends. */
+    forAttempt(): string[];
+}
+/**
+ * Validates one script `browser.addInitScript` was given and reads it into
+ * page source, a `path` through `resolvePath`. Only a function takes an
+ * argument, as in Playwright.
+ */
+export declare function testInitScriptSource(script: unknown, argument: {
+    readonly arg: unknown;
+} | undefined, resolvePath: (file: string) => string): Promise<string>;
+/** The step label of a script: the file a `path` names, else its kind, never its source. */
+export declare function initScriptLabel(script: unknown): string;

package/dist/init-scripts.js

@@ -0,0 +1,105 @@
+/**
+ * Init scripts: test code every document of an attempt runs after it is
+ * created and before any of its own scripts, in every tab and frame, as
+ * Playwright's `addInitScript` runs it. The configured ones apply to every
+ * attempt; `browser.addInitScript` adds more for one attempt.
+ */
+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 { message } from './support.js';
+/** Refuses, at config load, a `web({ initScripts })` value that is not a list of scripts. */
+export function validateInitScripts(scripts) {
+    if (!Array.isArray(scripts)) {
+        throw new ConfigurationError('INVALID_CONFIG', 'web({ initScripts }) must be an array of scripts');
+    }
+    // Indexed, not `forEach`, so a hole in a sparse array is refused like `undefined`.
+    for (let index = 0; index < scripts.length; index += 1) {
+        assertInitScript(scripts[index], (problem) => new ConfigurationError('INVALID_CONFIG', `web({ initScripts })[${index}] ${problem}`));
+    }
+}
+/** The configured `initScripts`, read into page source once per process and handed to each attempt as the start of its own list. */
+export class ConfiguredInitScripts {
+    scripts;
+    sources = [];
+    constructor(scripts) {
+        this.scripts = scripts;
+    }
+    /** Reads every script, a `path` against the project root; a file that cannot be read is `INVALID_CONFIG`. */
+    async load(projectRoot) {
+        if (this.scripts.length === 0)
+            return;
+        this.sources = await Promise.all(this.scripts.map(async (script, index) => {
+            try {
+                return await initScriptSource(script, undefined, (file) => path.resolve(projectRoot, file));
+            }
+            catch (cause) {
+                throw new ConfigurationError('INVALID_CONFIG', `web({ initScripts })[${index}] ${message(cause)}`, { cause });
+            }
+        }));
+    }
+    /** A new attempt's init scripts: the configured ones, to which `browser.addInitScript` appends. */
+    forAttempt() {
+        return [...this.sources];
+    }
+}
+/**
+ * Validates one script `browser.addInitScript` was given and reads it into
+ * page source, a `path` through `resolvePath`. Only a function takes an
+ * argument, as in Playwright.
+ */
+export async function testInitScriptSource(script, argument, resolvePath) {
+    assertInitScript(script, (problem) => new TestError('INVALID_ARGUMENT', `browser.addInitScript script ${problem}`));
+    if (argument !== undefined && typeof script !== 'function') {
+        throw new TestError('INVALID_ARGUMENT', 'browser.addInitScript takes an argument only with a function script');
+    }
+    validateJsonValue(argument?.arg, 'addInitScript argument');
+    try {
+        return await initScriptSource(script, argument?.arg, resolvePath);
+    }
+    catch (cause) {
+        throw new TestError('INVALID_ARGUMENT', `browser.addInitScript ${message(cause)}`, { cause });
+    }
+}
+/** The step label of a script: the file a `path` names, else its kind, never its source. */
+export function initScriptLabel(script) {
+    if (typeof script === 'object' && script !== null && 'path' in script)
+        return String(script.path);
+    return typeof script === 'function' ? 'function' : 'source';
+}
+/** Throws what `fail` makes of the problem unless `script` is one init script. */
+function assertInitScript(script, fail) {
+    if (typeof script === 'string' || typeof script === 'function')
+        return;
+    if (typeof script !== 'object' || script === null || Array.isArray(script)) {
+        const got = script === null ? 'null' : Array.isArray(script) ? 'an array' : typeof script;
+        throw fail(`must be a string of source, a { path }, or a function, got ${got}`);
+    }
+    const unknown = Object.keys(script).filter((key) => key !== 'path');
+    if (unknown.length > 0)
+        throw fail(`takes only path, got ${unknown.join(', ')}`);
+    if (!('path' in script) || typeof script.path !== 'string' || script.path === '')
+        throw fail('path must be a non-empty string');
+}
+/**
+ * The page source of one script. A function is called with its JSON argument
+ * as Playwright calls it, beside the `__name` helper tsx's output needs; the
+ * argument is parsed in the page, since an object literal would turn an own
+ * `__proto__` key into the prototype. A
+ * file gets a `sourceURL`, so a stack trace in the page names it.
+ */
+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})();`;
+    }
+    const file = resolvePath(script.path);
+    try {
+        return `${await readFile(file, 'utf8')}\n//# sourceURL=${file.replace(/[\r\n]/g, '')}`;
+    }
+    catch (cause) {
+        throw new Error(`path cannot be read: ${file} (${cause.code ?? message(cause)})`, { cause });
+    }
+}

package/dist/install.d.ts

@@ -1,5 +1,12 @@
 /** First-run browser provisioning for the Playwright engine. */
 import { type BrowserName } from './browser-connection.ts';
+/**
+ * Runs the pinned Playwright CLI with `args`, sharing this process's terminal,
+ * and resolves to its exit code, 128 plus the signal number when a signal
+ * ended it. SIGINT and SIGTERM sent to this process reach the child, so a
+ * cancelled CI job does not leave a download running. Backs the `e2e-web` command.
+ */
+export declare function runPlaywrightCli(args: readonly string[]): Promise<number>;
 /** What an installer receives besides the browser names. */
 export interface InstallContext {
     /** Receives every line the installer prints: the download URL, progress, warnings. */
@@ -30,11 +37,10 @@ export interface EnsureBrowsersOptions {
 }
 /**
  * Ensures the given Playwright browsers are installed, downloading any
- * missing ones via `playwright install`. Called from the engine's `prepare`,
+ * missing ones via `playwright-core install`. Called from the engine's `prepare`,
  * once per run before any worker starts, so a download is never charged
  * against a launch timeout and never runs once per worker. Concurrent
  * installs (two runs at once) are still safe: the Playwright CLI serializes
  * them with a registry lock.
  */
 export declare function ensureBrowsersInstalled(names: readonly BrowserName[], options?: EnsureBrowsersOptions): Promise<void>;
-//# sourceMappingURL=install.d.ts.map