@itmetsam/samurai-framework 0.21.1 → 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/network-tracker.d.ts

@@ -11,6 +11,12 @@ export interface TrackerOptions {
  * Follows the network activity of one page (its frames included): which requests are in flight,
  * and `request` / `response` / `requestfailed` events. In-flight is keyed by `request id:redirect count`,
  * so a redirect chain is one live request at a time.
+ *
+ * Chrome (chromium-bidi) reports a redirect response only once the browser has started the next hop, and it can
+ * leave out that hop's `beforeRequestSent`: when the hop's `requestWillBeSentExtraInfo` reaches it before the
+ * redirect's `requestWillBeSent`, it files the extra info under the previous hop and never announces the new one.
+ * So on Chrome a redirect keeps the chain in flight until the next hop shows itself, and a hop that first shows up
+ * with its response or error is announced then.
  */
 export declare class NetworkTracker {
     private tree;
@@ -21,13 +27,16 @@ export declare class NetworkTracker {
     private subscription;
     /**
      * Every hop that is in flight or may still be the source of a redirect, by hop key. A redirect response ends a
-     * hop's flight (`live` false) but keeps it, for the next hop's `redirectedFrom`.
+     * hop's flight (`live` false; on Chrome `answered`, live until the next hop shows) but keeps it, for the next
+     * hop's `redirectedFrom`.
      */
     private hops;
     /** Rejects a pending `waitForIdle`; each wait adds its own */
     private waiters;
     private disposed;
     private constructor();
+    /** Whether a redirect response means the next hop has already started (Chrome), see the class comment */
+    private get redirectsStartNextHop();
     static start(connector: BiDiConnector, tree: ContextTree, contextId: string, options?: TrackerOptions): Promise<NetworkTracker>;
     /** Requests currently in flight */
     get inflight(): number;
@@ -52,6 +61,13 @@ export declare class NetworkTracker {
     private owns;
     private static key;
     private onBeforeRequestSent;
+    /** Tracks a new hop and emits its `request`; the hop it was redirected from is done with */
+    private startHop;
+    /**
+     * The hop a response or error is for. A hop Chrome never announced (see the class comment) is started here,
+     * when the hop it was redirected from is known.
+     */
+    private hopOf;
     private onResponseCompleted;
     private onFetchError;
     /**

package/dist/network/network-tracker.js

@@ -12,6 +12,12 @@ const URLS_IN_MESSAGE = 5;
  * Follows the network activity of one page (its frames included): which requests are in flight,
  * and `request` / `response` / `requestfailed` events. In-flight is keyed by `request id:redirect count`,
  * so a redirect chain is one live request at a time.
+ *
+ * Chrome (chromium-bidi) reports a redirect response only once the browser has started the next hop, and it can
+ * leave out that hop's `beforeRequestSent`: when the hop's `requestWillBeSentExtraInfo` reaches it before the
+ * redirect's `requestWillBeSent`, it files the extra info under the previous hop and never announces the new one.
+ * So on Chrome a redirect keeps the chain in flight until the next hop shows itself, and a hop that first shows up
+ * with its response or error is announced then.
  */
 export class NetworkTracker {
     constructor(tree, contextId, ignore, connector) {
@@ -22,7 +28,8 @@ export class NetworkTracker {
         this.events = new EventEmitter();
         /**
          * Every hop that is in flight or may still be the source of a redirect, by hop key. A redirect response ends a
-         * hop's flight (`live` false) but keeps it, for the next hop's `redirectedFrom`.
+         * hop's flight (`live` false; on Chrome `answered`, live until the next hop shows) but keeps it, for the next
+         * hop's `redirectedFrom`.
          */
         this.hops = new Map();
         /** Rejects a pending `waitForIdle`; each wait adds its own */
@@ -31,30 +38,22 @@ export class NetworkTracker {
         this.onBeforeRequestSent = (params) => {
             if (!this.owns(params.context))
                 return;
-            const key = NetworkTracker.key(params.request, params.redirectCount);
-            const { redirectCount } = params;
-            const previousKey = `${params.request.request}:${redirectCount - 1}`;
-            const redirectedFrom = redirectCount > 0 ? (this.hops.get(previousKey)?.request ?? null) : null;
-            this.hops.delete(previousKey);
-            const request = toRequest(params.request, params.navigation, params.isBlocked, redirectedFrom);
-            if (this.ignore(request))
-                return;
-            this.hops.set(key, { request, context: params.context, live: true });
-            this.emit("request", request);
-            this.events.emit("change");
+            this.startHop(params);
         };
         this.onResponseCompleted = (params) => {
             if (!this.owns(params.context))
                 return;
             const key = NetworkTracker.key(params.request, params.redirectCount);
-            const hop = this.hops.get(key);
-            if (!hop?.live)
+            const hop = this.hopOf(params);
+            if (!hop?.live || hop.answered)
                 return;
             const { request } = hop;
             const { response } = params;
             // A redirect response keeps its request around: the next hop links back to it
             if (response.status < 300 || response.status >= 400)
                 this.hops.delete(key);
+            else if (this.redirectsStartNextHop && hasLocation(response))
+                hop.answered = true;
             else
                 hop.live = false;
             this.emit("response", {
@@ -71,11 +70,13 @@ export class NetworkTracker {
             if (!this.owns(params.context))
                 return;
             const key = NetworkTracker.key(params.request, params.redirectCount);
-            const hop = this.hops.get(key);
+            const hop = this.hopOf(params);
             if (!hop?.live)
                 return;
             this.hops.delete(key);
-            this.emit("requestfailed", Object.assign(hop.request, { errorText: params.errorText }));
+            // A hop that has its response already did not fail
+            if (!hop.answered)
+                this.emit("requestfailed", Object.assign(hop.request, { errorText: params.errorText }));
             this.events.emit("change");
         };
         /**
@@ -86,19 +87,24 @@ export class NetworkTracker {
             if (!this.owns(params.context))
                 return;
             let changed = false;
-            for (const [key, { request, context, live }] of [...this.hops]) {
+            for (const [key, { request, context, live, answered }] of [...this.hops]) {
                 if (!live || request.navigation === params.navigation)
                     continue;
                 if (!this.tree.isWithin(context, params.context))
                     continue;
                 this.hops.delete(key);
-                this.emit("requestfailed", Object.assign(request, { errorText: ABORTED_BY_NAVIGATION }));
+                if (!answered)
+                    this.emit("requestfailed", Object.assign(request, { errorText: ABORTED_BY_NAVIGATION }));
                 changed = true;
             }
             if (changed)
                 this.events.emit("change");
         };
     }
+    /** Whether a redirect response means the next hop has already started (Chrome), see the class comment */
+    get redirectsStartNextHop() {
+        return this.connector.browserName === "chrome";
+    }
     static async start(connector, tree, contextId, options = {}) {
         const tracker = new NetworkTracker(tree, contextId, options.ignore ?? (() => false), connector);
         // Listen first, then subscribe: nothing can arrive in between
@@ -189,6 +195,41 @@ export class NetworkTracker {
     static key(data, redirectCount) {
         return `${data.request}:${redirectCount}`;
     }
+    /** Tracks a new hop and emits its `request`; the hop it was redirected from is done with */
+    startHop(params) {
+        const key = NetworkTracker.key(params.request, params.redirectCount);
+        const { redirectCount } = params;
+        const previousKey = `${params.request.request}:${redirectCount - 1}`;
+        const previous = redirectCount > 0 ? this.hops.get(previousKey) : undefined;
+        this.hops.delete(previousKey);
+        const request = toRequest(params.request, params.navigation, params.isBlocked, previous?.request ?? null);
+        if (this.ignore(request)) {
+            if (previous?.live)
+                this.events.emit("change");
+            return undefined;
+        }
+        const hop = {
+            request,
+            context: params.context,
+            live: true,
+            answered: false,
+        };
+        this.hops.set(key, hop);
+        this.emit("request", request);
+        this.events.emit("change");
+        return hop;
+    }
+    /**
+     * The hop a response or error is for. A hop Chrome never announced (see the class comment) is started here,
+     * when the hop it was redirected from is known.
+     */
+    hopOf(params) {
+        const hop = this.hops.get(NetworkTracker.key(params.request, params.redirectCount));
+        if (hop || params.redirectCount === 0)
+            return hop;
+        const previousKey = `${params.request.request}:${params.redirectCount - 1}`;
+        return this.hops.has(previousKey) ? this.startHop(params) : undefined;
+    }
     /** A listener that throws must not stop the tracker or the other listeners */
     emit(event, ...args) {
         for (const listener of this.events.listeners(event)) {
@@ -201,3 +242,7 @@ export class NetworkTracker {
         }
     }
 }
+/** Whether a 3xx response says where to go next: only then does the browser follow it */
+function hasLocation(response) {
+    return response.headers.some((header) => header.name.toLowerCase() === "location");
+}

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