@itmetsam/samurai-framework 0.21.3 → 0.21.4

package/dist/assert/value-matchers.js

@@ -0,0 +1,53 @@
+import { format } from "./assertion-error.js";
+/** Calls `fn` and says whether it threw */
+export function callAndCatch(fn) {
+    try {
+        fn();
+        return { threw: false };
+    }
+    catch (error) {
+        return { threw: true, error };
+    }
+}
+function messageOf(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "object" && error !== null && "message" in error)
+        return String(error.message);
+    return String(error);
+}
+/** Whether what was thrown fits `expected`; with no expectation, throwing at all fits */
+export function thrownMatches(outcome, expected) {
+    if (!outcome.threw)
+        return false;
+    if (expected === undefined)
+        return true;
+    if (typeof expected === "string")
+        return messageOf(outcome.error).includes(expected);
+    if (expected instanceof RegExp)
+        return messageOf(outcome.error).search(expected) !== -1;
+    if (expected instanceof Error)
+        return messageOf(outcome.error) === expected.message;
+    return outcome.error instanceof expected;
+}
+/** What a `toThrow` failure shows as the received value */
+export function describeOutcome(outcome) {
+    return outcome.threw ? `threw ${format(outcome.error)}` : "did not throw";
+}
+/** Jest's rule: the difference is under half a unit of the last digit asked for */
+export function isCloseTo(actual, expected, digits) {
+    if (actual === expected)
+        return true;
+    return Math.abs(expected - actual) < Math.pow(10, -digits) / 2;
+}
+/** The `length` of a string, array or array-like; undefined for anything else */
+export function lengthOf(value) {
+    if (typeof value === "string")
+        return value.length;
+    if (typeof value === "object" && value !== null && "length" in value) {
+        const length = value.length;
+        if (typeof length === "number")
+            return length;
+    }
+    return undefined;
+}

package/dist/browser/navigation-error.d.ts

@@ -9,5 +9,9 @@ export declare class NavigationError extends Error {
 }
 /** The page did not reach the awaited load state in time */
 export declare class LoadStateTimeoutError extends WaitTimeoutError<undefined> {
-    constructor(state: string, timeout: number);
+    constructor(state: string, timeout: number, operation?: string);
+}
+/** The page's URL did not match in time */
+export declare class UrlTimeoutError extends WaitTimeoutError<string> {
+    constructor(expected: string, timeout: number, lastUrl: string | undefined);
 }

package/dist/browser/navigation-error.js

@@ -11,9 +11,17 @@ export class NavigationError extends Error {
 }
 /** The page did not reach the awaited load state in time */
 export class LoadStateTimeoutError extends WaitTimeoutError {
-    constructor(state, timeout) {
+    constructor(state, timeout, operation = "waitForLoadState") {
         super(timeout, undefined);
         this.name = "LoadStateTimeoutError";
-        this.message = `waitForLoadState("${state}") did not finish within ${timeout}ms`;
+        this.message = `${operation}("${state}") did not finish within ${timeout}ms`;
+    }
+}
+/** The page's URL did not match in time */
+export class UrlTimeoutError extends WaitTimeoutError {
+    constructor(expected, timeout, lastUrl) {
+        super(timeout, lastUrl);
+        this.name = "UrlTimeoutError";
+        this.message = `waitForURL(): the URL did not match ${expected} within ${timeout}ms (last URL: ${lastUrl ?? "unknown"})`;
     }
 }

package/dist/browser/page-content.d.ts

@@ -0,0 +1,5 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/** The page's markup now, with its doctype */
+export declare function readContent(connector: BiDiConnector, context: string): Promise<string>;
+/** Writes `html` as the page's document; true when the document reached `state` within `timeout` ms */
+export declare function writeContent(connector: BiDiConnector, context: string, html: string, state: "load" | "domcontentloaded", timeout: number): Promise<boolean>;

package/dist/browser/page-content.js

@@ -0,0 +1,43 @@
+import { callFunction } from "../script/call-function.js";
+/** The document as markup: the doctype (when there is one) followed by the document element */
+const READ_CONTENT = `() => {
+  const type = document.doctype;
+  const doctype = type
+    ? "<!DOCTYPE " + type.name +
+      (type.publicId ? ' PUBLIC "' + type.publicId + '"' : "") +
+      (!type.publicId && type.systemId ? " SYSTEM" : "") +
+      (type.systemId ? ' "' + type.systemId + '"' : "") + ">"
+    : "";
+  return doctype + document.documentElement.outerHTML;
+}`;
+/**
+ * Replaces the document in place with `document.open()`, `write()` and `close()`: scripts and styles in `html` run and
+ * apply, and the page keeps its URL and origin. The listeners are added after `open()` because it removes the old ones.
+ * Resolves true once the `load` (or `DOMContentLoaded`) event fired, false when `timeout` ms passed first.
+ */
+const WRITE_CONTENT = `async (html, state, timeout) => {
+  document.open();
+  const reached = new Promise((resolve) => {
+    const done = () => resolve(true);
+    if (state === "domcontentloaded") document.addEventListener("DOMContentLoaded", done, { once: true });
+    else window.addEventListener("load", done, { once: true });
+    setTimeout(() => resolve(false), timeout);
+  });
+  document.write(html);
+  document.close();
+  return reached;
+}`;
+/** The page's markup now, with its doctype */
+export function readContent(connector, context) {
+    return callFunction(connector, context, READ_CONTENT, [], {
+        awaitPromise: false,
+    });
+}
+/** Writes `html` as the page's document; true when the document reached `state` within `timeout` ms */
+export function writeContent(connector, context, html, state, timeout) {
+    return callFunction(connector, context, WRITE_CONTENT, [
+        html,
+        state,
+        timeout,
+    ]);
+}

package/dist/browser/page-evaluate.d.ts

@@ -0,0 +1,9 @@
+import { type PageFunction } from "../script/call-function.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/** Whether a string is the source of a function (called with the argument) rather than an expression (evaluated) */
+export declare function isFunctionSource(source: string): boolean;
+/**
+ * Runs a function, or a string, in the page and returns the result as plain JavaScript (see `fromRemoteValue`).
+ * A function (or a string holding a function's source) is called with `arg`; any other string is an expression.
+ */
+export declare function evaluateInPage<R, A>(connector: BiDiConnector, context: string, fn: PageFunction<[A], R>, arg?: A): Promise<R>;

package/dist/browser/page-evaluate.js

@@ -0,0 +1,20 @@
+import { callFunction, evaluateExpression, } from "../script/call-function.js";
+/** A function (or arrow function, async or not) written out as source, as opposed to an expression */
+const FUNCTION_SOURCE = /^\s*(?:async\s+)?(?:function\b|(?:\((?:[^()]|\([^()]*\))*\)|[\w$]+)\s*=>)/;
+/** Whether a string is the source of a function (called with the argument) rather than an expression (evaluated) */
+export function isFunctionSource(source) {
+    return FUNCTION_SOURCE.test(source);
+}
+/**
+ * Runs a function, or a string, in the page and returns the result as plain JavaScript (see `fromRemoteValue`).
+ * A function (or a string holding a function's source) is called with `arg`; any other string is an expression.
+ */
+export async function evaluateInPage(connector, context, fn, arg) {
+    if (typeof fn === "string" && !isFunctionSource(fn)) {
+        if (arg !== undefined) {
+            throw new TypeError("evaluate(): an expression takes no argument; pass a function to use one");
+        }
+        return evaluateExpression(connector, context, fn);
+    }
+    return callFunction(connector, context, fn, arg === undefined ? [] : [arg]);
+}

package/dist/browser/page-locators.d.ts

@@ -13,6 +13,6 @@ export declare class PageLocators {
     private strictOverride;
     constructor(biDiConnector: BiDiConnector, id: BrowsingContext, helperRealm: HelperRealm, pageConfig: PageConfig, assertOpen: () => void);
     locate(selector: ConstructorParameters<typeof Locator>[0]): Locator;
-    /** `undefined` goes back to config `use.strictSelectors`; applies to locators already made, too */
+    /** `undefined` goes back to config `use.strictSelectors`; a locator asks once, at its first action or read, so earlier ones that already ran keep their answer */
     setStrictSelectors(enabled: boolean | undefined): void;
 }

package/dist/browser/page-locators.js

@@ -12,7 +12,7 @@ export class PageLocators {
         this.assertOpen();
         return new Locator(selector, this.biDiConnector, this.id, this.helperRealm, [], () => this.pageConfig.strictSelectors(this.strictOverride));
     }
-    /** `undefined` goes back to config `use.strictSelectors`; applies to locators already made, too */
+    /** `undefined` goes back to config `use.strictSelectors`; a locator asks once, at its first action or read, so earlier ones that already ran keep their answer */
     setStrictSelectors(enabled) {
         this.strictOverride = enabled;
     }

package/dist/browser/page-navigation.d.ts

@@ -1,4 +1,5 @@
 import type { BiDiConnector } from "../transport/bidi-connection.js";
+import { type UrlPattern } from "../network/url-match.js";
 import type { DocumentWatcher } from "./document-watcher.js";
 import type { PageConfig, ReadinessState } from "./page-settings.js";
 export type LoadState = "load" | "domcontentloaded" | "networkidle";
@@ -54,6 +55,23 @@ export declare class PageNavigation {
     waitForLoadState(state?: LoadState, options?: {
         timeout?: number;
     }): Promise<void>;
+    /**
+     * Waits until the page's URL matches `url` (a string equals it, or with `*` / `**` is a glob; a RegExp is tested on it;
+     * a function gets it as a `URL`), then waits for `waitUntil` (default "load"). A string starting with "/", "./" or
+     * "../" resolves against the base URL, as in `goto`. `timeout` applies to the URL, then again to the load state.
+     */
+    waitForURL(url: UrlPattern | ((url: URL) => boolean), options?: {
+        timeout?: number;
+        waitUntil?: LoadState;
+    }): Promise<void>;
+    /**
+     * Replaces the document with `html` (see `writeContent`) and waits for `waitUntil` (default "load"); "networkidle" is
+     * "load" plus a quiet network. The page keeps its URL.
+     */
+    setContent(html: string, options?: {
+        timeout?: number;
+        waitUntil?: LoadState;
+    }): Promise<void>;
     /**
      * Runs a navigation command and settles what waiting for it means: failures become NavigationErrors, and a
      * navigation that did not wait for the load is watched so `waitForLoadState` can tell it from the old page.

package/dist/browser/page-navigation.js

@@ -1,8 +1,11 @@
+import logger from "../logger/index.js";
 import { peekRunSettings } from "../config/run-settings.js";
 import { BiDiError } from "../transport/bidi-error.js";
 import { UnsupportedOperationError } from "../transport/unsupported.js";
-import { WaitTimeoutError } from "../wait/wait-until.js";
-import { LoadStateTimeoutError, NavigationError } from "./navigation-error.js";
+import { matchUrl } from "../network/url-match.js";
+import { waitUntil, WaitTimeoutError } from "../wait/wait-until.js";
+import { LoadStateTimeoutError, NavigationError, UrlTimeoutError, } from "./navigation-error.js";
+import { writeContent } from "./page-content.js";
 /** A URL starting with "/", "./" or "../" */
 const RELATIVE_URL = /^\.{0,2}\//;
 /** Resolves a slash-led `url` against `base`; any other URL is returned as given */
@@ -88,6 +91,53 @@ export class PageNavigation {
         if (state === "networkidle")
             await this.deps.waitForNetworkIdle({ timeout });
     }
+    /**
+     * Waits until the page's URL matches `url` (a string equals it, or with `*` / `**` is a glob; a RegExp is tested on it;
+     * a function gets it as a `URL`), then waits for `waitUntil` (default "load"). A string starting with "/", "./" or
+     * "../" resolves against the base URL, as in `goto`. `timeout` applies to the URL, then again to the load state.
+     */
+    async waitForURL(url, options = {}) {
+        this.deps.assertOpen();
+        const timeout = await this.deps.config.navigationTimeout(options.timeout);
+        const pattern = typeof url === "string" ? this.resolveURL(url, "waitForURL") : url;
+        const matches = typeof pattern === "function"
+            ? (current) => pattern(new URL(current))
+            : (current) => matchUrl(pattern, current);
+        // A read that fails while the page navigates counts as no URL yet
+        const read = () => this.deps.url().catch((err) => {
+            this.deps.assertOpen();
+            logger.debug("waitForURL could not read the URL", { err });
+            return undefined;
+        });
+        try {
+            await waitUntil(read, (current) => current !== undefined && matches(current), { timeout });
+        }
+        catch (err) {
+            if (!(err instanceof WaitTimeoutError))
+                throw err;
+            const wanted = typeof pattern === "function"
+                ? "the predicate"
+                : typeof pattern === "string"
+                    ? `"${pattern}"`
+                    : String(pattern);
+            throw new UrlTimeoutError(wanted, timeout, err.last);
+        }
+        await this.waitForLoadState(options.waitUntil, { timeout });
+    }
+    /**
+     * Replaces the document with `html` (see `writeContent`) and waits for `waitUntil` (default "load"); "networkidle" is
+     * "load" plus a quiet network. The page keeps its URL.
+     */
+    async setContent(html, options = {}) {
+        this.deps.assertOpen();
+        const timeout = await this.deps.config.navigationTimeout(options.timeout);
+        const state = options.waitUntil ?? "load";
+        const reached = await writeContent(this.connector, this.contextId, html, state === "domcontentloaded" ? "domcontentloaded" : "load", timeout);
+        if (!reached)
+            throw new LoadStateTimeoutError(state, timeout, "setContent");
+        if (state === "networkidle")
+            await this.deps.waitForNetworkIdle({ timeout });
+    }
     /**
      * Runs a navigation command and settles what waiting for it means: failures become NavigationErrors, and a
      * navigation that did not wait for the load is watched so `waitForLoadState` can tell it from the old page.

package/dist/browser/page.d.ts

@@ -25,6 +25,7 @@ export type { PageSettings, ReadinessState };
 import { type Viewport } from "./viewport.js";
 import type { PreloadHandle } from "../script/preload.js";
 import type { BiDiConnector } from "../transport/bidi-connection.js";
+import { type PageFunction } from "../script/call-function.js";
 import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
 export type { LoadState, NavigateOptions, NavigationResult };
 export default class Page {
@@ -46,6 +47,7 @@ export default class Page {
     private browserContext;
     private transfers;
     private evidence;
+    private knownViewport;
     /** `settings` override what `samurai.config.ts` says; without them the config is read when needed */
     constructor(biDiConnector: BiDiConnector, contextId: string, settings?: PageSettings);
     /** The BiDi browsing context id of this page's top-level context */
@@ -61,7 +63,8 @@ export default class Page {
     /**
      * Makes this page's locators strict (or not): an action or read on a locator matching several elements then
      * throws `name(): strict mode violation, N elements match ...` instead of using the first. `undefined` goes back
-     * to config `use.strictSelectors` (off unless set). Applies to locators already made, too
+     * to config `use.strictSelectors` (off unless set). Applies to locators made afterwards and to earlier ones that have not
+     * run an action or read yet: a locator keeps the answer it got at its first one
      */
     setStrictSelectors(enabled: boolean | undefined): void;
     /** Locates elements with a CSS selector */
@@ -133,14 +136,58 @@ export default class Page {
     goForward(): Promise<boolean>;
     /** The URL of the page now */
     url(): Promise<string>;
+    /**
+     * Waits until the URL matches `url` (a string equals it, or with `*` / `**` is a glob; a RegExp is tested on it;
+     * a function gets it as a `URL`), then until the page reached `waitUntil` (default "load"). Also sees `pushState`.
+     * @example
+     *  await page.getByRole("button", { name: "Sign in" }).click();
+     *  await page.waitForURL("**\/dashboard");
+     */
+    waitForURL(url: UrlPattern | ((url: URL) => boolean), options?: {
+        timeout?: number;
+        waitUntil?: LoadState;
+    }): Promise<void>;
+    /** The markup of the document now, doctype included */
+    content(): Promise<string>;
+    /**
+     * Replaces the document with `html` and waits for `waitUntil` (default "load"). Scripts and styles in it run and apply;
+     * the page keeps its URL and origin (it is not a `data:` page).
+     * @example
+     *  await page.setContent("<button>Go</button><script>document.title = 'x'</script>");
+     */
+    setContent(html: string, options?: {
+        timeout?: number;
+        waitUntil?: LoadState;
+    }): Promise<void>;
     /** The title of the document now */
     title(): Promise<string>;
+    /**
+     * Runs `fn` in the page, with `arg` as its only argument, and returns the result (a promise is awaited). `fn` is a function,
+     * the source of one (`"async () => ..."`), or any other string, which is an expression (`"document.title"`; it takes no argument).
+     * Values come back as plain JavaScript: Date, Map, Set, RegExp, BigInt, NaN, undefined, nested objects and arrays;
+     * an element as an `ElementHandle`; what cannot be copied (a function, window, error, promise) as a `RemoteObject` with its `type`.
+     * The page's own error message is kept (`ScriptError`). A function written under tsx must not contain named inner functions
+     * (the transpiler adds a `__name` helper the page lacks); a string always works.
+     * @example
+     *  const count = await page.evaluate((min) => document.querySelectorAll("li").length > min, 3);
+     */
+    evaluate<R = unknown, A = unknown>(fn: PageFunction<[A], R>, arg?: A): Promise<R>;
     /**
      * Sets the size of the viewport (and, optionally, the device pixel ratio); `null` puts the browser's own size back.
      * @example
      *  await page.setViewport({ width: 390, height: 844, devicePixelRatio: 3 });
      */
     setViewport(viewport: Viewport | null): Promise<void>;
+    /** Playwright's name for `setViewport` */
+    setViewportSize(size: Viewport): Promise<void>;
+    /**
+     * The size this page was last given (`setViewport`, `setViewportSize`, or the default from config `use.viewport` when the
+     * browser opened it), read at once; null before one is known, after `setViewport(null)` and when config turns the viewport off.
+     */
+    viewportSize(): {
+        width: number;
+        height: number;
+    } | null;
     /** Gives the page the size from config `use.viewport` (1280x720 by default); the browser does this when it opens a page */
     applyDefaultViewport(): Promise<void>;
     /**

package/dist/browser/page.js

@@ -28,6 +28,8 @@ import { applyViewport } from "./viewport.js";
 import { HelperRealm } from "../locator/helper-realm.js";
 import { BiDiError } from "../transport/bidi-error.js";
 import { callFunction } from "../script/call-function.js";
+import { readContent } from "./page-content.js";
+import { evaluateInPage } from "./page-evaluate.js";
 export default class Page {
     /** `settings` override what `samurai.config.ts` says; without them the config is read when needed */
     constructor(biDiConnector, contextId, settings) {
@@ -37,6 +39,7 @@ export default class Page {
         this.lazyLogs = new Lazy();
         this.errorsAllowed = false;
         this.isClosed = false;
+        this.knownViewport = null;
         this.biDiConnector = biDiConnector;
         this.id = contextId;
         this.pageConfig = new PageConfig(settings);
@@ -84,7 +87,8 @@ export default class Page {
     /**
      * Makes this page's locators strict (or not): an action or read on a locator matching several elements then
      * throws `name(): strict mode violation, N elements match ...` instead of using the first. `undefined` goes back
-     * to config `use.strictSelectors` (off unless set). Applies to locators already made, too
+     * to config `use.strictSelectors` (off unless set). Applies to locators made afterwards and to earlier ones that have not
+     * run an action or read yet: a locator keeps the answer it got at its first one
      */
     setStrictSelectors(enabled) {
         this.locators.setStrictSelectors(enabled);
@@ -220,11 +224,49 @@ export default class Page {
         this.assertOpen();
         return callFunction(this.biDiConnector, this.id, "() => location.href", [], { awaitPromise: false });
     }
+    /**
+     * Waits until the URL matches `url` (a string equals it, or with `*` / `**` is a glob; a RegExp is tested on it;
+     * a function gets it as a `URL`), then until the page reached `waitUntil` (default "load"). Also sees `pushState`.
+     * @example
+     *  await page.getByRole("button", { name: "Sign in" }).click();
+     *  await page.waitForURL("**\/dashboard");
+     */
+    waitForURL(url, options) {
+        return this.nav.waitForURL(url, options);
+    }
+    /** The markup of the document now, doctype included */
+    async content() {
+        this.assertOpen();
+        return readContent(this.biDiConnector, this.id);
+    }
+    /**
+     * Replaces the document with `html` and waits for `waitUntil` (default "load"). Scripts and styles in it run and apply;
+     * the page keeps its URL and origin (it is not a `data:` page).
+     * @example
+     *  await page.setContent("<button>Go</button><script>document.title = 'x'</script>");
+     */
+    async setContent(html, options) {
+        return this.nav.setContent(html, options);
+    }
     /** The title of the document now */
     async title() {
         this.assertOpen();
         return callFunction(this.biDiConnector, this.id, "() => document.title", [], { awaitPromise: false });
     }
+    /**
+     * Runs `fn` in the page, with `arg` as its only argument, and returns the result (a promise is awaited). `fn` is a function,
+     * the source of one (`"async () => ..."`), or any other string, which is an expression (`"document.title"`; it takes no argument).
+     * Values come back as plain JavaScript: Date, Map, Set, RegExp, BigInt, NaN, undefined, nested objects and arrays;
+     * an element as an `ElementHandle`; what cannot be copied (a function, window, error, promise) as a `RemoteObject` with its `type`.
+     * The page's own error message is kept (`ScriptError`). A function written under tsx must not contain named inner functions
+     * (the transpiler adds a `__name` helper the page lacks); a string always works.
+     * @example
+     *  const count = await page.evaluate((min) => document.querySelectorAll("li").length > min, 3);
+     */
+    async evaluate(fn, arg) {
+        this.assertOpen();
+        return evaluateInPage(this.biDiConnector, this.id, fn, arg);
+    }
     /**
      * Sets the size of the viewport (and, optionally, the device pixel ratio); `null` puts the browser's own size back.
      * @example
@@ -233,6 +275,21 @@ export default class Page {
     async setViewport(viewport) {
         this.assertOpen();
         await applyViewport(this.biDiConnector, this.id, viewport);
+        this.knownViewport = viewport && {
+            width: viewport.width,
+            height: viewport.height,
+        };
+    }
+    /** Playwright's name for `setViewport` */
+    setViewportSize(size) {
+        return this.setViewport(size);
+    }
+    /**
+     * The size this page was last given (`setViewport`, `setViewportSize`, or the default from config `use.viewport` when the
+     * browser opened it), read at once; null before one is known, after `setViewport(null)` and when config turns the viewport off.
+     */
+    viewportSize() {
+        return this.knownViewport && { ...this.knownViewport };
     }
     /** Gives the page the size from config `use.viewport` (1280x720 by default); the browser does this when it opens a page */
     async applyDefaultViewport() {

package/dist/locator/element-access.d.ts

@@ -8,6 +8,8 @@ export interface ElementAccess extends ElementContext {
      * throw instead (`method` is the public method that asked, for the message)
      */
     resolveOne(method?: string): Promise<ElementHandle | null>;
+    /** Every element the locator matches now, in document order; never strict, never waits */
+    resolveAll(): Promise<ElementHandle[]>;
 }
 /** Calls `fn` in the page; a throwing function becomes a "Failed to locate element" error */
 export declare function callInPage<T>(access: Pick<ElementAccess, "connector" | "contextId" | "selector">, fn: string, args: Arg[], sandbox?: string): Promise<T>;

package/dist/locator/element-reads.d.ts

@@ -3,6 +3,23 @@ import { type ActionabilityContext } from "./actionability.js";
 import { type ElementAccess } from "./element-access.js";
 /** Trimmed text content, or null when the element is missing */
 export declare function readTextContent(access: ElementAccess): Promise<string | null>;
+/** Rendered text (what a person would copy: line breaks, no hidden text), untrimmed, or null when the element is missing */
+export declare function readInnerText(access: ElementAccess): Promise<string | null>;
+/** The markup inside the element, or null when the element is missing */
+export declare function readInnerHTML(access: ElementAccess): Promise<string | null>;
+/** `textContent` of every match, as the page has it (untrimmed); an empty array when none match */
+export declare function readAllTextContents(access: ElementAccess): Promise<string[]>;
+/** `innerText` of every match; an empty array when none match */
+export declare function readAllInnerTexts(access: ElementAccess): Promise<string[]>;
+/** The element's box in CSS pixels from the viewport's top left */
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The element's box, or null when it is missing or not rendered (`display: none`, detached): it has no boxes then */
+export declare function readBoundingBox(access: ElementAccess): Promise<BoundingBox | null>;
 /** The accessible name (see `ACCESSIBLE_NAME_JS`), "" when it has none, or null when the element is missing */
 export declare function readAccessibleName(access: ElementAccess): Promise<string | null>;
 /** The accessible description, "" when it has none, or null when the element is missing */

package/dist/locator/element-reads.js

@@ -2,6 +2,7 @@ import { probeState } from "./actionability.js";
 import { callOnElement, callOnExistingElement, } from "./element-access.js";
 import { describeType } from "./element-state.js";
 import { ACCESSIBLE_NAME_JS } from "./accessible-name.js";
+import { evaluateOnAll } from "./evaluate.js";
 /** Body run in the page as `(el) => { ... }`: a checked checkbox or radio input, or `aria-checked="true"` */
 const IS_CHECKED_BODY = `
   const type = (el.getAttribute("type") || "").toLowerCase();
@@ -31,6 +32,36 @@ function stringOrNull(value) {
 export async function readTextContent(access) {
     return stringOrNull(await callOnElement(access, null, `return el.textContent.trim();`, [], [], "textContent"));
 }
+/** Rendered text (what a person would copy: line breaks, no hidden text), untrimmed, or null when the element is missing */
+export async function readInnerText(access) {
+    return stringOrNull(await callOnElement(access, null, `return el.innerText;`, [], [], "innerText"));
+}
+/** The markup inside the element, or null when the element is missing */
+export async function readInnerHTML(access) {
+    return stringOrNull(await callOnElement(access, null, `return el.innerHTML;`, [], [], "innerHTML"));
+}
+/** `textContent` of every match, as the page has it (untrimmed); an empty array when none match */
+export function readAllTextContents(access) {
+    return evaluateOnAll(access, `(els) => els.map((el) => el.textContent ?? "")`, undefined);
+}
+/** `innerText` of every match; an empty array when none match */
+export function readAllInnerTexts(access) {
+    return evaluateOnAll(access, `(els) => els.map((el) => el.innerText ?? "")`, undefined);
+}
+/** The element's box, or null when it is missing or not rendered (`display: none`, detached): it has no boxes then */
+export async function readBoundingBox(access) {
+    const box = await callOnElement(access, null, `
+      if (el.getClientRects().length === 0) return null;
+      const { x, y, width, height } = el.getBoundingClientRect();
+      return { x, y, width, height };
+    `, [], [], "boundingBox");
+    if (box === null)
+        return null;
+    if (typeof box !== "object") {
+        throw new Error(`Expected to receive an object but instead received "${describeType(box)}"`);
+    }
+    return box;
+}
 /** The accessible name (see `ACCESSIBLE_NAME_JS`), "" when it has none, or null when the element is missing */
 export async function readAccessibleName(access) {
     return stringOrNull(await callOnElement(access, null, `${ACCESSIBLE_NAME_JS} return accessibleName(el);`, [], [], "accessibleName"));

package/dist/locator/evaluate.d.ts

@@ -0,0 +1,12 @@
+import { type PageFunction } from "../script/call-function.js";
+import type { ElementAccess } from "./element-access.js";
+/**
+ * Waits until the element is attached (hidden is fine), then calls `fn(element, arg)` in the page.
+ * A missing element ends in the usual timeout error; a strict locator throws when several match.
+ * What the page function throws reaches the caller unchanged (a `ScriptError`).
+ */
+export declare function evaluateOnElement<R, A>(access: ElementAccess, fn: PageFunction<[any, A], R>, arg: A | undefined, options?: {
+    timeout?: number;
+}): Promise<R>;
+/** Calls `fn(elements, arg)` in the page with every element the locator matches now (an empty array when none); does not wait */
+export declare function evaluateOnAll<R, A>(access: ElementAccess, fn: PageFunction<[any[], A], R>, arg: A | undefined): Promise<R>;

package/dist/locator/evaluate.js

@@ -0,0 +1,36 @@
+import { BiDiError } from "../transport/bidi-error.js";
+import { callFunction } from "../script/call-function.js";
+import { ATTACHED_ONLY } from "./page-scripts.js";
+/**
+ * Waits until the element is attached (hidden is fine), then calls `fn(element, arg)` in the page.
+ * A missing element ends in the usual timeout error; a strict locator throws when several match.
+ * What the page function throws reaches the caller unchanged (a `ScriptError`).
+ */
+export async function evaluateOnElement(access, fn, arg, options) {
+    await access.waitForActionable("evaluate", ATTACHED_ONLY, { scroll: false, hitTest: false }, options?.timeout === undefined ? undefined : { timeout: options.timeout });
+    const el = await access.requireElement();
+    try {
+        return await callFunction(access.connector, access.contextId, fn, arg === undefined ? [el] : [el, arg]);
+    }
+    catch (err) {
+        // The element went away between the search and the call
+        if (err instanceof BiDiError && err.code === "no such node")
+            throw access.noElementError();
+        throw err;
+    }
+}
+/** Calls `fn(elements, arg)` in the page with every element the locator matches now (an empty array when none); does not wait */
+export async function evaluateOnAll(access, fn, arg) {
+    // One more search when an element was removed between the search and the call
+    for (let attempt = 1;; attempt++) {
+        const elements = await access.resolveAll();
+        try {
+            return await callFunction(access.connector, access.contextId, fn, arg === undefined ? [elements] : [elements, arg]);
+        }
+        catch (err) {
+            if (attempt === 2 ||
+                !(err instanceof BiDiError && err.code === "no such node"))
+                throw err;
+        }
+    }
+}

package/dist/locator/locator.d.ts

@@ -1,10 +1,12 @@
 import type { BiDiConnector } from "../transport/bidi-connection.js";
 import type { BrowsingContext, ElementRectangle } from "../types/bidi-modules/browsing-context.js";
 import { ElementHandle } from "../script/element-handle.js";
+import type { PageFunction } from "../script/call-function.js";
 import type { ElementScreenshotOptions } from "../browser/screenshot.js";
 import type { FileInput } from "../browser/generated-files.js";
 import { type ActionOptions } from "./actionability.js";
 import { type CheckOptions } from "./check-actions.js";
+import { type BoundingBox } from "./element-reads.js";
 import type { WaitForState } from "./element-state.js";
 import type { HelperInstaller } from "./helper-realm.js";
 import { type StrictSource } from "./strict-mode.js";
@@ -197,6 +199,27 @@ export default class Locator {
     isHidden(): Promise<boolean>;
     /** Trimmed text content, or null when the element is missing */
     textContent(): Promise<string | null>;
+    /** Rendered text of the element (as a person would copy it, hidden text left out), untrimmed, or null when the element is missing */
+    innerText(): Promise<string | null>;
+    /** The markup inside the element, or null when the element is missing */
+    innerHTML(): Promise<string | null>;
+    /** `textContent` of every match, as the page has it (untrimmed, unlike `textContent()`); `[]` when none match. Does not wait */
+    allTextContents(): Promise<string[]>;
+    /** `innerText` of every match; `[]` when none match. Does not wait */
+    allInnerTexts(): Promise<string[]>;
+    /** The element's box in CSS pixels from the viewport's top left, or null when it is missing or not rendered (`display: none`). Does not wait or scroll */
+    boundingBox(): Promise<BoundingBox | null>;
+    /**
+     * Waits until the element is attached (hidden is fine), then calls `fn(element, arg)` in the page and returns the result
+     * (see `page.evaluate` for what comes back). `fn` is a function or the source of one; a strict locator throws when several match.
+     * @example
+     *  const id = await page.getByTestId("row").evaluate((el) => el.dataset.id);
+     */
+    evaluate<R = unknown, A = unknown>(fn: PageFunction<[any, A], R>, arg?: A, options?: {
+        timeout?: number;
+    }): Promise<R>;
+    /** Calls `fn(elements, arg)` in the page with an array of every match (empty when none; does not wait) and returns the result */
+    evaluateAll<R = unknown, A = unknown>(fn: PageFunction<[any[], A], R>, arg?: A): Promise<R>;
     /** Value of an input/textarea/select, or null when missing */
     inputValue(): Promise<string | null>;
     /** Attribute value, or null when the element or attribute is missing */