@itmetsam/samurai-framework 0.21.2 → 0.21.3

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/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/package.json

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