@itmetsam/samurai-framework 0.21.2 → 0.21.4

package/dist/locator/selector.js

@@ -1,3 +1,4 @@
+import { buildRoleSelector, isNativeRole, } from "./role-locator.js";
 function nonEmpty(value, what) {
     if (value.trim() === "")
         throw new TypeError(`${what} must not be empty`);
@@ -9,8 +10,26 @@ export function xpathSelector(value) {
 export function cssSelector(value) {
     return { kind: "css", value: nonEmpty(value, "a css selector") };
 }
-function textMatch(value, what, { match = "full", ignoreCase = false }) {
-    return { value: nonEmpty(value, what), match, ignoreCase };
+export function nthSelector(index) {
+    if (!Number.isInteger(index)) {
+        throw new TypeError(`nth(): index must be an integer, got ${index}`);
+    }
+    return { kind: "nth", index };
+}
+function textMatch(value, what, { exact = true, match, ignoreCase }) {
+    if (value instanceof RegExp) {
+        // The page tests it as written; g and y would make a repeated test depend on lastIndex
+        const plain = new RegExp(value.source, value.flags.replace(/[gy]/g, ""));
+        return { value: plain, match: "full", ignoreCase: false };
+    }
+    if (typeof value !== "string") {
+        throw new TypeError(`${what} must be a string or a RegExp`);
+    }
+    return {
+        value: nonEmpty(value, what),
+        match: match ?? (exact ? "full" : "partial"),
+        ignoreCase: ignoreCase ?? !exact,
+    };
 }
 export function textSelector(value, options = {}) {
     return { kind: "text", ...textMatch(value, "the text", options) };
@@ -18,14 +37,24 @@ export function textSelector(value, options = {}) {
 export function labelSelector(value, options = {}) {
     return { kind: "label", ...textMatch(value, "the label", options) };
 }
+const ATTRIBUTE_WHAT = {
+    placeholder: "the placeholder",
+    alt: "the alt text",
+    title: "the title",
+};
+export function attributeSelector(attribute, value, options = {}) {
+    return {
+        kind: "attribute",
+        attribute,
+        ...textMatch(value, ATTRIBUTE_WHAT[attribute], options),
+    };
+}
 export function testIdSelector(value) {
     return { kind: "testid", value: nonEmpty(value, "the test id") };
 }
-export function roleSelector(role, { name } = {}) {
+export function roleSelector(role, options = {}) {
     nonEmpty(role, "the role");
-    return name === undefined
-        ? { kind: "role", role }
-        : { kind: "role", role, name };
+    return buildRoleSelector(role, options);
 }
 /**
  * Normalises an xpath. Relative xpaths get a leading `//` (`.//` when `scoped`, i.e. searching inside
@@ -48,6 +77,9 @@ export function toBiDiLocator(selector, scoped) {
         case "css":
             return { type: "css", value: selector.value };
         case "text":
+            if (typeof selector.value !== "string") {
+                throw new Error("a RegExp text is resolved by the framework, not by the browser");
+            }
             return {
                 type: "innerText",
                 value: selector.value,
@@ -55,6 +87,9 @@ export function toBiDiLocator(selector, scoped) {
                 ignoreCase: selector.ignoreCase,
             };
         case "role":
+            if (!isNativeRole(selector) || typeof selector.name === "object") {
+                throw new Error("this role search is resolved by the framework, not by the browser");
+            }
             return {
                 type: "accessibility",
                 value: {
@@ -69,9 +104,14 @@ export function toBiDiLocator(selector, scoped) {
             };
         // The locator resolves these two itself, so a chain never hands them to the browser
         case "label":
-            throw new Error("label is resolved by the framework, not by the browser");
+        case "attribute":
+            throw new Error(`${selector.kind} is resolved by the framework, not by the browser`);
         case "nth":
             throw new Error("nth is resolved by the framework, not by the browser");
+        case "filter":
+        case "and":
+        case "or":
+            throw new Error(`${selector.kind} is resolved by the framework, not by the browser`);
     }
 }
 /** A short name for error messages */
@@ -87,19 +127,50 @@ export function describeSelector(selector, scoped) {
                 selector.match === "partial" && "partial",
                 selector.ignoreCase && "ignoring case",
             ].filter(Boolean);
-            return `${selector.kind}=${JSON.stringify(selector.value)}${flags.length ? ` (${flags.join(", ")})` : ""}`;
+            return `${selector.kind}=${describeValue(selector.value)}${flags.length ? ` (${flags.join(", ")})` : ""}`;
+        }
+        case "attribute": {
+            const flags = [
+                selector.match === "partial" && "partial",
+                selector.ignoreCase && "ignoring case",
+            ].filter(Boolean);
+            return `${selector.attribute}=${describeValue(selector.value)}${flags.length ? ` (${flags.join(", ")})` : ""}`;
         }
         case "testid":
             return `testid=${JSON.stringify(selector.value)}`;
         case "role":
-            return (`role=${selector.role}` +
-                (selector.name === undefined
-                    ? ""
-                    : `[name=${JSON.stringify(selector.name)}]`));
+            return `role=${selector.role}${describeRoleOptions(selector)}`;
         case "nth":
             return `nth=${selector.index}`;
+        case "filter":
+            return `filter(${describeFilter(selector)})`;
+        case "and":
+        case "or":
+            return `(${describeChain(selector.left)}) ${selector.kind} (${describeChain(selector.right)})`;
     }
 }
+function describeValue(value) {
+    return typeof value === "string" ? JSON.stringify(value) : String(value);
+}
+function describeRoleOptions({ kind: _kind, role: _role, name, exact, ...rest }) {
+    const parts = [
+        name !== undefined && `name=${describeValue(name)}`,
+        exact === false && "exact=false",
+        ...Object.entries(rest).map(([key, value]) => `${key}=${String(value)}`),
+    ].filter(Boolean);
+    return parts.length ? `[${parts.join(", ")}]` : "";
+}
+function describeFilter(tests) {
+    return [
+        tests.hasText !== undefined && `hasText=${describeValue(tests.hasText)}`,
+        tests.hasNotText !== undefined &&
+            `hasNotText=${describeValue(tests.hasNotText)}`,
+        tests.has && `has=${describeChain(tests.has)}`,
+        tests.hasNot && `hasNot=${describeChain(tests.hasNot)}`,
+    ]
+        .filter(Boolean)
+        .join(", ");
+}
 export function describeChain(chain) {
     return chain
         .map((selector, index) => describeSelector(selector, index > 0))

package/dist/locator/strict-mode.d.ts

@@ -0,0 +1,6 @@
+/** Whether a locator throws when it matches several elements; asked when an action or read needs its element */
+export type StrictSource = () => Promise<boolean>;
+/** The default: the first match is used */
+export declare const NOT_STRICT: StrictSource;
+/** The error a strict locator throws for an action or read that found several elements */
+export declare function strictViolation(method: string, count: number, selector: string): Error;

package/dist/locator/strict-mode.js

@@ -0,0 +1,6 @@
+/** The default: the first match is used */
+export const NOT_STRICT = () => Promise.resolve(false);
+/** The error a strict locator throws for an action or read that found several elements */
+export function strictViolation(method, count, selector) {
+    return new Error(`${method}(): strict mode violation, ${count} elements match ${selector}`);
+}

package/dist/locator/text-locator.d.ts

@@ -10,4 +10,4 @@
  *
  * A string, so the transpiler cannot inject helpers that do not exist in the page.
  */
-export declare const TEXT_LOCATE = "(starts, value, match, ignoreCase) => {\n  const skipped = new Set([\"SCRIPT\", \"STYLE\", \"NOSCRIPT\", \"TEMPLATE\", \"HEAD\", \"TITLE\", \"META\", \"LINK\"]);\n  \n  const normalise = (text) => {\n    const collapsed = String(text).replace(/\\s+/g, \" \").trim();\n    return ignoreCase ? collapsed.toLowerCase() : collapsed;\n  };\n  const wanted = normalise(value);\n  const textMatches = (text) => {\n    const normal = normalise(text);\n    return match === \"full\" ? normal === wanted : normal.includes(wanted);\n  };\n  const roots = starts.length > 0 ? starts : [document];\n  const seen = new Set();\n  const matches = [];\n  for (const root of roots) {\n    for (const el of root.querySelectorAll(\"*\")) {\n      if (seen.has(el) || skipped.has(el.tagName.toUpperCase())) continue;\n      seen.add(el);\n      if (textMatches(el.innerText ?? el.textContent ?? \"\")) matches.push(el);\n    }\n  }\n  const hasMatchingDescendant = new Set();\n  for (const el of matches) {\n    for (let parent = el.parentElement; parent; parent = parent.parentElement) hasMatchingDescendant.add(parent);\n  }\n  return matches\n    .filter((el) => !hasMatchingDescendant.has(el))\n    .sort((a, b) => (a === b ? 0 : a.compareDocumentPosition(b) & 4 ? -1 : 1));\n}";
+export declare const TEXT_LOCATE = "(starts, value, match, ignoreCase) => {\n  const skipped = new Set([\"SCRIPT\", \"STYLE\", \"NOSCRIPT\", \"TEMPLATE\", \"HEAD\", \"TITLE\", \"META\", \"LINK\"]);\n  \n  const collapse = (text) => String(text).replace(/\\s+/g, \" \").trim();\n  const normalise = (text) => {\n    const collapsed = collapse(text);\n    return ignoreCase ? collapsed.toLowerCase() : collapsed;\n  };\n  const pattern = typeof value === \"string\" ? null : new RegExp(value.source, value.flags.replace(/[gy]/g, \"\"));\n  const wanted = pattern ? \"\" : normalise(value);\n  const textMatches = (text) => {\n    if (pattern) return pattern.test(collapse(text));\n    const normal = normalise(text);\n    return match === \"full\" ? normal === wanted : normal.includes(wanted);\n  };\n  const roots = starts.length > 0 ? starts : [document];\n  const seen = new Set();\n  const matches = [];\n  for (const root of roots) {\n    for (const el of root.querySelectorAll(\"*\")) {\n      if (seen.has(el) || skipped.has(el.tagName.toUpperCase())) continue;\n      seen.add(el);\n      if (textMatches(el.innerText ?? el.textContent ?? \"\")) matches.push(el);\n    }\n  }\n  const hasMatchingDescendant = new Set();\n  for (const el of matches) {\n    for (let parent = el.parentElement; parent; parent = parent.parentElement) hasMatchingDescendant.add(parent);\n  }\n  return matches\n    .filter((el) => !hasMatchingDescendant.has(el))\n    .sort((a, b) => (a === b ? 0 : a.compareDocumentPosition(b) & 4 ? -1 : 1));\n}";

package/dist/network/url-match.js

@@ -24,7 +24,9 @@ function globToRegExp(glob) {
 /** Whether `url` matches `pattern` */
 export function matchUrl(pattern, url) {
     if (typeof pattern === "string") {
-        return isExactString(pattern) ? pattern === url : globToRegExp(pattern).test(url);
+        return isExactString(pattern)
+            ? pattern === url
+            : globToRegExp(pattern).test(url);
     }
     // A global or sticky RegExp remembers where it stopped; every match must start fresh
     pattern.lastIndex = 0;

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/types/config.d.ts

@@ -142,6 +142,13 @@ export interface SamuraiTestConfig {
      * Left out, a run is headless when the `CI` environment variable is set and shows a window otherwise
      */
     headless?: boolean;
+    /**
+     * Make an action or read on a locator that matches several elements throw
+     * `name(): strict mode violation, N elements match ...` instead of using the first one. Narrow the locator
+     * (`first()`, `nth()`, `filter()`) or turn it off for one locator with `locator.strict(false)`
+     * @default false
+     */
+    strictSelectors?: boolean;
   };
   /** What to do with the browser's console output and uncaught page exceptions */
   logs?: {

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.2",
+  "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": {