@itmetsam/samurai-framework 0.21.2 → 0.21.4

package/dist/locator/locator.js

@@ -1,51 +1,57 @@
-import { BiDiError } from "../transport/bidi-error.js";
-import { callFunction, ScriptError } from "../script/call-function.js";
 import { ElementHandle } from "../script/element-handle.js";
-import { takeScreenshot, } from "../browser/screenshot.js";
-import { probeState, waitForActionable, waitForState, } from "./actionability.js";
+import { waitForActionable, waitForState, } from "./actionability.js";
+import { setChecked } from "./check-actions.js";
 import { ChainResolver } from "./chain-resolver.js";
-import { dropFiles, setInputFiles, } from "./file-actions.js";
-import { describeType, } from "./element-state.js";
-import { bindOutput } from "../wait/output-sink.js";
-import { cssPropertyName, IS_CHECKED_BODY } from "./element-reads.js";
-import { clickRect, DEFAULT_PAUSE_MS, NAMED_KEYS, pause, pressKey, typeText, } from "./input-actions.js";
-import { CLICK_CHECKS, FILL_CHECKS, PRESS_CHECKS, SCREENSHOT_CHECKS, ATTACHED_ONLY, } from "./page-scripts.js";
-import { cssSelector, describeChain, describeSelector, labelSelector, roleSelector, testIdSelector, textSelector, xpathSelector, } from "./selector.js";
+import { callInPage, noElementError, requireElement, } from "./element-access.js";
+import { clickElement, fillElement, focusElement, pressOnElement, screenshotElement, } from "./element-actions.js";
+import { readAccessibleDescription, readAccessibleName, readAllInnerTexts, readAllTextContents, readAttribute, readBoundingBox, readBoundingClientRect, readClassAttribute, readCssValue, readEnabledState, readInnerHTML, readInnerText, readInputValue, readIsChecked, readIsEditable, readIsEnabled, readIsVisible, readTextContent, } from "./element-reads.js";
+import { evaluateOnAll, evaluateOnElement } from "./evaluate.js";
+import { dropFiles, setInputFiles } from "./file-actions.js";
+import { DEFAULT_PAUSE_MS, pause } from "./input-actions.js";
+import { NOT_STRICT, strictViolation, } from "./strict-mode.js";
+import { attributeSelector, cssSelector, describeChain, describeSelector, labelSelector, nthSelector, roleSelector, testIdSelector, textSelector, } from "./selector.js";
+import { selectOptions } from "./select-actions.js";
+import { filterSelector } from "./filter-step.js";
+import { selectorFromString } from "./selector-string.js";
 export default class Locator {
     /**
      * `selector` is an xpath, or a chain of selector steps that each search inside the previous step's matches.
      * `helpers` is the page's helper realm. With it the actionability probe is installed once per
      * document and called by name; without it (a locator built by hand) the probe source is sent on every poll.
      * `alternatives` are fallback locators tried in order whenever this chain matches nothing (see `withFallbacks`).
+     * `strictness` says whether actions and reads throw when the locator matches several elements (see `strict`); default no.
      */
-    constructor(selector, biDiConnector, contextId, helpers, alternatives = []) {
+    constructor(selector, biDiConnector, contextId, helpers, alternatives = [], strictness = NOT_STRICT) {
         this.chain =
-            typeof selector === "string" ? [xpathSelector(selector)] : selector;
+            typeof selector === "string" ? [selectorFromString(selector)] : selector;
         this.biDiConnector = biDiConnector;
         this.contextId = contextId;
         this.helpers = helpers;
         this.alternatives = alternatives;
+        this.strictness = strictness;
         const locator = this;
         this.actionability = {
-            resolveOne: () => this.resolveOne(),
-            call: (fn, args, sandbox) => this.call(fn, args, sandbox),
+            resolveOne: (method) => this.resolveOne(method),
+            call: (fn, args, sandbox) => this.access.call(fn, args, sandbox),
             get selector() {
                 return locator.selector;
             },
             helpers,
         };
-        this.elementContext = {
+        this.access = {
             connector: biDiConnector,
             contextId,
             get selector() {
                 return locator.selector;
             },
-            call: (fn, args, sandbox) => this.call(fn, args, sandbox),
+            resolveOne: (method) => this.resolveOne(method),
+            resolveAll: () => this.resolve(),
+            call: (fn, args, sandbox) => callInPage(this.access, fn, args, sandbox),
             waitForActionable: (action, checks, probe, options) => this.waitForActionable(action, checks, probe, options),
-            requireElement: () => this.requireElement(),
-            noElementError: () => this.noElementError(),
+            requireElement: () => requireElement(this.access),
+            noElementError: () => noElementError(this.access.selector),
         };
-        this.resolver = new ChainResolver(biDiConnector, contextId, (fn, args, sandbox) => this.call(fn, args, sandbox));
+        this.resolver = new ChainResolver(biDiConnector, contextId, (fn, args, sandbox) => this.access.call(fn, args, sandbox));
     }
     /**
      * The description of this locator used in error messages, e.g. `//form >> role=button[name="Save"]`;
@@ -59,7 +65,7 @@ export default class Locator {
     }
     /** Steps that keep the fallbacks: each fallback gets the same step, so "inside A or B" stays meaningful */
     child(step) {
-        return new Locator([...this.chain, step], this.biDiConnector, this.contextId, this.helpers, this.alternatives.map((alt) => alt.child(step)));
+        return new Locator([...this.chain, step], this.biDiConnector, this.contextId, this.helpers, this.alternatives.map((alt) => alt.child(step)), this.strictness);
     }
     /**
      * A locator that tries this one first and, whenever it matches nothing, each of `fallbacks` in order;
@@ -70,7 +76,17 @@ export default class Locator {
      *  page.getByTestId("save").withFallbacks(page.getByRole("button", { name: "Save" }), page.getByText("Save"));
      */
     withFallbacks(...fallbacks) {
-        return new Locator(this.chain, this.biDiConnector, this.contextId, this.helpers, [...this.alternatives, ...fallbacks]);
+        return new Locator(this.chain, this.biDiConnector, this.contextId, this.helpers, [...this.alternatives, ...fallbacks], this.strictness);
+    }
+    /**
+     * This locator, strict or not whatever the page and the config say: a strict locator makes actions and reads
+     * (`click`, `fill`, `textContent`, ...) throw `name(): strict mode violation, N elements match ...` when it
+     * matches several elements, instead of using the first. Steps added to it stay strict. See config `use.strictSelectors`
+     * @example
+     *  await page.locator("li").strict().click(); // throws when there is more than one li
+     */
+    strict(enabled = true) {
+        return new Locator(this.chain, this.biDiConnector, this.contextId, this.helpers, this.alternatives, () => Promise.resolve(enabled));
     }
     /**
      * Which locator found elements the last time this one searched: index 0 is the primary, 1 the first
@@ -79,30 +95,96 @@ export default class Locator {
     get matchedBy() {
         return this.matched;
     }
-    /** Elements matching the label text (`<label>`, `aria-labelledby`, `aria-label`), inside this locator's matches */
+    /** Elements matching the label text (`<label>`, `aria-labelledby`, `aria-label`), inside this locator's matches. See `TextOptions` for `exact` and RegExp */
     getByLabel(text, options) {
         return this.child(labelSelector(text, options));
     }
+    /** Elements whose `placeholder` matches, inside this locator's matches. See `TextOptions` for `exact` and RegExp */
+    getByPlaceholder(text, options) {
+        return this.child(attributeSelector("placeholder", text, options));
+    }
+    /** Elements whose `alt` text matches (images, areas, image inputs), inside this locator's matches. See `TextOptions` */
+    getByAltText(text, options) {
+        return this.child(attributeSelector("alt", text, options));
+    }
+    /** Elements whose `title` attribute matches, inside this locator's matches. See `TextOptions` */
+    getByTitle(text, options) {
+        return this.child(attributeSelector("title", text, options));
+    }
     /** Elements whose `data-testid` attribute equals `testId`, inside this locator's matches */
     getByTestId(testId) {
         return this.child(testIdSelector(testId));
     }
-    /** Elements matching `xpath` inside this locator's matches (relative and `//` paths search inside them) */
-    locator(xpath) {
-        return this.child(xpathSelector(xpath));
+    /**
+     * Elements matching `selector` inside this locator's matches. An xpath (`//x`, `./x`, `xpath=…`, or an older
+     * relative one such as `a[@id='x']`) searches inside them; anything else is css (`css=` is accepted).
+     * `options` filter the matches, as `filter()` does
+     */
+    locator(selector, options) {
+        const found = this.child(selectorFromString(selector));
+        return options === undefined ? found : found.filter(options);
     }
     /** Elements matching the CSS selector inside this locator's matches */
     getByCss(css) {
         return this.child(cssSelector(css));
     }
-    /** Elements whose text matches, inside this locator's matches. Exact match unless `match: "partial"` */
+    /** Elements whose text matches, inside this locator's matches. Exact match unless `match: "partial"` or `exact: false`; a RegExp is tested as written */
     getByText(text, options) {
         return this.child(textSelector(text, options));
     }
-    /** Elements with the ARIA role (and accessible name, when given), inside this locator's matches */
+    /** Elements with the ARIA role (and accessible name and state, when given), inside this locator's matches. See `RoleOptions` */
     getByRole(role, options) {
         return this.child(roleSelector(role, options));
     }
+    /** The n-th (0-based) match, in document order; a negative index counts from the end (`-1` is the last). Matches nothing when out of range */
+    nth(index) {
+        return this.child(nthSelector(index));
+    }
+    /**
+     * The matches that pass the tests, in their order. `hasText` keeps elements whose text contains the string
+     * (case-insensitive, whitespace collapsed; this is Playwright's rule, the `getBy*` text matching is unchanged)
+     * or matches the RegExp; `has` keeps elements containing a match of the locator, searched inside them.
+     * @example
+     *  await page.locator("li").filter({ hasText: "paid", has: page.getByRole("button") }).first().click();
+     */
+    filter(options) {
+        return this.child(filterSelector(options, (inner, option) => inner.chainFor("filter()", option)));
+    }
+    /** The elements both this locator and `other` match, in this locator's order */
+    and(other) {
+        return this.combined("and", other);
+    }
+    /** The elements either this locator or `other` matches, in document order, each once */
+    or(other) {
+        return this.combined("or", other);
+    }
+    combined(kind, other) {
+        if (other.contextId !== this.contextId) {
+            throw new TypeError(`${kind}(): the locators belong to different pages`);
+        }
+        return new Locator([
+            {
+                kind,
+                left: this.chainFor(`${kind}()`, "an operand"),
+                right: other.chainFor(`${kind}()`, "an operand"),
+            },
+        ], this.biDiConnector, this.contextId, this.helpers, [], this.strictness);
+    }
+    /** The chain of a locator used inside another (`has`); a locator with fallbacks cannot be */
+    chainFor(method, role) {
+        if (this.alternatives.length > 0) {
+            throw new TypeError(`${method}: a locator with fallbacks (withFallbacks) cannot be used as ${role}`);
+        }
+        return this.chain;
+    }
+    /** The first match, in document order */
+    first() {
+        return this.nth(0);
+    }
+    /** The last match, in document order */
+    last() {
+        return this.nth(-1);
+    }
     /** One locator per element currently matching, in document order */
     async all() {
         if (this.alternatives.length > 0) {
@@ -114,7 +196,7 @@ export default class Locator {
         const only = this.chain.length === 1 ? this.chain[0] : undefined;
         return Array.from({ length: count }, (_, index) => only?.kind === "xpath"
             ? // A positional xpath keeps working without a second search for the whole chain
-                new Locator(`(${describeSelector(only, false)})[${index + 1}]`, this.biDiConnector, this.contextId, this.helpers)
+                new Locator(`(${describeSelector(only, false)})[${index + 1}]`, this.biDiConnector, this.contextId, this.helpers, [], this.strictness)
             : this.child({ kind: "nth", index }));
     }
     /**
@@ -150,73 +232,58 @@ export default class Locator {
         return undefined;
     }
     withoutFallbacks() {
-        return new Locator(this.chain, this.biDiConnector, this.contextId, this.helpers);
-    }
-    async resolveOne() {
-        return (await this.resolve(1))[0] ?? null;
-    }
-    /** Calls `fn` in the page; a throwing function becomes a "Failed to locate element" error */
-    async call(fn, args, sandbox) {
-        try {
-            return await callFunction(this.biDiConnector, this.contextId, fn, args, {
-                awaitPromise: false,
-                ...(sandbox !== undefined && { sandbox }),
-            });
-        }
-        catch (err) {
-            if (err instanceof ScriptError) {
-                throw new Error(`Failed to locate element ${this.selector}. Details: ${err.text}`);
-            }
-            throw err;
-        }
+        return new Locator(this.chain, this.biDiConnector, this.contextId, this.helpers, [], this.strictness);
     }
     /**
-     * Calls a function on the first matching element: `body` sees it as `el`, followed by `params`.
-     * Answers `whenMissing` when nothing matches, or the element disappeared meanwhile.
+     * The element the locator matches first. With a `method` name and strict selectors on, several matches
+     * throw instead (`method` is the public method that asked, for the message)
      */
-    async callOnElement(whenMissing, body, params = [], args = []) {
-        const el = await this.resolveOne();
-        if (!el)
-            return whenMissing;
-        try {
-            return await this.call(`(el${params.map((param) => `, ${param}`).join("")}) => { ${body} }`, [el, ...args]);
+    async resolveOne(method) {
+        if (method === undefined ||
+            !(await (this.strictAnswer ??= this.strictness()))) {
+            return (await this.resolve(1))[0] ?? null;
         }
-        catch (err) {
-            if (err instanceof BiDiError && err.code === "no such node")
-                return whenMissing;
-            throw err;
+        const found = await this.resolve();
+        if (found.length > 1) {
+            throw strictViolation(method, found.length, this.selector);
         }
-    }
-    /** Like `callOnElement`, for operations that cannot go on without the element */
-    async callOnExistingElement(body) {
-        const missing = Symbol("missing");
-        const result = await this.callOnElement(missing, body);
-        if (result === missing)
-            throw this.noElementError();
-        return result;
-    }
-    /** The error for an operation that needs an element when none matches */
-    noElementError() {
-        return new Error(`Failed to locate element ${this.selector}. Details: no element matches`);
-    }
-    /** The element the locator matches now; throws when none does */
-    async requireElement() {
-        const el = await this.resolveOne();
-        if (!el)
-            throw this.noElementError();
-        return el;
-    }
-    probeState(options) {
-        return probeState(this.actionability, options);
+        return found[0] ?? null;
     }
     waitForActionable(action, checks, probe, options) {
         return waitForActionable(this.actionability, action, checks, probe, options);
     }
     /** Waits until the element is attached, visible, stable, enabled and not covered, then clicks its centre with real pointer input */
     async click(options) {
-        const state = await this.waitForActionable("click", CLICK_CHECKS, { scroll: true, hitTest: true }, options);
-        // "attached" is always required, so the box is present
-        await clickRect(this.biDiConnector, this.contextId, state.box);
+        await clickElement(this.access, options);
+    }
+    /**
+     * Checks a checkbox, radio or `role=checkbox|radio|switch` element; does nothing when it is already checked.
+     * Waits like `click`, but a hidden input counts as reachable through its `<label>`, which is what gets clicked.
+     * `trial` waits without clicking. Throws when the click did not change the state.
+     * @example
+     *  await page.getByLabel("I accept the terms").check();
+     */
+    async check(options) {
+        await setChecked(this.access, "check", true, options);
+    }
+    /** Unchecks a checkbox or `role=checkbox|switch` element; does nothing when it is already unchecked. A radio button cannot be unchecked: throws */
+    async uncheck(options) {
+        await setChecked(this.access, "uncheck", false, options);
+    }
+    /** `check()` or `uncheck()`, whichever brings the element to `checked` */
+    async setChecked(checked, options) {
+        await setChecked(this.access, "setChecked", checked, options);
+    }
+    /**
+     * Selects options of a `<select>` or `<select multiple>` (which replaces its selection) and fires `input` and
+     * `change`. A string matches an option's value or its label; `{ value, label, index }` must match every field
+     * given. Waits until the select is visible and enabled and every option exists. Returns the values now selected.
+     * @example
+     *  await page.getByLabel("Country").selectOption("Netherlands");
+     *  await page.locator("select").selectOption([{ index: 0 }, { value: "b" }]);
+     */
+    async selectOption(values, options) {
+        return selectOptions(this.access, values, options);
     }
     /**
      * Sets the files of an `<input type=file>`; `[]` clears it. Paths are relative to the project folder (absolute
@@ -227,7 +294,7 @@ export default class Locator {
      *  await page.getByLabel("Upload").setInputFiles(generatedFile({ name: "huge.pdf", size: "60 MB" }));
      */
     async setInputFiles(files, options) {
-        await setInputFiles(this.elementContext, files, options);
+        await setInputFiles(this.access, files, options);
     }
     /**
      * Drops files on the element, as dragging them from the desktop does: `dragenter`, `dragover` and `drop`
@@ -238,7 +305,7 @@ export default class Locator {
      *  await page.getByTestId("dropzone").dropFiles(["files/a.png", "files/b.png"]);
      */
     async dropFiles(files, options) {
-        await dropFiles(this.elementContext, files, options);
+        await dropFiles(this.access, files, options);
     }
     /**
      * Takes a screenshot of just this element, after scrolling it into view and waiting until it is attached and
@@ -247,17 +314,11 @@ export default class Locator {
      *  await page.locator("div[@id='chart']").screenshot({ path: "out/chart.png" });
      */
     async screenshot(options = {}) {
-        const { timeout, ...capture } = options;
-        await this.waitForActionable("screenshot", SCREENSHOT_CHECKS, { scroll: true, hitTest: false }, timeout === undefined ? undefined : { timeout });
-        const el = await this.requireElement();
-        return takeScreenshot(this.biDiConnector, this.contextId, capture, {
-            sharedId: el.sharedId,
-        });
+        return screenshotElement(this.access, options);
     }
     /** Waits until the element is attached, then focuses it */
     async focus(options) {
-        await this.waitForActionable("focus", ATTACHED_ONLY, { scroll: false, hitTest: false }, options);
-        await this.callOnExistingElement(`el.focus();`);
+        await focusElement(this.access, options);
     }
     /** Waits until the element reaches `state` (default "visible"); does not scroll */
     async waitFor(options = {}) {
@@ -265,31 +326,60 @@ export default class Locator {
     }
     /** Returns the browser's getBoundingClientRect result for the given element */
     async getBoundingClientRect() {
-        const rect = await this.callOnExistingElement(`
-      const { x, y, width, height, top, right, bottom, left } = el.getBoundingClientRect();
-      return { x, y, width, height, top, right, bottom, left };
-    `);
-        if (typeof rect !== "object" || rect === null) {
-            throw new Error(`Expected to receive an object but instead received "${describeType(rect)}"`);
-        }
-        return rect;
+        return readBoundingClientRect(this.access);
     }
     /** Whether the element exists, has a non-empty box and is not hidden by CSS */
     async isVisible() {
-        const state = await this.probeState({ scroll: false, hitTest: false });
-        return state.attached && state.visible;
+        return readIsVisible(this.actionability);
+    }
+    /** The opposite of `isVisible`: true for a hidden element and for one that is not there */
+    async isHidden() {
+        return !(await this.isVisible());
     }
     /** Trimmed text content, or null when the element is missing */
     async textContent() {
-        return stringOrNull(await this.callOnElement(null, `return el.textContent.trim();`));
+        return readTextContent(this.access);
+    }
+    /** Rendered text of the element (as a person would copy it, hidden text left out), untrimmed, or null when the element is missing */
+    async innerText() {
+        return readInnerText(this.access);
+    }
+    /** The markup inside the element, or null when the element is missing */
+    async innerHTML() {
+        return readInnerHTML(this.access);
+    }
+    /** `textContent` of every match, as the page has it (untrimmed, unlike `textContent()`); `[]` when none match. Does not wait */
+    async allTextContents() {
+        return readAllTextContents(this.access);
+    }
+    /** `innerText` of every match; `[]` when none match. Does not wait */
+    async allInnerTexts() {
+        return readAllInnerTexts(this.access);
+    }
+    /** The element's box in CSS pixels from the viewport's top left, or null when it is missing or not rendered (`display: none`). Does not wait or scroll */
+    async boundingBox() {
+        return readBoundingBox(this.access);
+    }
+    /**
+     * Waits until the element is attached (hidden is fine), then calls `fn(element, arg)` in the page and returns the result
+     * (see `page.evaluate` for what comes back). `fn` is a function or the source of one; a strict locator throws when several match.
+     * @example
+     *  const id = await page.getByTestId("row").evaluate((el) => el.dataset.id);
+     */
+    async evaluate(fn, arg, options) {
+        return evaluateOnElement(this.access, fn, arg, options);
+    }
+    /** Calls `fn(elements, arg)` in the page with an array of every match (empty when none; does not wait) and returns the result */
+    async evaluateAll(fn, arg) {
+        return evaluateOnAll(this.access, fn, arg);
     }
     /** Value of an input/textarea/select, or null when missing */
     async inputValue() {
-        return stringOrNull(await this.callOnElement(null, `return typeof el.value === "string" ? el.value : null;`));
+        return readInputValue(this.access);
     }
     /** Attribute value, or null when the element or attribute is missing */
     async getAttribute(name) {
-        return stringOrNull(await this.callOnElement(null, `return el.getAttribute(name);`, ["name"], [name]));
+        return readAttribute(this.access, name);
     }
     /** References to the elements currently matching, in document order. Internal: for tooling that identifies elements */
     async elements() {
@@ -301,30 +391,39 @@ export default class Locator {
     }
     /** Whether the element exists and is not disabled; does not wait */
     async isEnabled() {
-        const state = await this.probeState({ scroll: false, hitTest: false });
-        return state.attached && state.enabled;
+        return readIsEnabled(this.actionability);
+    }
+    /** The opposite of `isEnabled`: true for a disabled element and for one that is not there; does not wait */
+    async isDisabled() {
+        return !(await this.isEnabled());
     }
     /** Like `isEnabled`, but null when the element is missing, so callers can tell "disabled" from "not there"; does not wait */
     async enabledState() {
-        const state = await this.probeState({ scroll: false, hitTest: false });
-        return state.attached ? state.enabled : null;
+        return readEnabledState(this.actionability);
     }
     /** Whether a checkbox or radio input is checked or the element has `aria-checked="true"`; null when the element is missing */
     async isChecked() {
-        return booleanOrNull(await this.callOnElement(null, IS_CHECKED_BODY));
+        return readIsChecked(this.access);
+    }
+    /** The accessible name (what `getByRole`'s `name` is matched against), "" when there is none, or null when the element is missing */
+    async accessibleName() {
+        return readAccessibleName(this.access);
+    }
+    /** The accessible description (`aria-describedby`, `aria-description`, else `title` when it is not the name), or null when the element is missing */
+    async accessibleDescription() {
+        return readAccessibleDescription(this.access);
     }
     /** The class attribute as written ("" when the element has none), or null when the element is missing */
     async classAttribute() {
-        return stringOrNull(await this.callOnElement(null, `return el.getAttribute("class") ?? "";`));
+        return readClassAttribute(this.access);
     }
     /** Computed value of a CSS property (camelCase names become kebab-case, `--custom` is kept), or null when the element is missing */
     async cssValue(name) {
-        return stringOrNull(await this.callOnElement(null, `return getComputedStyle(el).getPropertyValue(name);`, ["name"], [cssPropertyName(name)]));
+        return readCssValue(this.access, name);
     }
     /** Whether the element exists and accepts typing (enabled, not readonly, a text field); does not wait */
     async isEditable() {
-        const state = await this.probeState({ scroll: false, hitTest: false });
-        return state.attached && state.editable;
+        return readIsEditable(this.actionability);
     }
     /** Wait for certain time (ms). Default: 300ms  */
     async wait(duration = DEFAULT_PAUSE_MS) {
@@ -338,42 +437,10 @@ export default class Locator {
      *  await page.getByLabel("New todo").press("Enter");
      */
     async press(key, options) {
-        const code = NAMED_KEYS[key] ?? (Array.from(key).length === 1 ? key : "");
-        if (code === "") {
-            throw new Error(`press(): unknown key "${key}". Use one of ${Object.keys(NAMED_KEYS).join(", ")} or a single character`);
-        }
-        await this.waitForActionable("press", PRESS_CHECKS, { scroll: true, hitTest: false }, options);
-        await this.callOnElement(undefined, `el.focus();`);
-        await pressKey(this.biDiConnector, this.contextId, code);
+        await pressOnElement(this.access, key, options);
     }
     /** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
     async fill(value, options) {
-        // Taken when the call starts, so a fill that outlives its test saves into that test's closed sink
-        const save = options?.output === undefined
-            ? undefined
-            : bindOutput("fill()", options.output);
-        const state = await this.waitForActionable("fill", FILL_CHECKS, { scroll: true, hitTest: true }, options);
-        // Typing over the selected existing value replaces it; Backspace clears it for an empty value
-        const keys = value === "" ? NAMED_KEYS.Backspace : value;
-        await clickRect(this.biDiConnector, this.contextId, state.box);
-        // Lets the focus the click caused (and the page's focus handlers) settle before the text is selected and typed over
-        await this.wait();
-        await this.callOnElement(undefined, `if (typeof el.select === "function") el.select();`);
-        await typeText(this.biDiConnector, this.contextId, keys);
-        save?.(value);
+        await fillElement(this.access, value, options);
     }
 }
-function booleanOrNull(value) {
-    if (typeof value === "boolean")
-        return value;
-    if (value === null)
-        return null;
-    throw new Error(`Expected a boolean or null but received "${describeType(value)}"`);
-}
-function stringOrNull(value) {
-    if (typeof value === "string")
-        return value;
-    if (value === null)
-        return null;
-    throw new Error(`Expected a string or null but received "${describeType(value)}"`);
-}

package/dist/locator/page-scripts.d.ts

@@ -11,6 +11,8 @@ export declare const DROP_INPUT = "() => {\n  const input = document.createEleme
 export declare const DROP_EVENTS = "(el, types) => {\n  const input = globalThis[Symbol.for(\"samurai.drop\")];\n  delete globalThis[Symbol.for(\"samurai.drop\")];\n  const data = new DataTransfer();\n  Array.from(input.files).forEach((file, i) => {\n    data.items.add(types[i] ? new File([file], file.name, { type: types[i], lastModified: file.lastModified }) : file);\n  });\n  const box = el.getBoundingClientRect();\n  const at = { clientX: box.left + box.width / 2, clientY: box.top + box.height / 2 };\n  for (const type of [\"dragenter\", \"dragover\", \"drop\"]) {\n    el.dispatchEvent(new DragEvent(type, Object.assign({ bubbles: true, cancelable: true, composed: true, dataTransfer: data }, at)));\n  }\n}";
 export declare const SCREENSHOT_CHECKS: readonly CheckName[];
 export declare const CLICK_CHECKS: readonly CheckName[];
+/** `selectOption`: a select is not clicked, so it need not be stable or uncovered */
+export declare const SELECT_CHECKS: readonly CheckName[];
 export declare const FILL_CHECKS: readonly CheckName[];
 export declare const PRESS_CHECKS: readonly CheckName[];
 export declare const ATTACHED_ONLY: readonly CheckName[];

package/dist/locator/page-scripts.js

@@ -39,6 +39,12 @@ export const CLICK_CHECKS = [
     "enabled",
     "hit target",
 ];
+/** `selectOption`: a select is not clicked, so it need not be stable or uncovered */
+export const SELECT_CHECKS = [
+    "attached",
+    "visible",
+    "enabled",
+];
 export const FILL_CHECKS = [
     "attached",
     "visible",

package/dist/locator/page-search.d.ts

@@ -2,9 +2,18 @@
  * Page-side pieces the text and label searches share. They are strings, glued into the function declarations
  * of `TEXT_LOCATE` and `LABEL_LOCATE`, which run in the page with `(starts, value, match, ignoreCase)` in scope.
  */
-/** `normalise` collapses whitespace and trims (lower-casing with `ignoreCase`); `textMatches` compares a text with `value` by `match` */
-export declare const MATCHING_JS = "\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  };";
+/**
+ * `normalise` collapses whitespace and trims (lower-casing with `ignoreCase`); `textMatches` compares a text with `value` by
+ * `match`. A RegExp `value` is tested on the collapsed text as written (flags kept, `g` and `y` dropped); `match` and
+ * `ignoreCase` then do not apply.
+ */
+export declare const MATCHING_JS = "\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  };";
 /** The nodes to search in: the start nodes, else the whole document */
 export declare const ROOTS_JS = "const roots = starts.length > 0 ? starts : [document];";
 /** A sort callback putting elements in document order */
 export declare const DOCUMENT_ORDER_JS = "(a, b) => (a === b ? 0 : a.compareDocumentPosition(b) & 4 ? -1 : 1)";
+/**
+ * Function declaration run in the page as `(elements)`: the same elements in document order. A search with
+ * several start nodes answers per start node, so its results are not in document order.
+ */
+export declare const SORT_IN_DOCUMENT_ORDER = "(elements) => elements.slice().sort((a, b) => (a === b ? 0 : a.compareDocumentPosition(b) & 4 ? -1 : 1))";

package/dist/locator/page-search.js

@@ -2,14 +2,21 @@
  * Page-side pieces the text and label searches share. They are strings, glued into the function declarations
  * of `TEXT_LOCATE` and `LABEL_LOCATE`, which run in the page with `(starts, value, match, ignoreCase)` in scope.
  */
-/** `normalise` collapses whitespace and trims (lower-casing with `ignoreCase`); `textMatches` compares a text with `value` by `match` */
+/**
+ * `normalise` collapses whitespace and trims (lower-casing with `ignoreCase`); `textMatches` compares a text with `value` by
+ * `match`. A RegExp `value` is tested on the collapsed text as written (flags kept, `g` and `y` dropped); `match` and
+ * `ignoreCase` then do not apply.
+ */
 export const MATCHING_JS = `
+  const collapse = (text) => String(text).replace(/\\s+/g, " ").trim();
   const normalise = (text) => {
-    const collapsed = String(text).replace(/\\s+/g, " ").trim();
+    const collapsed = collapse(text);
     return ignoreCase ? collapsed.toLowerCase() : collapsed;
   };
-  const wanted = normalise(value);
+  const pattern = typeof value === "string" ? null : new RegExp(value.source, value.flags.replace(/[gy]/g, ""));
+  const wanted = pattern ? "" : normalise(value);
   const textMatches = (text) => {
+    if (pattern) return pattern.test(collapse(text));
     const normal = normalise(text);
     return match === "full" ? normal === wanted : normal.includes(wanted);
   };`;
@@ -17,3 +24,8 @@ export const MATCHING_JS = `
 export const ROOTS_JS = `const roots = starts.length > 0 ? starts : [document];`;
 /** A sort callback putting elements in document order */
 export const DOCUMENT_ORDER_JS = `(a, b) => (a === b ? 0 : a.compareDocumentPosition(b) & 4 ? -1 : 1)`;
+/**
+ * Function declaration run in the page as `(elements)`: the same elements in document order. A search with
+ * several start nodes answers per start node, so its results are not in document order.
+ */
+export const SORT_IN_DOCUMENT_ORDER = `(elements) => elements.slice().sort(${DOCUMENT_ORDER_JS})`;

package/dist/locator/page-step.d.ts

@@ -0,0 +1,16 @@
+import type { Arg } from "../script/serialize.js";
+import type { Selector } from "./selector.js";
+/** A step the framework searches in the page: the function (run as `(starts, ...args)`) and its arguments after the start nodes */
+export interface PageSearch {
+    fn: string;
+    args: Arg[];
+}
+/** The text search of a `text` step, which the browser's own `innerText` locator cannot do (or does not exist) */
+export declare function textSearch(selector: Extract<Selector, {
+    kind: "text";
+}>): PageSearch;
+/**
+ * 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 declare function pageSearch(selector: Selector): PageSearch | undefined;