@itmetsam/samurai-framework 0.21.3 → 0.21.4

package/dist/locator/locator.js

@@ -4,7 +4,8 @@ import { setChecked } from "./check-actions.js";
 import { ChainResolver } from "./chain-resolver.js";
 import { callInPage, noElementError, requireElement, } from "./element-access.js";
 import { clickElement, fillElement, focusElement, pressOnElement, screenshotElement, } from "./element-actions.js";
-import { readAccessibleDescription, readAccessibleName, readAttribute, readBoundingClientRect, readClassAttribute, readCssValue, readEnabledState, readInputValue, readIsChecked, readIsEditable, readIsEnabled, readIsVisible, readTextContent, } from "./element-reads.js";
+import { readAccessibleDescription, readAccessibleName, readAllInnerTexts, readAllTextContents, readAttribute, readBoundingBox, readBoundingClientRect, readClassAttribute, readCssValue, readEnabledState, readInnerHTML, readInnerText, readInputValue, readIsChecked, readIsEditable, readIsEnabled, readIsVisible, readTextContent, } from "./element-reads.js";
+import { evaluateOnAll, evaluateOnElement } from "./evaluate.js";
 import { dropFiles, setInputFiles } from "./file-actions.js";
 import { DEFAULT_PAUSE_MS, pause } from "./input-actions.js";
 import { NOT_STRICT, strictViolation, } from "./strict-mode.js";
@@ -44,6 +45,7 @@ export default class Locator {
                 return locator.selector;
             },
             resolveOne: (method) => this.resolveOne(method),
+            resolveAll: () => this.resolve(),
             call: (fn, args, sandbox) => callInPage(this.access, fn, args, sandbox),
             waitForActionable: (action, checks, probe, options) => this.waitForActionable(action, checks, probe, options),
             requireElement: () => requireElement(this.access),
@@ -338,6 +340,39 @@ export default class Locator {
     async textContent() {
         return readTextContent(this.access);
     }
+    /** Rendered text of the element (as a person would copy it, hidden text left out), untrimmed, or null when the element is missing */
+    async innerText() {
+        return readInnerText(this.access);
+    }
+    /** The markup inside the element, or null when the element is missing */
+    async innerHTML() {
+        return readInnerHTML(this.access);
+    }
+    /** `textContent` of every match, as the page has it (untrimmed, unlike `textContent()`); `[]` when none match. Does not wait */
+    async allTextContents() {
+        return readAllTextContents(this.access);
+    }
+    /** `innerText` of every match; `[]` when none match. Does not wait */
+    async allInnerTexts() {
+        return readAllInnerTexts(this.access);
+    }
+    /** 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 */
+    async boundingBox() {
+        return readBoundingBox(this.access);
+    }
+    /**
+     * 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);
+     */
+    async evaluate(fn, arg, options) {
+        return evaluateOnElement(this.access, fn, arg, options);
+    }
+    /** Calls `fn(elements, arg)` in the page with an array of every match (empty when none; does not wait) and returns the result */
+    async evaluateAll(fn, arg) {
+        return evaluateOnAll(this.access, fn, arg);
+    }
     /** Value of an input/textarea/select, or null when missing */
     async inputValue() {
         return readInputValue(this.access);

package/dist/script/call-function.d.ts

@@ -20,7 +20,14 @@ export declare class ScriptError extends Error {
 export declare class ScriptSerializationError extends Error {
     constructor(message: string);
 }
+/** A function to run in the page, or its source (a string is used as written) */
+export type PageFunction<A extends unknown[], R> = string | ((...args: A) => R | Promise<R>);
 /** The source to send for `fn`; a function object must not depend on transpiler helpers */
 export declare function toFunctionDeclaration(fn: string | ((...args: any[]) => unknown)): string;
 /** Calls `fn` in the page with serialized arguments and returns its deserialized result */
 export declare function callFunction<T = unknown>(connector: BiDiConnector, context: string, fn: string | ((...args: any[]) => unknown), args?: Arg[], options?: CallOptions): Promise<T>;
+/**
+ * Evaluates `expression` in the page and returns its deserialized result; a promise is awaited.
+ * Throws `ScriptError` with the page's message when it throws.
+ */
+export declare function evaluateExpression<T = unknown>(connector: BiDiConnector, context: string, expression: string): Promise<T>;

package/dist/script/call-function.js

@@ -26,10 +26,12 @@ export function toFunctionDeclaration(fn) {
     if (typeof fn === "string")
         return fn;
     const source = fn.toString();
-    // tsx/esbuild wrap named functions in a __name() helper that does not exist in the page
+    // tsx/esbuild (keepNames) wrap named functions in a __name() helper that does not exist in the page
     if (source.includes("__name(")) {
-        throw new ScriptSerializationError("The function's source uses the transpiler's __name helper, which does not exist in the page. " +
-            "Use an arrow function without inner named functions, or pass the function as a string.");
+        throw new ScriptSerializationError("The function's source uses __name(), a helper that tsx and esbuild add around named functions " +
+            "(also an arrow function assigned to a variable) and that does not exist in the page. " +
+            "Write the function without inner named functions (pass callbacks inline as anonymous arrow functions), " +
+            "or pass it as a string.");
     }
     return source;
 }
@@ -52,3 +54,19 @@ export async function callFunction(connector, context, fn, args = [], options =
     }
     return fromRemoteValue(result.result);
 }
+/**
+ * Evaluates `expression` in the page and returns its deserialized result; a promise is awaited.
+ * Throws `ScriptError` with the page's message when it throws.
+ */
+export async function evaluateExpression(connector, context, expression) {
+    const result = await connector.send("script.evaluate", {
+        expression,
+        awaitPromise: true,
+        target: { context },
+        resultOwnership: "none",
+    });
+    if (result.type === "exception") {
+        throw new ScriptError(result.exceptionDetails.text, expression, result.exceptionDetails.stackTrace);
+    }
+    return fromRemoteValue(result.result);
+}

package/dist/wait/wait-until.d.ts

@@ -1,6 +1,8 @@
 export interface WaitOptions {
     /** Total time (ms) to keep probing; 0 probes exactly once */
     timeout: number;
+    /** Pauses (ms) after the first, second, ... probe; the last one repeats. Default: 100 every time */
+    intervals?: readonly number[];
 }
 export declare class WaitTimeoutError<T> extends Error {
     readonly timeout: number;
@@ -13,4 +15,4 @@ export declare class WaitTimeoutError<T> extends Error {
  * Always probes at least once; with `timeout > 0` every probe races the time left.
  * Probe errors are rethrown immediately. Throws WaitTimeoutError at the deadline.
  */
-export declare function waitUntil<T>(probe: () => Promise<T>, isDone: (current: T, previous: T | undefined) => boolean, { timeout }: WaitOptions): Promise<T>;
+export declare function waitUntil<T>(probe: () => Promise<T>, isDone: (current: T, previous: T | undefined) => boolean, { timeout, intervals }: WaitOptions): Promise<T>;

package/dist/wait/wait-until.js

@@ -29,9 +29,10 @@ function probeBefore(probe, remaining) {
  * Always probes at least once; with `timeout > 0` every probe races the time left.
  * Probe errors are rethrown immediately. Throws WaitTimeoutError at the deadline.
  */
-export async function waitUntil(probe, isDone, { timeout }) {
+export async function waitUntil(probe, isDone, { timeout, intervals }) {
     const deadline = Date.now() + timeout;
     let previous;
+    let probes = 0;
     for (let first = true;; first = false) {
         const remaining = deadline - Date.now();
         // Only start a probe while time remains; a later one could only lose the race
@@ -49,6 +50,10 @@ export async function waitUntil(probe, isDone, { timeout }) {
         const left = deadline - Date.now();
         if (left <= 0)
             throw new WaitTimeoutError(timeout, previous);
-        await sleep(Math.min(POLL_INTERVAL, left));
+        const pause = intervals?.length
+            ? intervals[Math.min(probes, intervals.length - 1)]
+            : POLL_INTERVAL;
+        probes++;
+        await sleep(Math.min(pause, left));
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.21.3",
+  "version": "0.21.4",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {