@itmetsam/samurai-framework 0.21.2 → 0.21.4

package/dist/locator/page-step.js

@@ -0,0 +1,35 @@
+import { ATTRIBUTE_LOCATE } from "./attribute-locator.js";
+import { LABEL_LOCATE } from "./label-locator.js";
+import { isNativeRole, ROLE_LOCATE, roleSearchArgs } from "./role-locator.js";
+import { TEXT_LOCATE } from "./text-locator.js";
+/** The arguments of the text-matching searches: `(value, match, ignoreCase)`, and the attribute for `attribute` steps */
+function textArgs(selector) {
+    const args = [selector.value, selector.match, selector.ignoreCase];
+    return selector.kind === "attribute" ? [...args, selector.attribute] : args;
+}
+/** The text search of a `text` step, which the browser's own `innerText` locator cannot do (or does not exist) */
+export function textSearch(selector) {
+    return { fn: TEXT_LOCATE, args: textArgs(selector) };
+}
+/**
+ * The page-side search for a step the browser cannot locate by itself: labels, attributes, RegExp texts and roles with a RegExp name or options.
+ * `undefined` when the browser's locator does the job
+ */
+export function pageSearch(selector) {
+    switch (selector.kind) {
+        case "label":
+            return { fn: LABEL_LOCATE, args: textArgs(selector) };
+        case "attribute":
+            return { fn: ATTRIBUTE_LOCATE, args: textArgs(selector) };
+        case "text":
+            return typeof selector.value === "string"
+                ? undefined
+                : textSearch(selector);
+        case "role":
+            return isNativeRole(selector)
+                ? undefined
+                : { fn: ROLE_LOCATE, args: [...roleSearchArgs(selector)] };
+        default:
+            return undefined;
+    }
+}

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

@@ -0,0 +1,65 @@
+/** What `getByRole` takes beside the role */
+export interface RoleOptions {
+    /**
+     * The accessible name. A string is matched in full and case-sensitively (whitespace normalised) unless `exact` is
+     * false; a RegExp is tested on the name as written (flags kept, `g` and `y` dropped) and ignores `exact`
+     */
+    name?: string | RegExp;
+    /**
+     * `true` (the default) keeps the full-string, case-sensitive name match; `false` switches this call to Playwright's
+     * matching: a case-insensitive substring. This is the one intentional difference from Playwright, whose default is
+     * the case-insensitive substring. Does not apply to a RegExp
+     * @default true
+     */
+    exact?: boolean;
+    /** The heading level: `h1` to `h6`, else `aria-level` */
+    level?: number;
+    /** `checked` of a checkbox, radio or switch, from the element's state or `aria-checked`; `"mixed"` for indeterminate */
+    checked?: boolean | "mixed";
+    /** `aria-pressed` of a toggle button */
+    pressed?: boolean | "mixed";
+    /** `aria-expanded` */
+    expanded?: boolean;
+    /** `selected` of an option, or `aria-selected` */
+    selected?: boolean;
+    /** Disabled by `disabled` (also through a disabled fieldset) or by `aria-disabled` on it or an ancestor */
+    disabled?: boolean;
+    /** Also match elements that are not rendered or are hidden from assistive technology (`aria-hidden`). @default false */
+    includeHidden?: boolean;
+}
+/** A `role` step: the options that are not their default, so the plain steps stay `{ kind, role, name }` */
+export interface RoleSelector extends Omit<RoleOptions, "exact" | "includeHidden"> {
+    kind: "role";
+    role: string;
+    /** Present (as `false`) only when the name is matched loosely */
+    exact?: false;
+    /** Present (as `true`) only when hidden elements count */
+    includeHidden?: true;
+}
+/** The `role` step for `getByRole(role, options)`; `nonEmpty` rejects a blank role */
+export declare function buildRoleSelector(role: string, options: RoleOptions): RoleSelector;
+/** True when the browser's accessibility locator does the whole job: no RegExp, no loose match, no state, nothing hidden */
+export declare function isNativeRole(selector: RoleSelector): boolean;
+/** The options of a step as the page-side search takes them */
+export declare function roleSearchArgs(selector: RoleSelector): readonly [string, {
+    /** Present (as `false`) only when the name is matched loosely */
+    exact?: false;
+    /** Present (as `true`) only when hidden elements count */
+    includeHidden?: true;
+    name?: (string | RegExp) | undefined;
+    level?: number | undefined;
+    checked?: boolean | "mixed" | undefined;
+    pressed?: boolean | "mixed" | undefined;
+    expanded?: boolean | undefined;
+    selected?: boolean | undefined;
+    disabled?: boolean | undefined;
+}];
+/**
+ * Function declaration run in the page as `(starts, role, options)`; returns the elements with the role that pass
+ * every option, unique and in document order. This is the search for what the browser's accessibility locator cannot
+ * do (see `isNativeRole`); it is the same in Firefox and Chrome, which differ on ignored nodes (Chrome's locator
+ * also returns `aria-hidden` elements). The role is the `role` attribute's first token, else the implicit role (`ROLE_OF_JS`).
+ *
+ * A string, so the transpiler cannot inject helpers that do not exist in the page.
+ */
+export declare const ROLE_LOCATE: string;

package/dist/locator/role-locator.js

@@ -0,0 +1,125 @@
+import { ACCESSIBLE_NAME_JS } from "./accessible-name.js";
+import { DOCUMENT_ORDER_JS, MATCHING_JS, ROOTS_JS } from "./page-search.js";
+const STATE_OPTIONS = [
+    "level",
+    "checked",
+    "pressed",
+    "expanded",
+    "selected",
+    "disabled",
+];
+function checkOption(name, ok, expected) {
+    if (!ok)
+        throw new TypeError(`getByRole(): ${name} must be ${expected}`);
+}
+/** The `role` step for `getByRole(role, options)`; `nonEmpty` rejects a blank role */
+export function buildRoleSelector(role, options) {
+    if (typeof options !== "object" || options === null) {
+        throw new TypeError("getByRole(): options must be an object");
+    }
+    const { name, exact = true, includeHidden = false } = options;
+    const step = { kind: "role", role };
+    if (name !== undefined) {
+        checkOption("name", typeof name === "string" || name instanceof RegExp, "a string or a RegExp");
+        step.name =
+            name instanceof RegExp
+                ? new RegExp(name.source, name.flags.replace(/[gy]/g, ""))
+                : name;
+    }
+    if (exact === false)
+        step.exact = false;
+    if (includeHidden === true)
+        step.includeHidden = true;
+    const { level, checked, pressed, expanded, selected, disabled } = options;
+    checkOption("level", level === undefined || (Number.isInteger(level) && level >= 1), "a positive integer");
+    for (const [key, value] of [
+        ["checked", checked],
+        ["pressed", pressed],
+    ]) {
+        checkOption(key, value === undefined || typeof value === "boolean" || value === "mixed", 'a boolean or "mixed"');
+    }
+    for (const [key, value] of [
+        ["expanded", expanded],
+        ["selected", selected],
+        ["disabled", disabled],
+    ]) {
+        checkOption(key, value === undefined || typeof value === "boolean", "a boolean");
+    }
+    for (const key of STATE_OPTIONS) {
+        if (options[key] !== undefined)
+            Object.assign(step, { [key]: options[key] });
+    }
+    return step;
+}
+/** True when the browser's accessibility locator does the whole job: no RegExp, no loose match, no state, nothing hidden */
+export function isNativeRole(selector) {
+    return ((selector.name === undefined || typeof selector.name === "string") &&
+        selector.exact === undefined &&
+        selector.includeHidden === undefined &&
+        STATE_OPTIONS.every((key) => selector[key] === undefined));
+}
+/** The options of a step as the page-side search takes them */
+export function roleSearchArgs(selector) {
+    const { kind: _kind, role: _role, ...options } = selector;
+    return [selector.role, options];
+}
+/** Page-side source: whether `el` has the state `want` in `property` (`checked`, `pressed`, ...) */
+const STATES_JS = `
+  const tokenState = (value) => (value === "true" ? true : value === "mixed" ? "mixed" : false);
+  const ancestorsOrSelf = function* (el) { for (let n = el; n; n = n.parentElement) yield n; };
+  const stateOf = {
+    checked: (el) => {
+      const type = (el.getAttribute("type") || "").toLowerCase();
+      if (el.localName === "input" && (type === "checkbox" || type === "radio")) return el.indeterminate ? "mixed" : el.checked;
+      return tokenState(el.getAttribute("aria-checked"));
+    },
+    pressed: (el) => tokenState(el.getAttribute("aria-pressed")),
+    expanded: (el) => el.getAttribute("aria-expanded") === "true" || (el.localName === "details" && el.open === true),
+    selected: (el) => (el.localName === "option" ? el.selected : el.getAttribute("aria-selected") === "true"),
+    disabled: (el) => {
+      if (typeof el.matches === "function" && el.matches(":disabled")) return true;
+      for (const n of ancestorsOrSelf(el)) if (n.getAttribute("aria-disabled") === "true") return true;
+      return false;
+    },
+    level: (el) => {
+      const heading = /^h([1-6])$/.exec(el.localName);
+      const own = Number(el.getAttribute("aria-level"));
+      return own > 0 ? own : heading ? Number(heading[1]) : 0;
+    },
+  };`;
+/**
+ * Function declaration run in the page as `(starts, role, options)`; returns the elements with the role that pass
+ * every option, unique and in document order. This is the search for what the browser's accessibility locator cannot
+ * do (see `isNativeRole`); it is the same in Firefox and Chrome, which differ on ignored nodes (Chrome's locator
+ * also returns `aria-hidden` elements). The role is the `role` attribute's first token, else the implicit role (`ROLE_OF_JS`).
+ *
+ * A string, so the transpiler cannot inject helpers that do not exist in the page.
+ */
+export const ROLE_LOCATE = `(starts, wantedRole, options) => {
+  ${ACCESSIBLE_NAME_JS}
+  ${STATES_JS}
+  const hasName = options.name !== undefined;
+  const value = hasName ? options.name : "";
+  const match = options.exact === false ? "partial" : "full";
+  const ignoreCase = options.exact === false;
+  ${MATCHING_JS}
+  ${ROOTS_JS}
+  const role = wantedRole.toLowerCase();
+  const seen = new Set();
+  const matches = [];
+  for (const root of roots) {
+    for (const el of root.querySelectorAll("*")) {
+      if (seen.has(el)) continue;
+      seen.add(el);
+      if (roleOf(el) !== role) continue;
+      if (!options.includeHidden && isHidden(el)) continue;
+      let ok = true;
+      for (const key of ["checked", "pressed", "expanded", "selected", "disabled", "level"]) {
+        if (options[key] !== undefined && stateOf[key](el) !== options[key]) { ok = false; break; }
+      }
+      if (ok && hasName && !textMatches(accessibleName(el))) ok = false;
+      if (ok) matches.push(el);
+    }
+  }
+  return matches.sort(${DOCUMENT_ORDER_JS});
+}`;

package/dist/locator/role-table.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The implicit ARIA role of an element, for the in-page role search (`getByRole` with a RegExp name, `exact: false`,
+ * or a state option). A table of tags, a few attribute rules and a few context rules, in the spirit of HTML-AAM;
+ * the browser's own accessibility tree is the reference for the plain `getByRole(role, { name })`, which does not use this.
+ */
+/** Tags with one role whatever their attributes */
+export declare const TAG_ROLES: Readonly<Record<string, string>>;
+/**
+ * Roles whose accessible name may come from their content (ARIA 1.2 "name from: contents"), which
+ * `accessibleName` reads for the element itself, not only for what it embeds.
+ */
+export declare const NAME_FROM_CONTENT_ROLES: readonly string[];
+/**
+ * Page-side source: `roleOf(el)` is the role of an element: the first token of `role=""`, else the implicit role,
+ * else `""` (no role). Reads only `localName`, `getAttribute`, `hasAttribute` and `parentElement`, so a unit test can
+ * run it on a fake element. `div` and `span` are `generic`.
+ */
+export declare const ROLE_OF_JS: string;

package/dist/locator/role-table.js

@@ -0,0 +1,190 @@
+/**
+ * The implicit ARIA role of an element, for the in-page role search (`getByRole` with a RegExp name, `exact: false`,
+ * or a state option). A table of tags, a few attribute rules and a few context rules, in the spirit of HTML-AAM;
+ * the browser's own accessibility tree is the reference for the plain `getByRole(role, { name })`, which does not use this.
+ */
+/** Tags with one role whatever their attributes */
+export const TAG_ROLES = {
+    address: "group",
+    article: "article",
+    aside: "complementary",
+    blockquote: "blockquote",
+    button: "button",
+    caption: "caption",
+    code: "code",
+    dd: "definition",
+    del: "deletion",
+    details: "group",
+    dfn: "term",
+    dialog: "dialog",
+    dt: "term",
+    em: "emphasis",
+    fieldset: "group",
+    figure: "figure",
+    h1: "heading",
+    h2: "heading",
+    h3: "heading",
+    h4: "heading",
+    h5: "heading",
+    h6: "heading",
+    hgroup: "group",
+    hr: "separator",
+    ins: "insertion",
+    li: "listitem",
+    main: "main",
+    mark: "mark",
+    menu: "list",
+    meter: "meter",
+    nav: "navigation",
+    ol: "list",
+    optgroup: "group",
+    option: "option",
+    output: "status",
+    p: "paragraph",
+    progress: "progressbar",
+    search: "search",
+    strong: "strong",
+    sub: "subscript",
+    sup: "superscript",
+    table: "table",
+    tbody: "rowgroup",
+    tfoot: "rowgroup",
+    thead: "rowgroup",
+    textarea: "textbox",
+    time: "time",
+    tr: "row",
+    ul: "list",
+};
+/** `<input type>` to role; an unknown type is a textbox, `hidden` and `file` have none */
+const INPUT_ROLES = {
+    button: "button",
+    checkbox: "checkbox",
+    image: "button",
+    number: "spinbutton",
+    radio: "radio",
+    range: "slider",
+    reset: "button",
+    search: "searchbox",
+    submit: "button",
+};
+/** Input types that have no role at all */
+const INPUT_TYPES_WITHOUT_ROLE = [
+    "hidden",
+    "file",
+    "color",
+    "date",
+    "datetime-local",
+    "month",
+    "time",
+    "week",
+];
+/** Landmarks that stop a `header` / `footer` from being the page's banner / content info */
+const SECTIONING_TAGS = [
+    "article",
+    "aside",
+    "main",
+    "nav",
+    "section",
+];
+const SECTIONING_ROLES = [
+    "article",
+    "complementary",
+    "main",
+    "navigation",
+    "region",
+];
+/**
+ * Roles whose accessible name may come from their content (ARIA 1.2 "name from: contents"), which
+ * `accessibleName` reads for the element itself, not only for what it embeds.
+ */
+export const NAME_FROM_CONTENT_ROLES = [
+    "button",
+    "cell",
+    "checkbox",
+    "columnheader",
+    "gridcell",
+    "heading",
+    "link",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "radio",
+    "row",
+    "rowheader",
+    "switch",
+    "tab",
+    "tooltip",
+    "treeitem",
+];
+/**
+ * Page-side source: `roleOf(el)` is the role of an element: the first token of `role=""`, else the implicit role,
+ * else `""` (no role). Reads only `localName`, `getAttribute`, `hasAttribute` and `parentElement`, so a unit test can
+ * run it on a fake element. `div` and `span` are `generic`.
+ */
+export const ROLE_OF_JS = `
+  const TAG_ROLES = ${JSON.stringify(TAG_ROLES)};
+  const INPUT_ROLES = ${JSON.stringify(INPUT_ROLES)};
+  const NO_ROLE_INPUTS = ${JSON.stringify(INPUT_TYPES_WITHOUT_ROLE)};
+  const SECTIONING_TAGS = ${JSON.stringify(SECTIONING_TAGS)};
+  const SECTIONING_ROLES = ${JSON.stringify(SECTIONING_ROLES)};
+  const hasText = (el, name) => (el.getAttribute(name) || "").trim() !== "";
+  const isNamed = (el) => hasText(el, "aria-label") || hasText(el, "aria-labelledby");
+  const insideSectioning = (el) => {
+    for (let n = el.parentElement; n; n = n.parentElement) {
+      const explicit = (n.getAttribute("role") || "").trim().split(/\\s+/)[0];
+      if (SECTIONING_TAGS.includes(n.localName) || SECTIONING_ROLES.includes(explicit)) return true;
+    }
+    return false;
+  };
+  const inGrid = (el) => {
+    for (let n = el.parentElement; n; n = n.parentElement) {
+      const explicit = (n.getAttribute("role") || "").trim().split(/\\s+/)[0];
+      if (explicit === "grid" || explicit === "treegrid") return true;
+    }
+    return false;
+  };
+  const implicitRole = (el) => {
+    const tag = el.localName;
+    switch (tag) {
+      case "a":
+      case "area":
+        return el.hasAttribute("href") ? "link" : tag === "a" ? "generic" : "";
+      case "input": {
+        const type = (el.getAttribute("type") || "text").toLowerCase();
+        if (NO_ROLE_INPUTS.includes(type)) return "";
+        const mapped = INPUT_ROLES[type];
+        if (mapped) return type === "search" && el.hasAttribute("list") ? "combobox" : mapped;
+        return el.hasAttribute("list") ? "combobox" : "textbox";
+      }
+      case "select":
+        return el.hasAttribute("multiple") || Number(el.getAttribute("size")) > 1 ? "listbox" : "combobox";
+      case "datalist":
+        return "listbox";
+      case "img":
+        return el.getAttribute("alt") === "" && !el.hasAttribute("title") ? "presentation" : "img";
+      case "section":
+        return isNamed(el) ? "region" : "";
+      case "form":
+        return isNamed(el) ? "form" : "";
+      case "header":
+        return insideSectioning(el) ? "" : "banner";
+      case "footer":
+        return insideSectioning(el) ? "" : "contentinfo";
+      case "td":
+        return inGrid(el) ? "gridcell" : "cell";
+      case "th": {
+        const scope = (el.getAttribute("scope") || "").toLowerCase();
+        return scope === "row" || scope === "rowgroup" ? "rowheader" : "columnheader";
+      }
+      case "div":
+      case "span":
+        return "generic";
+      default:
+        return TAG_ROLES[tag] ?? "";
+    }
+  };
+  const roleOf = (el) => {
+    const explicit = (el.getAttribute("role") || "").trim().split(/\\s+/)[0];
+    return explicit ? explicit.toLowerCase() : implicitRole(el);
+  };`;

package/dist/locator/select-actions.d.ts

@@ -0,0 +1,13 @@
+import type { ActionOptions } from "./actionability.js";
+import { type ElementAccess } from "./element-access.js";
+/** One option to select: a string matches the option's value or its label; an object must match every field it names */
+export type SelectOptionValue = string | {
+    value?: string;
+    label?: string;
+    index?: number;
+};
+/**
+ * Selects the options of a `<select>` (or `<select multiple>`, whose selection it replaces) and returns the values
+ * now selected. Waits until the select is visible and enabled, and until every wanted option exists.
+ */
+export declare function selectOptions(access: ElementAccess, values: SelectOptionValue | SelectOptionValue[], options?: ActionOptions): Promise<string[]>;

package/dist/locator/select-actions.js

@@ -0,0 +1,73 @@
+import { resolveTimeout } from "../config/timeouts.js";
+import { waitUntil, WaitTimeoutError } from "../wait/wait-until.js";
+import { callOnExistingElement } from "./element-access.js";
+import { SELECT_CHECKS } from "./page-scripts.js";
+/**
+ * Body run in the page as `(el, wanted) => { ... }`: selects the matching options of a `<select>`, then fires
+ * `input` and `change` once each. Selects nothing and reports what is missing when a wanted option is not there.
+ */
+const SELECT_BODY = `
+  if (el.tagName !== "SELECT") return { notSelect: true };
+  const options = Array.from(el.options);
+  const matches = (option, want, index) =>
+    (want.any === undefined || option.value === want.any || option.label === want.any) &&
+    (want.value === undefined || option.value === want.value) &&
+    (want.label === undefined || option.label === want.label) &&
+    (want.index === undefined || index === want.index);
+  const missing = wanted.filter((want) => !options.some((option, i) => matches(option, want, i)));
+  if (missing.length) return { missing };
+  let chosen = options.filter((option, i) => wanted.some((want) => matches(option, want, i)));
+  if (!el.multiple) chosen = chosen.slice(0, 1);
+  el.focus();
+  for (const option of options) option.selected = chosen.includes(option);
+  el.dispatchEvent(new Event("input", { bubbles: true, composed: true }));
+  el.dispatchEvent(new Event("change", { bubbles: true }));
+  return { values: Array.from(el.selectedOptions, (option) => option.value) };`;
+function normalise(values) {
+    const list = Array.isArray(values) ? values : [values];
+    return list.map((item) => {
+        if (typeof item === "string")
+            return { any: item };
+        if (typeof item !== "object" || item === null) {
+            throw new TypeError(`selectOption(): expected a string, { value, label, index } or an array of those, got ${item === null ? "null" : typeof item}`);
+        }
+        const { value, label, index } = item;
+        return {
+            ...(value !== undefined && { value }),
+            ...(label !== undefined && { label }),
+            ...(index !== undefined && { index }),
+        };
+    });
+}
+function describeWanted(want) {
+    return want.any !== undefined
+        ? JSON.stringify(want.any)
+        : JSON.stringify(want);
+}
+/**
+ * Selects the options of a `<select>` (or `<select multiple>`, whose selection it replaces) and returns the values
+ * now selected. Waits until the select is visible and enabled, and until every wanted option exists.
+ */
+export async function selectOptions(access, values, options) {
+    const wanted = normalise(values);
+    await access.waitForActionable("selectOption", SELECT_CHECKS, { scroll: true, hitTest: false }, options);
+    const timeout = await resolveTimeout(options?.timeout);
+    const attempt = () => callOnExistingElement(access, `return ((el, wanted) => { ${SELECT_BODY} })(el, ${JSON.stringify(wanted)});`, "selectOption");
+    let outcome;
+    try {
+        outcome = await waitUntil(attempt, (current) => !("missing" in current), {
+            timeout,
+        });
+    }
+    catch (err) {
+        if (!(err instanceof WaitTimeoutError))
+            throw err;
+        const last = err.last;
+        const missing = last && "missing" in last ? last.missing : [];
+        throw new Error(`selectOption(): no option matches ${missing.map(describeWanted).join(", ")} in ${access.selector} within ${timeout}ms`);
+    }
+    if ("notSelect" in outcome) {
+        throw new Error(`selectOption(): ${access.selector} is not a <select>`);
+    }
+    return outcome.values;
+}

package/dist/locator/selector-string.d.ts

@@ -0,0 +1,7 @@
+import { type Selector } from "./selector.js";
+/**
+ * The selector step for the string `locator(…)` takes. `xpath=…` and `css=…` name the kind. A string starting
+ * with `//`, `/`, `(`, `..` or `./` is an xpath, as is a relative path that cannot be css (`a[@id='x']`,
+ * `button[text()='Go']`). Anything else is css (`input[name='x']`, `a, button`, `main`).
+ */
+export declare function selectorFromString(value: string): Selector;

package/dist/locator/selector-string.js

@@ -0,0 +1,27 @@
+import { cssSelector, xpathSelector } from "./selector.js";
+/** Prefixes that make a string an xpath, as in Playwright: `//a`, `/html`, `(//a)[2]`, `../x`, `./x` */
+const XPATH_START = /^(?:\/|\(|\.\.|\.\/)/;
+/**
+ * What only an xpath written without a leading `//` (the older form of `locator("a[@id='x']")`) has and a
+ * css selector cannot: `@`, `/`, `::`, a function call (a `(` that does not follow a `:pseudo-class`) or a
+ * positional predicate (`li[2]`, `li[last()]`). Quoted text is ignored, so `a[href^='/x']` stays css.
+ */
+const RELATIVE_XPATH = /@|\/|::|(?<!:[\w-]+)\(|\[\s*(?:\d|last\b)/;
+const QUOTED = /(["'])(?:\\.|(?!\1).)*\1/g;
+/**
+ * The selector step for the string `locator(…)` takes. `xpath=…` and `css=…` name the kind. A string starting
+ * with `//`, `/`, `(`, `..` or `./` is an xpath, as is a relative path that cannot be css (`a[@id='x']`,
+ * `button[text()='Go']`). Anything else is css (`input[name='x']`, `a, button`, `main`).
+ */
+export function selectorFromString(value) {
+    const text = value.trim();
+    if (text.startsWith("xpath="))
+        return xpathSelector(text.slice(6));
+    if (text.startsWith("css="))
+        return cssSelector(text.slice(4));
+    if (text === "" || XPATH_START.test(text))
+        return xpathSelector(text);
+    return RELATIVE_XPATH.test(text.replace(QUOTED, "''"))
+        ? xpathSelector(text)
+        : cssSelector(text);
+}

package/dist/locator/selector.d.ts

@@ -1,4 +1,5 @@
 import type { NodeLocator } from "../types/bidi-modules/browsing-context.js";
+import { type RoleOptions, type RoleSelector } from "./role-locator.js";
 /** One step of a locator. A locator is a chain of them, each searching inside the previous step's matches */
 export type Selector = {
     kind: "xpath";
@@ -8,45 +9,76 @@ export type Selector = {
     value: string;
 } | ({
     kind: "text";
-} & TextMatch) | {
-    kind: "role";
-    role: string;
-    name?: string;
-}
+} & TextMatch) | RoleSelector
 /** Form controls named by a `<label>`, `aria-labelledby` or `aria-label` whose text matches */
  | ({
     kind: "label";
 } & TextMatch)
+/** Elements whose `placeholder`, `alt` or `title` attribute matches */
+ | ({
+    kind: "attribute";
+    attribute: TextAttribute;
+} & TextMatch)
 /** Elements whose `data-testid` attribute equals `value` */
  | {
     kind: "testid";
     value: string;
 }
-/** Picks the n-th (0-based) of everything the chain so far matches; `all()` builds these */
+/** Picks the n-th (0-based) of everything the chain so far matches; a negative index counts from the end. `nth()` and `all()` build these */
  | {
     kind: "nth";
     index: number;
+}
+/** Keeps the elements the chain so far matched that pass every given test (see `filterSelector`) */
+ | ({
+    kind: "filter";
+} & FilterTests)
+/** The elements two whole chains both match (`and`), or either matches (`or`, in document order); built by `and()` and `or()` */
+ | {
+    kind: "and" | "or";
+    left: readonly Selector[];
+    right: readonly Selector[];
 };
-/** What a text or label step looks for */
+/** A text test of a filter: a string is a case-insensitive substring, a RegExp is tested on the element's text */
+export type TextCriterion = string | RegExp;
+/** The tests of a `filter` step; `has` and `hasNot` are chains searched inside each candidate */
+export interface FilterTests {
+    hasText?: TextCriterion;
+    hasNotText?: TextCriterion;
+    has?: readonly Selector[];
+    hasNot?: readonly Selector[];
+}
+/** The attributes `getByPlaceholder`, `getByAltText` and `getByTitle` look at */
+export type TextAttribute = "placeholder" | "alt" | "title";
+/** What a text, label or attribute step looks for; a RegExp is tested as written (`match` and `ignoreCase` do not apply) */
 interface TextMatch {
-    value: string;
+    value: string | RegExp;
     match: "full" | "partial";
     ignoreCase: boolean;
 }
 export interface TextOptions {
-    /** @default "full" */
+    /**
+     * `true` (the default) keeps the full-string, case-sensitive match; `false` switches this call to Playwright's
+     * matching: a case-insensitive substring, whitespace normalised. Does not apply to a RegExp. This is the one
+     * intentional difference from Playwright, whose default is the case-insensitive substring.
+     * @default true
+     */
+    exact?: boolean;
+    /** @default "full", or "partial" with `exact: false` */
     match?: "full" | "partial";
-    /** @default false */
+    /** @default false, or true with `exact: false` */
     ignoreCase?: boolean;
 }
+/** What `getByPlaceholder`, `getByAltText` and `getByTitle` take */
+export type ExactOption = Pick<TextOptions, "exact">;
 export declare function xpathSelector(value: string): Selector;
 export declare function cssSelector(value: string): Selector;
-export declare function textSelector(value: string, options?: TextOptions): Selector;
-export declare function labelSelector(value: string, options?: TextOptions): Selector;
+export declare function nthSelector(index: number): Selector;
+export declare function textSelector(value: string | RegExp, options?: TextOptions): Selector;
+export declare function labelSelector(value: string | RegExp, options?: TextOptions): Selector;
+export declare function attributeSelector(attribute: TextAttribute, value: string | RegExp, options?: ExactOption): Selector;
 export declare function testIdSelector(value: string): Selector;
-export declare function roleSelector(role: string, { name }?: {
-    name?: string;
-}): Selector;
+export declare function roleSelector(role: string, options?: RoleOptions): Selector;
 /**
  * Normalises an xpath. Relative xpaths get a leading `//` (`.//` when `scoped`, i.e. searching inside
  * a parent match). Absolute (`/…`), grouped (`(…)`) and context (`./…`) paths are kept; in a scoped