@itmetsam/samurai-framework 0.21.2 → 0.21.3

package/README.md

@@ -19,7 +19,7 @@ test("Visitor can sign in", async ({ page, env, secrets }) => {
 ```
 
 - **Auto-waiting.** Actions wait until the element is attached, visible, stable, enabled and not covered. Assertions retry until they pass or time out.
-- **Semantic locators.** By role, label, text, test id, CSS or XPath, with ordered fallbacks.
+- **Semantic locators.** By role, label, text, test id, CSS or XPath, with `nth`, `filter`, `and` / `or` and ordered fallbacks.
 - **Environments and secrets.** One test file runs against `dev`, `staging` or `production`; secrets come from the environment or a `.env.<name>` file and are masked in logs and reports.
 - **Parallel runs.** Tests run side by side in worker processes (`--workers`, `workers` in the config; half the CPUs by default), and a flow's Parallel node runs its branches at the same time (see [Running tests and reports](https://github.com/degrootsam/samurai-framework/wiki/Running-tests-and-reports#parallel-runs)).
 - **Network control.** Mock, block or modify requests; wait for requests, responses and network idle; read response bodies.

package/dist/assert/locator-assertions.d.ts

@@ -65,4 +65,8 @@ export declare class LocatorAssertions {
     toHaveClass(expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
     /** The computed value of a CSS property equals `expected` (string) or matches it (RegExp); `name` may be camelCase (`backgroundColor`) or kebab-case, `--custom` is kept */
     toHaveCSS(name: string, expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
+    /** The accessible name equals `expected` (string, whitespace collapsed and trimmed on both sides) or matches it (RegExp, tested as written); a missing element never passes, not even with `.not` */
+    toHaveAccessibleName(expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
+    /** The accessible description (`aria-describedby`, else `title` when it is not the name) equals or matches `expected`, as `toHaveAccessibleName`; "" when there is none */
+    toHaveAccessibleDescription(expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
 }

package/dist/assert/locator-assertions.js

@@ -3,7 +3,7 @@ import { waitUntil, WaitTimeoutError } from "../wait/wait-until.js";
 import { AssertionError } from "./assertion-error.js";
 import { track } from "./pending-assertions.js";
 import { bindOutput } from "../wait/output-sink.js";
-import { captured, classCheck, matchesText, textCheck } from "./text-match.js";
+import { captured, matchesText, normalizedCheck, textCheck, } from "./text-match.js";
 /**
  * Re-reads the element until `check` passes or the timeout expires, and resolves with the read that passed. A
  * timeout fails as an `AssertionError` with the last read, or as "could not read" when no read completed.
@@ -107,10 +107,18 @@ export class LocatorAssertions {
     }
     /** The class attribute equals `expected` (string, whitespace collapsed and trimmed on both sides) or matches it (RegExp, tested on the attribute as written) */
     toHaveClass(expected, options) {
-        return this.assertExisting("toHaveClass", expected, () => this.locator.classAttribute(), classCheck(expected), options);
+        return this.assertExisting("toHaveClass", expected, () => this.locator.classAttribute(), normalizedCheck(expected), options);
     }
     /** The computed value of a CSS property equals `expected` (string) or matches it (RegExp); `name` may be camelCase (`backgroundColor`) or kebab-case, `--custom` is kept */
     toHaveCSS(name, expected, options) {
         return this.assertExisting("toHaveCSS", expected, () => this.locator.cssValue(name), (actual) => matchesText(actual, expected, "exact"), options);
     }
+    /** The accessible name equals `expected` (string, whitespace collapsed and trimmed on both sides) or matches it (RegExp, tested as written); a missing element never passes, not even with `.not` */
+    toHaveAccessibleName(expected, options) {
+        return this.assertExisting("toHaveAccessibleName", expected, () => this.locator.accessibleName(), normalizedCheck(expected), options);
+    }
+    /** The accessible description (`aria-describedby`, else `title` when it is not the name) equals or matches `expected`, as `toHaveAccessibleName`; "" when there is none */
+    toHaveAccessibleDescription(expected, options) {
+        return this.assertExisting("toHaveAccessibleDescription", expected, () => this.locator.accessibleDescription(), normalizedCheck(expected), options);
+    }
 }

package/dist/assert/text-match.d.ts

@@ -8,5 +8,5 @@ export declare function matchesText(actual: string, expected: string | RegExp, m
 export declare function captured(matcher: string | RegExp, actual: string): string;
 /** A check for a read that may find nothing (`null`): true when the text is there and matches */
 export declare function textCheck(expected: string | RegExp, mode: "exact" | "contains"): (actual: string | null) => boolean;
-/** A check for a class attribute: a string equals it after collapsing whitespace and trimming both sides, a RegExp tests it as written */
-export declare function classCheck(expected: string | RegExp): (actual: string) => boolean;
+/** A check for a text compared after normalising whitespace: a string equals it with whitespace collapsed and both sides trimmed, a RegExp tests it as written */
+export declare function normalizedCheck(expected: string | RegExp): (actual: string) => boolean;

package/dist/assert/text-match.js

@@ -21,8 +21,8 @@ export function captured(matcher, actual) {
 export function textCheck(expected, mode) {
     return (actual) => actual !== null && matchesText(actual, expected, mode);
 }
-/** A check for a class attribute: a string equals it after collapsing whitespace and trimming both sides, a RegExp tests it as written */
-export function classCheck(expected) {
+/** A check for a text compared after normalising whitespace: a string equals it with whitespace collapsed and both sides trimmed, a RegExp tests it as written */
+export function normalizedCheck(expected) {
     if (expected instanceof RegExp)
         return (actual) => matchesText(actual, expected, "exact");
     const normalize = (value) => value.replace(/\s+/g, " ").trim();

package/dist/browser/dialog.js

@@ -30,7 +30,10 @@ export class Dialog {
     }
     /** Clicks OK; `promptText` is typed into a `prompt` first */
     accept(promptText) {
-        return this.answer({ accept: true, ...(promptText !== undefined && { userText: promptText }) });
+        return this.answer({
+            accept: true,
+            ...(promptText !== undefined && { userText: promptText }),
+        });
     }
     /** Clicks Cancel */
     dismiss() {

package/dist/browser/init-script.d.ts

@@ -1,2 +1,13 @@
+import { type PreloadHandle } from "../script/preload.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
 /** Wraps an init script as one function declaration; the argument is embedded as JSON because preload scripts take no arguments */
 export declare function initScriptSource(script: string | ((arg?: any) => void), arg: unknown): string;
+/** The init scripts a page registered, so they can be released with the page */
+export declare class InitScripts {
+    private scripts;
+    /** Registers `script` for every document the context loads from now on, and runs it in the one loaded now */
+    add(biDiConnector: BiDiConnector, contextId: BrowsingContext, script: string | ((arg?: any) => void), arg?: unknown): Promise<PreloadHandle>;
+    /** The scripts still registered */
+    all(): PreloadHandle[];
+}

package/dist/browser/init-script.js

@@ -1,4 +1,5 @@
 import { toFunctionDeclaration } from "../script/call-function.js";
+import { addPreload } from "../script/preload.js";
 /** Wraps an init script as one function declaration; the argument is embedded as JSON because preload scripts take no arguments */
 export function initScriptSource(script, arg) {
     if (typeof script === "string") {
@@ -14,3 +15,31 @@ export function initScriptSource(script, arg) {
     }
     return `() => (${declaration})(${argument})`;
 }
+/** The init scripts a page registered, so they can be released with the page */
+export class InitScripts {
+    constructor() {
+        this.scripts = new Set();
+    }
+    /** Registers `script` for every document the context loads from now on, and runs it in the one loaded now */
+    async add(biDiConnector, contextId, script, arg) {
+        const source = initScriptSource(script, arg);
+        const handle = await addPreload(biDiConnector, {
+            source,
+            contexts: [contextId],
+            onRunError: "log",
+        });
+        const tracked = {
+            id: handle.id,
+            dispose: async () => {
+                this.scripts.delete(tracked);
+                await handle.dispose();
+            },
+        };
+        this.scripts.add(tracked);
+        return tracked;
+    }
+    /** The scripts still registered */
+    all() {
+        return [...this.scripts];
+    }
+}

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

@@ -0,0 +1,18 @@
+import Locator from "../locator/locator.js";
+import type { HelperRealm } from "../locator/helper-realm.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
+import type { PageConfig } from "./page-settings.js";
+/** Makes the page's locators, and holds whether they are strict */
+export declare class PageLocators {
+    private biDiConnector;
+    private id;
+    private helperRealm;
+    private pageConfig;
+    private assertOpen;
+    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 */
+    setStrictSelectors(enabled: boolean | undefined): void;
+}

package/dist/browser/page-locators.js

@@ -0,0 +1,19 @@
+import Locator from "../locator/locator.js";
+/** Makes the page's locators, and holds whether they are strict */
+export class PageLocators {
+    constructor(biDiConnector, id, helperRealm, pageConfig, assertOpen) {
+        this.biDiConnector = biDiConnector;
+        this.id = id;
+        this.helperRealm = helperRealm;
+        this.pageConfig = pageConfig;
+        this.assertOpen = assertOpen;
+    }
+    locate(selector) {
+        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 */
+    setStrictSelectors(enabled) {
+        this.strictOverride = enabled;
+    }
+}

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

@@ -0,0 +1,6 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BrowserContext } from "./browser-context.js";
+/** Grants a browser permission to the origin of the page (`url`), or to `options.origin` */
+export declare function grantPermission(biDiConnector: BiDiConnector, url: () => Promise<string>, context: () => BrowserContext | undefined, name: string, options?: {
+    origin?: string;
+}): Promise<void>;

package/dist/browser/page-permissions.js

@@ -0,0 +1,15 @@
+/** Grants a browser permission to the origin of the page (`url`), or to `options.origin` */
+export async function grantPermission(biDiConnector, url, context, name, options = {}) {
+    const origin = options.origin ?? new URL(await url()).origin;
+    // about:blank and data: pages have no origin to grant to
+    if (origin === "null")
+        throw new Error("grantPermission(): needs a page on a web origin, or an explicit origin option");
+    const browserContext = context();
+    await biDiConnector.send("permissions.setPermission", {
+        descriptor: { name },
+        state: "granted",
+        origin,
+        ...(browserContext &&
+            !browserContext.isDefault && { userContext: browserContext.id }),
+    });
+}

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

@@ -25,7 +25,10 @@ export declare class PageConfig {
             height: number;
         } | null;
         headless?: boolean;
+        strictSelectors?: boolean;
     }>;
+    /** Whether locators throw when they match several elements: the given override, else config `use.strictSelectors`, else no */
+    strictSelectors(override?: boolean): Promise<boolean>;
     /** The time (ms) a navigation or a wait may take: the call's, else config `navigation.timeout`, else 30 s */
     navigationTimeout(override?: number): Promise<number>;
     /** What a navigation waits for: the call's, else config `navigation.waitUntil`, else the load event */

package/dist/browser/page-settings.js

@@ -31,6 +31,10 @@ export class PageConfig {
             ? Promise.resolve(this.given.use)
             : readSection("use");
     }
+    /** Whether locators throw when they match several elements: the given override, else config `use.strictSelectors`, else no */
+    async strictSelectors(override) {
+        return override ?? (await this.use()).strictSelectors ?? false;
+    }
     /** The time (ms) a navigation or a wait may take: the call's, else config `navigation.timeout`, else 30 s */
     async navigationTimeout(override) {
         return (override ??

package/dist/browser/page.d.ts

@@ -1,5 +1,7 @@
 import Locator from "../locator/locator.js";
-import type { TextOptions } from "../locator/selector.js";
+import type { FilterOptions } from "../locator/filter-step.js";
+import type { RoleOptions } from "../locator/role-locator.js";
+import type { ExactOption, TextOptions } from "../locator/selector.js";
 import type { NetworkRequest } from "../network/network-tracker.js";
 import type { Recorder, RecorderOptions } from "../recorder/recorder.js";
 import { ContextTree } from "./context-tree.js";
@@ -21,7 +23,7 @@ export type { PageEventName, WaitableEventName, WaitForEventOptions, WaitOptions
 import { type PageSettings, type ReadinessState } from "./page-settings.js";
 export type { PageSettings, ReadinessState };
 import { type Viewport } from "./viewport.js";
-import { type PreloadHandle } from "../script/preload.js";
+import type { PreloadHandle } from "../script/preload.js";
 import type { BiDiConnector } from "../transport/bidi-connection.js";
 import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
 export type { LoadState, NavigateOptions, NavigationResult };
@@ -32,6 +34,7 @@ export default class Page {
     private helperRealm;
     private initScripts;
     private pageConfig;
+    private locators;
     private pageEvents;
     private documents;
     private nav;
@@ -49,21 +52,34 @@ export default class Page {
     get contextId(): BrowsingContext;
     /** The context tree, created on first use and shared by everything that needs to attribute frame events to this page */
     tree(): Promise<ContextTree>;
-    /** Locates an element on the page and returns an interactable object */
-    locator(xpath: string): Locator;
-    private locate;
+    /**
+     * Locates elements on the page. An xpath (`//x`, `/html/body`, `(//x)[2]`, `./x`, `xpath=…`, or an older
+     * relative one such as `a[@id='x']`) or a css selector (`input[name='x']`, `a, button`, `css=…`).
+     * `options` filter the matches, as `locator.filter()` does
+     */
+    locator(selector: string, options?: FilterOptions<Locator>): Locator;
+    /**
+     * 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
+     */
+    setStrictSelectors(enabled: boolean | undefined): void;
     /** Locates elements with a CSS selector */
     getByCss(css: string): Locator;
-    /** Locates elements by their text: an exact match unless `match: "partial"` */
-    getByText(text: string, options?: TextOptions): Locator;
-    /** Locates form controls by their label text: an exact match unless `match: "partial"` */
-    getByLabel(text: string, options?: TextOptions): Locator;
+    /** Locates elements by their text: an exact match unless `match: "partial"` or `exact: false`; a RegExp is tested as written (see `TextOptions`) */
+    getByText(text: string | RegExp, options?: TextOptions): Locator;
+    /** Locates form controls by their label text: an exact match unless `match: "partial"` or `exact: false`; a RegExp is tested as written */
+    getByLabel(text: string | RegExp, options?: TextOptions): Locator;
+    /** Locates elements by their `placeholder` (see `TextOptions` for `exact` and RegExp) */
+    getByPlaceholder(text: string | RegExp, options?: ExactOption): Locator;
+    /** Locates elements by their `alt` text (images, areas, image inputs) */
+    getByAltText(text: string | RegExp, options?: ExactOption): Locator;
+    /** Locates elements by their `title` attribute */
+    getByTitle(text: string | RegExp, options?: ExactOption): Locator;
     /** Locates elements by their `data-testid` attribute */
     getByTestId(testId: string): Locator;
-    /** Locates elements by ARIA role and, optionally, accessible name */
-    getByRole(role: string, options?: {
-        name?: string;
-    }): Locator;
+    /** Locates elements by ARIA role and, optionally, accessible name and state (see `RoleOptions`) */
+    getByRole(role: string, options?: RoleOptions): Locator;
     /**
      * Runs `script` before any page script in every document this page loads from now on, and once in
      * the document that is loaded now. It runs in the page's own realm, so the page sees what it sets.

package/dist/browser/page.js

@@ -1,5 +1,5 @@
 import Locator from "../locator/locator.js";
-import { cssSelector, labelSelector, roleSelector, testIdSelector, textSelector, } from "../locator/selector.js";
+import { attributeSelector, cssSelector, labelSelector, roleSelector, testIdSelector, textSelector, } from "../locator/selector.js";
 import EventEmitter from "node:events";
 import path from "node:path";
 import { projectDir } from "../config/config.js";
@@ -19,19 +19,20 @@ import { DocumentWatcher } from "./document-watcher.js";
 import { PageNavigation } from "./page-navigation.js";
 import { PageNetwork } from "./page-network.js";
 import { PageTransfers } from "./page-transfers.js";
-import { initScriptSource } from "./init-script.js";
+import { InitScripts } from "./init-script.js";
+import { grantPermission } from "./page-permissions.js";
+import { PageLocators } from "./page-locators.js";
 import { sourcesFor, waitForPageEvent, } from "./page-events.js";
 import { PageConfig, } from "./page-settings.js";
 import { applyViewport } from "./viewport.js";
 import { HelperRealm } from "../locator/helper-realm.js";
-import { addPreload } from "../script/preload.js";
 import { BiDiError } from "../transport/bidi-error.js";
 import { callFunction } from "../script/call-function.js";
 export default class Page {
     /** `settings` override what `samurai.config.ts` says; without them the config is read when needed */
     constructor(biDiConnector, contextId, settings) {
         this.lazyTree = new Lazy();
-        this.initScripts = new Set();
+        this.initScripts = new InitScripts();
         this.pageEvents = new EventEmitter();
         this.lazyLogs = new Lazy();
         this.errorsAllowed = false;
@@ -40,6 +41,7 @@ export default class Page {
         this.id = contextId;
         this.pageConfig = new PageConfig(settings);
         this.helperRealm = new HelperRealm(biDiConnector, contextId);
+        this.locators = new PageLocators(biDiConnector, contextId, this.helperRealm, this.pageConfig, () => this.assertOpen());
         this.documents = new DocumentWatcher(biDiConnector, contextId);
         this.net = new PageNetwork(biDiConnector, contextId, {
             config: this.pageConfig,
@@ -70,33 +72,56 @@ export default class Page {
     tree() {
         return this.lazyTree.get(() => ContextTree.create(this.biDiConnector));
     }
-    /** Locates an element on the page and returns an interactable object */
-    locator(xpath) {
-        return this.locate(xpath);
+    /**
+     * Locates elements on the page. An xpath (`//x`, `/html/body`, `(//x)[2]`, `./x`, `xpath=…`, or an older
+     * relative one such as `a[@id='x']`) or a css selector (`input[name='x']`, `a, button`, `css=…`).
+     * `options` filter the matches, as `locator.filter()` does
+     */
+    locator(selector, options) {
+        const found = this.locators.locate(selector);
+        return options === undefined ? found : found.filter(options);
     }
-    locate(selector) {
-        this.assertOpen();
-        return new Locator(selector, this.biDiConnector, this.id, this.helperRealm);
+    /**
+     * 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
+     */
+    setStrictSelectors(enabled) {
+        this.locators.setStrictSelectors(enabled);
     }
     /** Locates elements with a CSS selector */
     getByCss(css) {
-        return this.locate([cssSelector(css)]);
+        return this.locators.locate([cssSelector(css)]);
     }
-    /** Locates elements by their text: an exact match unless `match: "partial"` */
+    /** Locates elements by their text: an exact match unless `match: "partial"` or `exact: false`; a RegExp is tested as written (see `TextOptions`) */
     getByText(text, options) {
-        return this.locate([textSelector(text, options)]);
+        return this.locators.locate([textSelector(text, options)]);
     }
-    /** Locates form controls by their label text: an exact match unless `match: "partial"` */
+    /** Locates form controls by their label text: an exact match unless `match: "partial"` or `exact: false`; a RegExp is tested as written */
     getByLabel(text, options) {
-        return this.locate([labelSelector(text, options)]);
+        return this.locators.locate([labelSelector(text, options)]);
+    }
+    /** Locates elements by their `placeholder` (see `TextOptions` for `exact` and RegExp) */
+    getByPlaceholder(text, options) {
+        return this.locators.locate([
+            attributeSelector("placeholder", text, options),
+        ]);
+    }
+    /** Locates elements by their `alt` text (images, areas, image inputs) */
+    getByAltText(text, options) {
+        return this.locators.locate([attributeSelector("alt", text, options)]);
+    }
+    /** Locates elements by their `title` attribute */
+    getByTitle(text, options) {
+        return this.locators.locate([attributeSelector("title", text, options)]);
     }
     /** Locates elements by their `data-testid` attribute */
     getByTestId(testId) {
-        return this.locate([testIdSelector(testId)]);
+        return this.locators.locate([testIdSelector(testId)]);
     }
-    /** Locates elements by ARIA role and, optionally, accessible name */
+    /** Locates elements by ARIA role and, optionally, accessible name and state (see `RoleOptions`) */
     getByRole(role, options) {
-        return this.locate([roleSelector(role, options)]);
+        return this.locators.locate([roleSelector(role, options)]);
     }
     /**
      * Runs `script` before any page script in every document this page loads from now on, and once in
@@ -109,21 +134,7 @@ export default class Page {
      */
     async addInitScript(script, arg) {
         this.assertOpen();
-        const source = initScriptSource(script, arg);
-        const handle = await addPreload(this.biDiConnector, {
-            source,
-            contexts: [this.id],
-            onRunError: "log",
-        });
-        const tracked = {
-            id: handle.id,
-            dispose: async () => {
-                this.initScripts.delete(tracked);
-                await handle.dispose();
-            },
-        };
-        this.initScripts.add(tracked);
-        return tracked;
+        return this.initScripts.add(this.biDiConnector, this.id, script, arg);
     }
     /**
      * Starts recording what a person does in the page as steps (see `Recorder`). The page must be driven by
@@ -137,7 +148,7 @@ export default class Page {
     }
     /** Removes everything the page registered in the browser: init scripts, framework helpers and event subscriptions */
     async dispose() {
-        const scripts = [...this.initScripts];
+        const scripts = this.initScripts.all();
         const results = await Promise.allSettled([
             ...scripts.map((handle) => handle.dispose()),
             this.helperRealm.dispose(),
@@ -302,17 +313,7 @@ export default class Page {
      */
     async grantPermission(name, options = {}) {
         this.assertOpen();
-        const origin = options.origin ?? new URL(await this.url()).origin;
-        // about:blank and data: pages have no origin to grant to
-        if (origin === "null")
-            throw new Error("grantPermission(): needs a page on a web origin, or an explicit origin option");
-        const context = this.browserContext;
-        await this.biDiConnector.send("permissions.setPermission", {
-            descriptor: { name },
-            state: "granted",
-            origin,
-            ...(context && !context.isDefault && { userContext: context.id }),
-        });
+        await grantPermission(this.biDiConnector, () => this.url(), () => this.browserContext, name, options);
     }
     /** True once `close()` has run */
     get closed() {

package/dist/config/variables.js

@@ -18,7 +18,8 @@ export function isPassthroughKey(target, key) {
 export function createEnvFixture(environment, variables) {
     return new Proxy(Object.freeze({ ...variables }), {
         get(target, key, receiver) {
-            if (isPassthroughKey(target, key) || Object.prototype.hasOwnProperty.call(target, key))
+            if (isPassthroughKey(target, key) ||
+                Object.prototype.hasOwnProperty.call(target, key))
                 return Reflect.get(target, key, receiver);
             throw new UnknownVariableError(String(key), environment);
         },

package/dist/locator/accessible-name.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Page-side source that defines, in the scope it is pasted into:
+ *
+ * - `isHidden(el)`: not rendered or hidden from assistive technology: `display: none`, `visibility: hidden` or
+ *   `collapse`, or `aria-hidden="true"` on the element or an ancestor.
+ * - `accessibleName(el)` and `accessibleDescription(el)`: strings, whitespace collapsed and trimmed.
+ * - `roleOf(el)` (from `ROLE_OF_JS`).
+ *
+ * The name follows the accname algorithm in a simplified form, the order being: `aria-labelledby` (hidden content is
+ * read when referenced directly), `aria-label`, the native text alternative (`alt` of img / area / input[type=image],
+ * `value` of button-like inputs, the `<label>`s of a form control, `<legend>`, `<caption>`, `<figcaption>`, svg
+ * `<title>`), the content for roles that take their name from it (and always for what an embedding walks through),
+ * the `title` attribute, and for a text field its `placeholder`. Embedded form controls count by their value, and
+ * `::before` / `::after` text by its CSS content. Hidden descendants are skipped. A reference loop stops at the
+ * element already visited. The description is `aria-describedby`, else `aria-description`, else the `title` when it was not
+ * used as the name.
+ *
+ * It deliberately differs from the browser's own accessibility tree: no CSS `display` quirks for table parts, no
+ * `<summary>` or `<details>` rules, no shadow DOM or slot flattening, no `aria-owns`, and `placeholder` counts as a name
+ * for inputs in both browsers' way (Firefox and Chrome disagree there).
+ */
+export declare const ACCESSIBLE_NAME_JS: string;

package/dist/locator/accessible-name.js

@@ -0,0 +1,128 @@
+import { NAME_FROM_CONTENT_ROLES, ROLE_OF_JS } from "./role-table.js";
+/**
+ * Page-side source that defines, in the scope it is pasted into:
+ *
+ * - `isHidden(el)`: not rendered or hidden from assistive technology: `display: none`, `visibility: hidden` or
+ *   `collapse`, or `aria-hidden="true"` on the element or an ancestor.
+ * - `accessibleName(el)` and `accessibleDescription(el)`: strings, whitespace collapsed and trimmed.
+ * - `roleOf(el)` (from `ROLE_OF_JS`).
+ *
+ * The name follows the accname algorithm in a simplified form, the order being: `aria-labelledby` (hidden content is
+ * read when referenced directly), `aria-label`, the native text alternative (`alt` of img / area / input[type=image],
+ * `value` of button-like inputs, the `<label>`s of a form control, `<legend>`, `<caption>`, `<figcaption>`, svg
+ * `<title>`), the content for roles that take their name from it (and always for what an embedding walks through),
+ * the `title` attribute, and for a text field its `placeholder`. Embedded form controls count by their value, and
+ * `::before` / `::after` text by its CSS content. Hidden descendants are skipped. A reference loop stops at the
+ * element already visited. The description is `aria-describedby`, else `aria-description`, else the `title` when it was not
+ * used as the name.
+ *
+ * It deliberately differs from the browser's own accessibility tree: no CSS `display` quirks for table parts, no
+ * `<summary>` or `<details>` rules, no shadow DOM or slot flattening, no `aria-owns`, and `placeholder` counts as a name
+ * for inputs in both browsers' way (Firefox and Chrome disagree there).
+ */
+export const ACCESSIBLE_NAME_JS = `
+  ${ROLE_OF_JS}
+  const NAME_FROM_CONTENT = ${JSON.stringify(NAME_FROM_CONTENT_ROLES)};
+  const squash = (text) => String(text).replace(/\\s+/g, " ").trim();
+  const hiddenSelf = (n) => {
+    if (n.getAttribute("aria-hidden") === "true") return true;
+    const style = getComputedStyle(n);
+    return style.display === "none" || style.visibility === "hidden" || style.visibility === "collapse";
+  };
+  const isHidden = (el) => {
+    if (hiddenSelf(el)) return true;
+    for (let n = el.parentElement; n; n = n.parentElement) {
+      if (n.getAttribute("aria-hidden") === "true" || getComputedStyle(n).display === "none") return true;
+    }
+    return false;
+  };
+  const byIds = (el, attribute) => (el.getAttribute(attribute) || "").split(/\\s+/)
+    .map((id) => (id ? el.ownerDocument.getElementById(id) : null)).filter(Boolean);
+  const pseudoText = (el, which) => {
+    const content = getComputedStyle(el, which).content;
+    return content && content !== "none" && content !== "normal" && /^["']/.test(content) ? content.slice(1, -1) : "";
+  };
+  const embeddedValue = (el, role) => {
+    if (role === "textbox" || role === "searchbox" || role === "spinbutton" || role === "slider") return el.value ?? el.getAttribute("aria-valuenow") ?? "";
+    if (role === "combobox" || role === "listbox") {
+      const chosen = el.localName === "select" ? Array.from(el.selectedOptions) : [];
+      return chosen.map((option) => option.label || option.textContent).join(" ");
+    }
+    return null;
+  };
+  /** The text of a node and what it embeds. \`seen\` guards reference loops; \`top\` is the node whose name is asked for */
+  const walk = (node, seen, top) => {
+    if (node.nodeType === 3) return node.nodeValue;
+    if (node.nodeType !== 1 || seen.has(node)) return "";
+    if (node !== top && hiddenSelf(node)) return "";
+    if (["script", "style", "noscript", "template"].includes(node.localName)) return "";
+    seen.add(node);
+    const label = node !== top && (node.getAttribute("aria-label") || "").trim();
+    if (label) return label;
+    const role = roleOf(node);
+    if (node !== top) {
+      const value = embeddedValue(node, role);
+      if (value !== null) return value;
+    }
+    let text = pseudoText(node, "::before");
+    for (const child of node.childNodes) {
+      const part = walk(child, seen, top);
+      const block = child.nodeType === 1 && getComputedStyle(child).display !== "inline";
+      text += block ? " " + part + " " : part;
+    }
+    return text + pseudoText(node, "::after");
+  };
+  const fromReferences = (el, attribute, seen) => squash(byIds(el, attribute).map((ref) => {
+    const own = (ref.getAttribute("aria-label") || "").trim();
+    return own || walk(ref, new Set(seen), ref);
+  }).join(" "));
+  const labelText = (el, seen) => squash(Array.from(el.labels || []).map((label) => walk(label, new Set(seen), label)).join(" "));
+  const nativeName = (el, seen) => {
+    const tag = el.localName;
+    const type = (el.getAttribute("type") || "").toLowerCase();
+    const first = (selector) => el.querySelector(":scope > " + selector);
+    if (tag === "img" || tag === "area" || (tag === "input" && type === "image")) {
+      const alt = el.getAttribute("alt");
+      if (alt !== null && squash(alt)) return squash(alt);
+      if (tag === "input") return squash(el.getAttribute("value") || "") || labelText(el, seen);
+      return "";
+    }
+    if (tag === "input" && (type === "button" || type === "submit" || type === "reset")) {
+      const value = squash(el.getAttribute("value") || "");
+      return value || labelText(el, seen) || (type === "submit" ? "Submit" : type === "reset" ? "Reset" : "");
+    }
+    if (tag === "input" || tag === "textarea" || tag === "select" || tag === "meter" || tag === "progress" || tag === "output") return labelText(el, seen);
+    if (tag === "fieldset") { const legend = first("legend"); return legend ? squash(walk(legend, new Set(seen), legend)) : ""; }
+    if (tag === "table") { const caption = first("caption"); return caption ? squash(walk(caption, new Set(seen), caption)) : ""; }
+    if (tag === "figure") { const caption = first("figcaption"); return caption ? squash(walk(caption, new Set(seen), caption)) : ""; }
+    if (tag === "svg") { const title = first("title"); return title ? squash(title.textContent) : ""; }
+    return "";
+  };
+  /** The name and where it came from (\`title\` or \`placeholder\` matter to the description) */
+  const nameSource = (el) => {
+    const seen = new Set([el]);
+    const referenced = fromReferences(el, "aria-labelledby", seen);
+    if (referenced) return { name: referenced, source: "labelledby" };
+    const own = squash(el.getAttribute("aria-label") || "");
+    if (own) return { name: own, source: "label" };
+    const native = nativeName(el, seen);
+    if (native) return { name: native, source: "native" };
+    if (NAME_FROM_CONTENT.includes(roleOf(el)) || el.localName === "label" || el.localName === "legend" || el.localName === "caption") {
+      const content = squash(walk(el, new Set(), el));
+      if (content) return { name: content, source: "content" };
+    }
+    const title = squash(el.getAttribute("title") || "");
+    if (title) return { name: title, source: "title" };
+    const placeholder = squash(el.getAttribute("placeholder") || "");
+    if ((el.localName === "input" || el.localName === "textarea") && placeholder) return { name: placeholder, source: "placeholder" };
+    return { name: "", source: "" };
+  };
+  const accessibleName = (el) => nameSource(el).name;
+  const accessibleDescription = (el) => {
+    const referenced = fromReferences(el, "aria-describedby", new Set([el]));
+    if (referenced) return referenced;
+    const attribute = squash(el.getAttribute("aria-description") || "");
+    if (attribute) return attribute;
+    const title = squash(el.getAttribute("title") || "");
+    return title && nameSource(el).source !== "title" ? title : "";
+  };`;

package/dist/locator/action-timeout-error.js

@@ -1,4 +1,8 @@
-const SYMBOLS = { pass: "✓", fail: "✗", pending: "—" };
+const SYMBOLS = {
+    pass: "✓",
+    fail: "✗",
+    pending: "—",
+};
 function formatMessage({ action, selector, timeout, reason, checks, coveredBy, state, }) {
     switch (reason) {
         case "unreadable":