@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/dist/locator/locator.js

@@ -0,0 +1,591 @@
+import { BiDiError } from "../transport/bidi-error.js";
+import { callFunction, ScriptError } from "../script/call-function.js";
+import { CALL_PROBE, HELPER_SANDBOX, HELPERS_MISSING, } from "../script/helpers.js";
+import { ElementHandle } from "../script/element-handle.js";
+import { takeScreenshot, } from "../browser/screenshot.js";
+import { assertIsFile, resolveFiles } from "../browser/file-paths.js";
+import { resolveTimeout, waitUntil, WaitTimeoutError, } from "../wait/wait-until.js";
+import { ActionTimeoutError } from "./action-timeout-error.js";
+import { allPass, DETACHED_STATE, evaluateChecks, parseElementState, PROBE_ELEMENT, } from "./element-state.js";
+import { InvalidSelectorError, UnsupportedOperationError, } from "./selector-errors.js";
+import { LABEL_LOCATE } from "./label-locator.js";
+import { TEXT_LOCATE } from "./text-locator.js";
+import { cssSelector, describeChain, describeSelector, labelSelector, roleSelector, testIdSelector, textSelector, toBiDiLocator, xpathSelector, } from "./selector.js";
+export { InvalidSelectorError, UnsupportedOperationError, } from "./selector-errors.js";
+/** Locator types a connection's browser rejected, so they are not tried again on every poll */
+const unsupportedByConnector = new WeakMap();
+function unsupportedTypes(connector) {
+    let types = unsupportedByConnector.get(connector);
+    if (!types)
+        unsupportedByConnector.set(connector, (types = new Set()));
+    return types;
+}
+/** What `setInputFiles` needs to know about the element before it sends files */
+const FILE_INPUT_INFO = `(el) => ({
+  tag: el.tagName.toLowerCase(),
+  type: (el.getAttribute("type") || "").toLowerCase(),
+  multiple: Boolean(el.multiple),
+})`;
+const FILE_INPUT_CHECKS = ["attached", "enabled"];
+const SCREENSHOT_CHECKS = ["attached", "visible"];
+const CLICK_CHECKS = [
+    "attached",
+    "visible",
+    "stable",
+    "enabled",
+    "hit target",
+];
+const FILL_CHECKS = [
+    "attached",
+    "visible",
+    "enabled",
+    "editable",
+    "hit target",
+];
+const ATTACHED_ONLY = ["attached"];
+/** Unicode code point WebDriver uses for the Backspace key */
+const BACKSPACE = "";
+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`).
+     */
+    constructor(selector, biDiConnector, contextId, helpers, alternatives = []) {
+        this.chain =
+            typeof selector === "string" ? [xpathSelector(selector)] : selector;
+        this.biDiConnector = biDiConnector;
+        this.contextId = contextId;
+        this.helpers = helpers;
+        this.alternatives = alternatives;
+    }
+    /**
+     * The description of this locator used in error messages, e.g. `//form >> role=button[name="Save"]`;
+     * fallbacks follow as `or …`
+     */
+    get selector() {
+        return [
+            describeChain(this.chain),
+            ...this.alternatives.map((alt) => alt.selector),
+        ].join(" or ");
+    }
+    /** 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)));
+    }
+    /**
+     * A locator that tries this one first and, whenever it matches nothing, each of `fallbacks` in order;
+     * the first one with a match wins. For steps with several ways to find the same element (a test id,
+     * then role and name, then text), most stable first. `matchedBy` says which one matched last, so a
+     * self-healing layer can tell the primary locator has gone stale.
+     * @example
+     *  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]);
+    }
+    /**
+     * Which locator found elements the last time this one searched: index 0 is the primary, 1 the first
+     * fallback, and so on. `undefined` before any search or when the last search found nothing.
+     */
+    get matchedBy() {
+        return this.matched;
+    }
+    /** Elements matching the label text (`<label>`, `aria-labelledby`, `aria-label`), inside this locator's matches */
+    getByLabel(text, options) {
+        return this.child(labelSelector(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 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"` */
+    getByText(text, options) {
+        return this.child(textSelector(text, options));
+    }
+    /** Elements with the ARIA role (and accessible name, when given), inside this locator's matches */
+    getByRole(role, options) {
+        return this.child(roleSelector(role, options));
+    }
+    /** One locator per element currently matching, in document order */
+    async all() {
+        if (this.alternatives.length > 0) {
+            // Pin to whichever of the primary and the fallbacks matches, so each result is one element
+            const first = await this.firstMatching();
+            return first ? first.all() : [];
+        }
+        const count = await this.count();
+        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)
+            : this.child({ kind: "nth", index }));
+    }
+    /**
+     * Finds the elements the chain matches, in document order. Every step searches inside the previous
+     * step's matches; `max` limits the final result. Nothing is cached: the element that matches "first"
+     * can change between polls, and a removed node stays resolvable in the browser.
+     */
+    async resolve(max) {
+        this.matched = undefined;
+        const own = await this.resolveChain(max);
+        if (own.length > 0) {
+            this.matched = { index: 0, selector: describeChain(this.chain) };
+            return own;
+        }
+        for (const [index, alternative] of this.alternatives.entries()) {
+            const found = await alternative.resolve(max);
+            if (found.length > 0) {
+                this.matched = { index: index + 1, selector: alternative.selector };
+                return found;
+            }
+        }
+        return [];
+    }
+    /** The primary or the first fallback that currently matches, without its own fallbacks */
+    async firstMatching() {
+        if ((await this.resolveChain(1)).length > 0)
+            return this.withoutFallbacks();
+        for (const alternative of this.alternatives) {
+            const found = await alternative.firstMatching();
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    withoutFallbacks() {
+        return new Locator(this.chain, this.biDiConnector, this.contextId, this.helpers);
+    }
+    async resolveChain(max) {
+        let nodes;
+        for (const [index, selector] of this.chain.entries()) {
+            if (selector.kind === "nth") {
+                const picked = nodes?.[selector.index];
+                nodes = picked ? [picked] : [];
+            }
+            else {
+                nodes = await this.locateStep(selector, index > 0, nodes, index === this.chain.length - 1 ? max : undefined);
+            }
+            if (nodes.length === 0)
+                return [];
+        }
+        return nodes ?? [];
+    }
+    async resolveOne() {
+        return (await this.resolve(1))[0] ?? null;
+    }
+    async locateStep(selector, scoped, startNodes, max) {
+        if (selector.kind === "label")
+            return this.locateInPage(LABEL_LOCATE, selector, startNodes, max);
+        if (selector.kind === "text" &&
+            unsupportedTypes(this.biDiConnector).has("innerText")) {
+            return this.locateByText(selector, startNodes, max);
+        }
+        try {
+            return await this.locateNatively(selector, scoped, startNodes, max);
+        }
+        catch (err) {
+            if (err instanceof BiDiError && err.code === "invalid selector") {
+                throw new InvalidSelectorError(describeSelector(selector, scoped), err.message);
+            }
+            if (err instanceof BiDiError && err.code === "unsupported operation") {
+                if (selector.kind === "text") {
+                    // The browser has no innerText locator (Firefox): remember that and search in the page instead
+                    unsupportedTypes(this.biDiConnector).add("innerText");
+                    return this.locateByText(selector, startNodes, max);
+                }
+                throw new UnsupportedOperationError(`${describeSelector(selector, scoped)}: this kind of locator is not supported by the browser (${err.message})`);
+            }
+            throw err;
+        }
+    }
+    async locateNatively(selector, scoped, startNodes, max) {
+        const { nodes } = await this.biDiConnector.send("browsingContext.locateNodes", {
+            context: this.contextId,
+            locator: toBiDiLocator(selector, scoped),
+            ...(max !== undefined && { maxNodeCount: max }),
+            // Only the references are needed; skip serializing the matched subtrees
+            serializationOptions: { maxDomDepth: 0 },
+            ...(startNodes && {
+                startNodes: startNodes.map(({ sharedId }) => ({ sharedId })),
+            }),
+        });
+        const found = new Map();
+        for (const node of nodes) {
+            if (node.sharedId !== undefined && !found.has(node.sharedId)) {
+                found.set(node.sharedId, new ElementHandle(node.sharedId, node.handle));
+            }
+        }
+        return [...found.values()];
+    }
+    /** Text search done in the page, for browsers without BiDi's innerText locator */
+    locateByText(selector, startNodes, max) {
+        return this.locateInPage(TEXT_LOCATE, selector, startNodes, max);
+    }
+    /** Runs a page-side search `(starts, value, match, ignoreCase) => elements` */
+    async locateInPage(fn, selector, startNodes, max) {
+        const found = await this.call(fn, [
+            startNodes ?? [],
+            selector.value,
+            selector.match,
+            selector.ignoreCase,
+        ]);
+        return max === undefined ? found : found.slice(0, max);
+    }
+    /** 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;
+        }
+    }
+    /**
+     * 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.
+     */
+    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]);
+        }
+        catch (err) {
+            if (err instanceof BiDiError && err.code === "no such node")
+                return whenMissing;
+            throw err;
+        }
+    }
+    /** 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 new Error(`Failed to locate element ${this.selector}. Details: no element matches`);
+        }
+        return result;
+    }
+    /** Reads the element's actionability state: one search, one probe */
+    async probeState(options) {
+        const el = await this.resolveOne();
+        if (!el)
+            return DETACHED_STATE;
+        try {
+            return parseElementState(await this.callProbe(el, options));
+        }
+        catch (err) {
+            // The document changed between the search and the probe
+            if (err instanceof BiDiError && err.code === "no such node")
+                return DETACHED_STATE;
+            throw err;
+        }
+    }
+    async callProbe(el, options) {
+        const args = [el, { ...options }];
+        if (!this.helpers)
+            return this.call(PROBE_ELEMENT, args);
+        await this.helpers.ensureInstalled();
+        let result = await this.call(CALL_PROBE, args, HELPER_SANDBOX);
+        if (result === HELPERS_MISSING) {
+            // A document got past the registration (e.g. created while it was being set up): install again once
+            await this.helpers.reinstall();
+            result = await this.call(CALL_PROBE, args, HELPER_SANDBOX);
+            if (result === HELPERS_MISSING) {
+                throw new ScriptError("the samurai helpers are missing in the page after reinstalling", "probeElement");
+            }
+        }
+        return result;
+    }
+    /**
+     * Probes until every required check passes and returns that state.
+     * Throws ActionTimeoutError describing the last probe on timeout.
+     */
+    async waitForActionable(action, checks, probe, options) {
+        const timeout = await resolveTimeout(options?.timeout);
+        // Stability compares two probes; with timeout 0 there is only one
+        const required = options?.force
+            ? ATTACHED_ONLY
+            : timeout === 0
+                ? checks.filter((check) => check !== "stable")
+                : checks;
+        let lastChecks;
+        try {
+            return await waitUntil(() => this.probeState(probe), (current, previous) => {
+                lastChecks = evaluateChecks(required, current, previous);
+                return allPass(lastChecks);
+            }, { timeout });
+        }
+        catch (err) {
+            if (!(err instanceof WaitTimeoutError))
+                throw err;
+            const last = err.last;
+            throw new ActionTimeoutError({
+                action,
+                selector: this.selector,
+                timeout,
+                reason: !last
+                    ? "unreadable"
+                    : last.attached
+                        ? "not-actionable"
+                        : "not-attached",
+                checks: lastChecks,
+                coveredBy: lastChecks?.["hit target"] === "fail"
+                    ? (last?.hitTarget ?? undefined)
+                    : undefined,
+            });
+        }
+    }
+    /** 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 this.clickRect(state.box);
+    }
+    /** Simulate a click event on the center off a page element.
+     * This is mostly used internally to focus input elements when using the `fill()` method
+     * @example
+     *  const container = page.locator("div[@id=['clickable-element']");
+     *  const rect = await container.getBoundingClientRect();
+     *  await container.clickRect(rect);
+     */
+    async clickRect(rect) {
+        await this.biDiConnector.send("input.performActions", {
+            context: this.contextId,
+            actions: [
+                {
+                    type: "pointer",
+                    id: "samurai-pointer",
+                    actions: [
+                        {
+                            type: "pointerMove",
+                            x: rect.x + rect.width / 2,
+                            y: rect.y + rect.height / 2,
+                        },
+                        {
+                            type: "pointerDown",
+                            button: 0,
+                        },
+                        {
+                            type: "pointerUp",
+                            button: 0,
+                        },
+                    ],
+                },
+            ],
+        });
+    }
+    /**
+     * Sets the files of an `<input type=file>` (an empty list clears them); the browser fires `input` and `change`.
+     * Paths are resolved against the working directory and must exist on the machine the browser runs on.
+     * Waits for the input to be attached and enabled; it need not be visible, file inputs are often hidden behind a label.
+     * @example
+     *  await page.locator("input[@type='file']").setInputFiles("./fixtures/avatar.png");
+     *  await page.locator("input[@type='file']").setInputFiles([]);
+     */
+    async setInputFiles(files, options) {
+        const paths = resolveFiles(files);
+        for (const file of paths)
+            await assertIsFile(file, "setInputFiles");
+        await this.waitForActionable("setInputFiles", FILE_INPUT_CHECKS, { scroll: false, hitTest: false }, options?.timeout === undefined ? undefined : { timeout: options.timeout });
+        const missing = () => new Error(`Failed to locate element ${this.selector}. Details: no element matches`);
+        const el = await this.resolveOne();
+        if (!el)
+            throw missing();
+        let info;
+        try {
+            info = await this.call(FILE_INPUT_INFO, [el]);
+        }
+        catch (err) {
+            if (err instanceof BiDiError && err.code === "no such node")
+                throw missing();
+            throw err;
+        }
+        if (info.tag !== "input" || info.type !== "file") {
+            const found = info.tag === "input"
+                ? `<input type="${info.type || "text"}">`
+                : `<${info.tag}>`;
+            throw new Error(`setInputFiles(): ${this.selector} is not an <input type=file> (found ${found})`);
+        }
+        if (paths.length > 1 && !info.multiple) {
+            throw new Error(`setInputFiles(): ${this.selector} does not accept multiple files`);
+        }
+        await this.biDiConnector.send("input.setFiles", {
+            context: this.contextId,
+            element: { sharedId: el.sharedId },
+            files: paths,
+        });
+    }
+    /**
+     * Takes a screenshot of just this element, after scrolling it into view and waiting until it is attached and
+     * visible. Returns the image (also written to `options.path`).
+     * @example
+     *  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.resolveOne();
+        if (!el) {
+            throw new Error(`Failed to locate element ${this.selector}. Details: no element matches`);
+        }
+        return takeScreenshot(this.biDiConnector, this.contextId, capture, {
+            sharedId: el.sharedId,
+        });
+    }
+    /** 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();`);
+    }
+    /** Waits until the element reaches `state` (default "visible"); does not scroll */
+    async waitFor({ state = "visible", timeout, } = {}) {
+        const resolved = await resolveTimeout(timeout);
+        const reached = {
+            attached: (current) => current.attached,
+            detached: (current) => !current.attached,
+            visible: (current) => current.attached && current.visible,
+            hidden: (current) => !current.attached || !current.visible,
+        };
+        try {
+            await waitUntil(() => this.probeState({ scroll: false, hitTest: false }), reached[state], {
+                timeout: resolved,
+            });
+        }
+        catch (err) {
+            if (!(err instanceof WaitTimeoutError))
+                throw err;
+            throw new ActionTimeoutError({
+                action: "waitFor",
+                selector: this.selector,
+                timeout: resolved,
+                reason: err.last === undefined ? "unreadable" : "wrong-state",
+                state,
+            });
+        }
+    }
+    /** 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;
+    }
+    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)}"`);
+    }
+    /** Whether the element exists, has a non-empty box and is not hidden by CSS */
+    async isVisible() {
+        const result = await this.callOnElement(false, `
+      const rect = el.getBoundingClientRect();
+      const style = getComputedStyle(el);
+      return rect.width > 0 && rect.height > 0 &&
+        style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0";
+    `);
+        return result === true;
+    }
+    /** Trimmed text content, or null when the element is missing */
+    async textContent() {
+        return this.stringOrNull(await this.callOnElement(null, `return el.textContent.trim();`));
+    }
+    /** Value of an input/textarea/select, or null when missing */
+    async inputValue() {
+        return this.stringOrNull(await this.callOnElement(null, `return typeof el.value === "string" ? el.value : null;`));
+    }
+    /** Attribute value, or null when the element or attribute is missing */
+    async getAttribute(name) {
+        return this.stringOrNull(await this.callOnElement(null, `return el.getAttribute(name);`, ["name"], [name]));
+    }
+    /** References to the elements currently matching, in document order. Internal: for tooling that identifies elements */
+    async elements() {
+        return this.resolve();
+    }
+    /** Number of elements currently matching */
+    async count() {
+        return (await this.resolve()).length;
+    }
+    /** 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;
+    }
+    /** 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;
+    }
+    /** Wait for certain time (ms). Default: 300ms  */
+    async wait(duration = 300) {
+        await this.biDiConnector.send("input.performActions", {
+            context: this.contextId,
+            actions: [
+                {
+                    type: "none",
+                    id: "samurai-sleep",
+                    actions: [
+                        {
+                            type: "pause",
+                            duration,
+                        },
+                    ],
+                },
+            ],
+        });
+    }
+    /** 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) {
+        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 === "" ? BACKSPACE : value;
+        const actions = Array.from(keys).flatMap((char) => [
+            {
+                type: "keyDown",
+                value: char,
+            },
+            {
+                type: "keyUp",
+                value: char,
+            },
+        ]);
+        await this.clickRect(state.box);
+        await this.wait();
+        await this.callOnElement(undefined, `if (typeof el.select === "function") el.select();`);
+        await this.biDiConnector.send("input.performActions", {
+            context: this.contextId,
+            actions: [
+                {
+                    actions,
+                    type: "key",
+                    id: "samurai-keyboard",
+                },
+            ],
+        });
+    }
+}
+function describeType(value) {
+    return value === null ? "null" : typeof value;
+}

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

@@ -0,0 +1,9 @@
+/** The browser rejected a selector (bad css or xpath); retrying cannot help */
+export declare class InvalidSelectorError extends Error {
+    readonly selector: string;
+    constructor(selector: string, reason: string);
+}
+/** The browser does not implement this kind of locator */
+export declare class UnsupportedOperationError extends Error {
+    constructor(message: string);
+}

package/dist/locator/selector-errors.js

@@ -0,0 +1,15 @@
+/** The browser rejected a selector (bad css or xpath); retrying cannot help */
+export class InvalidSelectorError extends Error {
+    constructor(selector, reason) {
+        super(`Invalid selector ${selector}: ${reason}`);
+        this.name = "InvalidSelectorError";
+        this.selector = selector;
+    }
+}
+/** The browser does not implement this kind of locator */
+export class UnsupportedOperationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedOperationError";
+    }
+}

package/dist/locator/selector.d.ts

@@ -0,0 +1,60 @@
+import type { NodeLocator } from "../types/bidi-modules/browsing-context.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";
+    value: string;
+} | {
+    kind: "css";
+    value: string;
+} | {
+    kind: "text";
+    value: string;
+    match: "full" | "partial";
+    ignoreCase: boolean;
+} | {
+    kind: "role";
+    role?: string;
+    name?: string;
+}
+/** Form controls named by a `<label>`, `aria-labelledby` or `aria-label` whose text matches */
+ | {
+    kind: "label";
+    value: string;
+    match: "full" | "partial";
+    ignoreCase: boolean;
+}
+/** 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 */
+ | {
+    kind: "nth";
+    index: number;
+};
+export interface TextOptions {
+    /** @default "full" */
+    match?: "full" | "partial";
+    /** @default false */
+    ignoreCase?: boolean;
+}
+export declare function xpathSelector(value: string): Selector;
+export declare function cssSelector(value: string): Selector;
+export declare function textSelector(value: string, { match, ignoreCase }?: TextOptions): Selector;
+export declare function labelSelector(value: string, { match, ignoreCase }?: TextOptions): Selector;
+export declare function testIdSelector(value: string): Selector;
+export declare function roleSelector(role: string, { name }?: {
+    name?: string;
+}): 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
+ * position `//…` is also made relative, so `parent.locator("//x")` means "x inside parent".
+ */
+export declare function normalizeXpath(xpath: string, scoped: boolean): string;
+/** The BiDi locator for a step. `scoped` is true for every step after the first */
+export declare function toBiDiLocator(selector: Selector, scoped: boolean): NodeLocator;
+/** A short name for error messages */
+export declare function describeSelector(selector: Selector, scoped: boolean): string;
+export declare function describeChain(chain: readonly Selector[]): string;