@itmetsam/samurai-framework 0.21.1 → 0.21.3

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

@@ -0,0 +1,17 @@
+import { type ElementScreenshotOptions } from "../browser/screenshot.js";
+import type { ActionOptions } from "./actionability.js";
+import { type ElementAccess } from "./element-access.js";
+/** Waits until the element is attached, visible, stable, enabled and not covered, then clicks its centre with real pointer input */
+export declare function clickElement(access: ElementAccess, options?: ActionOptions): Promise<void>;
+/** Takes a screenshot of just the element, after scrolling it into view and waiting until it is attached and visible */
+export declare function screenshotElement(access: ElementAccess, options?: ElementScreenshotOptions & {
+    timeout?: number;
+}): Promise<Buffer>;
+/** Waits until the element is attached, then focuses it */
+export declare function focusElement(access: ElementAccess, options?: ActionOptions): Promise<void>;
+/** Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input */
+export declare function pressOnElement(access: ElementAccess, key: string, options?: ActionOptions): Promise<void>;
+/** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
+export declare function fillElement(access: ElementAccess, value: string, options?: ActionOptions & {
+    output?: string;
+}): Promise<void>;

package/dist/locator/element-actions.js

@@ -0,0 +1,51 @@
+import { bindOutput } from "../wait/output-sink.js";
+import { takeScreenshot, } from "../browser/screenshot.js";
+import { callOnElement, callOnExistingElement, requireElement, } from "./element-access.js";
+import { clickRect, DEFAULT_PAUSE_MS, NAMED_KEYS, pause, pressKey, typeText, } from "./input-actions.js";
+import { ATTACHED_ONLY, CLICK_CHECKS, FILL_CHECKS, PRESS_CHECKS, SCREENSHOT_CHECKS, } from "./page-scripts.js";
+/** Waits until the element is attached, visible, stable, enabled and not covered, then clicks its centre with real pointer input */
+export async function clickElement(access, options) {
+    const state = await access.waitForActionable("click", CLICK_CHECKS, { scroll: true, hitTest: true }, options);
+    // "attached" is always required, so the box is present
+    await clickRect(access.connector, access.contextId, state.box);
+}
+/** Takes a screenshot of just the element, after scrolling it into view and waiting until it is attached and visible */
+export async function screenshotElement(access, options = {}) {
+    const { timeout, ...capture } = options;
+    await access.waitForActionable("screenshot", SCREENSHOT_CHECKS, { scroll: true, hitTest: false }, timeout === undefined ? undefined : { timeout });
+    const el = await requireElement(access);
+    return takeScreenshot(access.connector, access.contextId, capture, {
+        sharedId: el.sharedId,
+    });
+}
+/** Waits until the element is attached, then focuses it */
+export async function focusElement(access, options) {
+    await access.waitForActionable("focus", ATTACHED_ONLY, { scroll: false, hitTest: false }, options);
+    await callOnExistingElement(access, `el.focus();`);
+}
+/** Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input */
+export async function pressOnElement(access, 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 access.waitForActionable("press", PRESS_CHECKS, { scroll: true, hitTest: false }, options);
+    await callOnElement(access, undefined, `el.focus();`);
+    await pressKey(access.connector, access.contextId, code);
+}
+/** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
+export async function fillElement(access, 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 access.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(access.connector, access.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 pause(access.connector, access.contextId, DEFAULT_PAUSE_MS);
+    await callOnElement(access, undefined, `if (typeof el.select === "function") el.select();`);
+    await typeText(access.connector, access.contextId, keys);
+    save?.(value);
+}

package/dist/locator/element-reads.d.ts

@@ -1,4 +1,29 @@
-/** Body run in the page as `(el) => { ... }`: a checked checkbox or radio input, or `aria-checked="true"` */
-export declare const IS_CHECKED_BODY = "\n  const type = (el.getAttribute(\"type\") || \"\").toLowerCase();\n  const input = el.tagName === \"INPUT\" && (type === \"checkbox\" || type === \"radio\");\n  return (input && el.checked) || el.getAttribute(\"aria-checked\") === \"true\";";
-/** The CSS property name for `getPropertyValue`: camelCase becomes kebab-case (`backgroundColor` to `background-color`), `--custom` and kebab-case names are kept */
-export declare function cssPropertyName(name: string): string;
+import type { ElementRectangle } from "../types/bidi-modules/browsing-context.js";
+import { type ActionabilityContext } from "./actionability.js";
+import { type ElementAccess } from "./element-access.js";
+/** Trimmed text content, or null when the element is missing */
+export declare function readTextContent(access: ElementAccess): Promise<string | null>;
+/** The accessible name (see `ACCESSIBLE_NAME_JS`), "" when it has none, or null when the element is missing */
+export declare function readAccessibleName(access: ElementAccess): Promise<string | null>;
+/** The accessible description, "" when it has none, or null when the element is missing */
+export declare function readAccessibleDescription(access: ElementAccess): Promise<string | null>;
+/** Value of an input/textarea/select, or null when missing */
+export declare function readInputValue(access: ElementAccess): Promise<string | null>;
+/** Attribute value, or null when the element or attribute is missing */
+export declare function readAttribute(access: ElementAccess, name: string): Promise<string | null>;
+/** Whether a checkbox or radio input is checked or the element has `aria-checked="true"`; null when the element is missing */
+export declare function readIsChecked(access: ElementAccess): Promise<boolean | null>;
+/** The class attribute as written ("" when the element has none), or null when the element is missing */
+export declare function readClassAttribute(access: ElementAccess): Promise<string | null>;
+/** Computed value of a CSS property (camelCase names become kebab-case, `--custom` is kept), or null when the element is missing */
+export declare function readCssValue(access: ElementAccess, name: string): Promise<string | null>;
+/** The browser's getBoundingClientRect result for the element */
+export declare function readBoundingClientRect(access: ElementAccess): Promise<ElementRectangle>;
+/** Whether the element exists, has a non-empty box and is not hidden by CSS */
+export declare function readIsVisible(ctx: ActionabilityContext): Promise<boolean>;
+/** Whether the element exists and is not disabled; does not wait */
+export declare function readIsEnabled(ctx: ActionabilityContext): Promise<boolean>;
+/** Like `readIsEnabled`, but null when the element is missing, so callers can tell "disabled" from "not there"; does not wait */
+export declare function readEnabledState(ctx: ActionabilityContext): Promise<boolean | null>;
+/** Whether the element exists and accepts typing (enabled, not readonly, a text field); does not wait */
+export declare function readIsEditable(ctx: ActionabilityContext): Promise<boolean>;

package/dist/locator/element-reads.js

@@ -1,11 +1,92 @@
+import { probeState } from "./actionability.js";
+import { callOnElement, callOnExistingElement, } from "./element-access.js";
+import { describeType } from "./element-state.js";
+import { ACCESSIBLE_NAME_JS } from "./accessible-name.js";
 /** Body run in the page as `(el) => { ... }`: a checked checkbox or radio input, or `aria-checked="true"` */
-export const IS_CHECKED_BODY = `
+const IS_CHECKED_BODY = `
   const type = (el.getAttribute("type") || "").toLowerCase();
   const input = el.tagName === "INPUT" && (type === "checkbox" || type === "radio");
   return (input && el.checked) || el.getAttribute("aria-checked") === "true";`;
 /** The CSS property name for `getPropertyValue`: camelCase becomes kebab-case (`backgroundColor` to `background-color`), `--custom` and kebab-case names are kept */
-export function cssPropertyName(name) {
+function cssPropertyName(name) {
     if (name.startsWith("--"))
         return name;
     return name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
 }
+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)}"`);
+}
+/** Trimmed text content, or null when the element is missing */
+export async function readTextContent(access) {
+    return stringOrNull(await callOnElement(access, null, `return el.textContent.trim();`, [], [], "textContent"));
+}
+/** The accessible name (see `ACCESSIBLE_NAME_JS`), "" when it has none, or null when the element is missing */
+export async function readAccessibleName(access) {
+    return stringOrNull(await callOnElement(access, null, `${ACCESSIBLE_NAME_JS} return accessibleName(el);`, [], [], "accessibleName"));
+}
+/** The accessible description, "" when it has none, or null when the element is missing */
+export async function readAccessibleDescription(access) {
+    return stringOrNull(await callOnElement(access, null, `${ACCESSIBLE_NAME_JS} return accessibleDescription(el);`, [], [], "accessibleDescription"));
+}
+/** Value of an input/textarea/select, or null when missing */
+export async function readInputValue(access) {
+    return stringOrNull(await callOnElement(access, null, `return typeof el.value === "string" ? el.value : null;`, [], [], "inputValue"));
+}
+/** Attribute value, or null when the element or attribute is missing */
+export async function readAttribute(access, name) {
+    return stringOrNull(await callOnElement(access, null, `return el.getAttribute(name);`, ["name"], [name], "getAttribute"));
+}
+/** Whether a checkbox or radio input is checked or the element has `aria-checked="true"`; null when the element is missing */
+export async function readIsChecked(access) {
+    return booleanOrNull(await callOnElement(access, null, IS_CHECKED_BODY, [], [], "isChecked"));
+}
+/** The class attribute as written ("" when the element has none), or null when the element is missing */
+export async function readClassAttribute(access) {
+    return stringOrNull(await callOnElement(access, null, `return el.getAttribute("class") ?? "";`, [], [], "classAttribute"));
+}
+/** Computed value of a CSS property (camelCase names become kebab-case, `--custom` is kept), or null when the element is missing */
+export async function readCssValue(access, name) {
+    return stringOrNull(await callOnElement(access, null, `return getComputedStyle(el).getPropertyValue(name);`, ["name"], [cssPropertyName(name)], "cssValue"));
+}
+/** The browser's getBoundingClientRect result for the element */
+export async function readBoundingClientRect(access) {
+    const rect = await callOnExistingElement(access, `
+      const { x, y, width, height, top, right, bottom, left } = el.getBoundingClientRect();
+      return { x, y, width, height, top, right, bottom, left };
+    `, "getBoundingClientRect");
+    if (typeof rect !== "object" || rect === null) {
+        throw new Error(`Expected to receive an object but instead received "${describeType(rect)}"`);
+    }
+    return rect;
+}
+/** Whether the element exists, has a non-empty box and is not hidden by CSS */
+export async function readIsVisible(ctx) {
+    const state = await probeState(ctx, { scroll: false, hitTest: false }, "isVisible");
+    return state.attached && state.visible;
+}
+/** Whether the element exists and is not disabled; does not wait */
+export async function readIsEnabled(ctx) {
+    const state = await probeState(ctx, { scroll: false, hitTest: false }, "isEnabled");
+    return state.attached && state.enabled;
+}
+/** Like `readIsEnabled`, but null when the element is missing, so callers can tell "disabled" from "not there"; does not wait */
+export async function readEnabledState(ctx) {
+    const state = await probeState(ctx, { scroll: false, hitTest: false }, "enabledState");
+    return state.attached ? state.enabled : null;
+}
+/** Whether the element exists and accepts typing (enabled, not readonly, a text field); does not wait */
+export async function readIsEditable(ctx) {
+    const state = await probeState(ctx, { scroll: false, hitTest: false }, "isEditable");
+    return state.attached && state.editable;
+}

package/dist/locator/element-state.d.ts

@@ -22,6 +22,11 @@ export interface ProbeOptions {
     scroll: boolean;
     /** Check which element receives a click at the element's centre */
     hitTest: boolean;
+    /**
+     * Probe a checkbox, radio or switch the way a user reaches it: opacity 0 does not hide it, and a click on
+     * one of its labels counts as hitting it (`control-probe.ts`). Only the check actions set this
+     */
+    control?: boolean;
 }
 export type WaitForState = "attached" | "detached" | "visible" | "hidden";
 export type CheckName = "attached" | "visible" | "stable" | "enabled" | "editable" | "hit target";

package/dist/locator/element-state.js

@@ -1,3 +1,4 @@
+import { CONTROL_PROBE_BRANCH } from "./control-probe.js";
 const TEXT_INPUT_TYPES = [
     "text",
     "search",
@@ -26,6 +27,7 @@ export const PROBE_ELEMENT = `(el, options) => {
   if (!el || !el.isConnected) {
     return ${JSON.stringify(DETACHED_STATE)};
   }
+  ${CONTROL_PROBE_BRANCH}
   if (options.scroll) {
     const before = el.getBoundingClientRect();
     const inViewport = before.top >= 0 && before.left >= 0 &&

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

@@ -3,7 +3,7 @@ import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js"
 import type { ElementHandle } from "../script/element-handle.js";
 import type { Arg } from "../script/serialize.js";
 import { type FileInput } from "../browser/generated-files.js";
-import type { CheckName, ProbeOptions } from "./element-state.js";
+import type { CheckName, ElementState, ProbeOptions } from "./element-state.js";
 import type { ActionOptions } from "./actionability.js";
 /** What the file actions need of a locator */
 export interface ElementContext {
@@ -12,7 +12,7 @@ export interface ElementContext {
     /** The locator's description for error messages */
     readonly selector: string;
     call<T>(fn: string, args: Arg[], sandbox?: string): Promise<T>;
-    waitForActionable(action: string, checks: readonly CheckName[], probe: ProbeOptions, options: ActionOptions | undefined): Promise<unknown>;
+    waitForActionable(action: string, checks: readonly CheckName[], probe: ProbeOptions, options: ActionOptions | undefined): Promise<ElementState>;
     /** The element the locator matches now; throws when none does */
     requireElement(): Promise<ElementHandle>;
     /** The error for an operation that needs an element when none matches */

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

@@ -0,0 +1,24 @@
+import type { ElementHandle } from "../script/element-handle.js";
+import type { CallInPage } from "./chain-resolver.js";
+import type { FilterTests, Selector, TextCriterion } from "./selector.js";
+/** What `filter()` and the options of `locator(selector, options)` take; `has` and `hasNot` are locators searched inside each candidate */
+export interface FilterOptions<L = unknown> {
+    /** Keeps elements whose text contains this string (case-insensitive, whitespace collapsed), or matches this RegExp (tested on the text as it is) */
+    hasText?: TextCriterion;
+    /** Keeps elements whose text does not contain / match it */
+    hasNotText?: TextCriterion;
+    /** Keeps elements that contain a match of this locator, searched inside the element */
+    has?: L;
+    /** Keeps elements that contain no match of this locator */
+    hasNot?: L;
+}
+/** The `filter` step for the options; `chainOf` reads the chain of a `has` / `hasNot` locator (and rejects one with fallbacks) */
+export declare function filterSelector<L>(options: FilterOptions<L>, chainOf: (locator: L, option: string) => readonly Selector[]): Selector;
+/** What applying a filter needs: the page, and a search of a chain inside one element */
+export interface FilterContext {
+    call: CallInPage;
+    /** The first match of `chain` inside `start` (its first step is scoped to it), or none */
+    findInside(chain: readonly Selector[], start: ElementHandle): Promise<ElementHandle[]>;
+}
+/** The candidates that pass every test of the filter, in their order */
+export declare function applyFilter(candidates: readonly ElementHandle[], tests: FilterTests, { call, findInside }: FilterContext): Promise<ElementHandle[]>;

package/dist/locator/filter-step.js

@@ -0,0 +1,72 @@
+const OPTION_NAMES = ["hasText", "hasNotText", "has", "hasNot"];
+function checkText(name, value) {
+    if (value !== undefined &&
+        typeof value !== "string" &&
+        !(value instanceof RegExp)) {
+        throw new TypeError(`filter(): ${name} must be a string or a RegExp`);
+    }
+}
+/** The `filter` step for the options; `chainOf` reads the chain of a `has` / `hasNot` locator (and rejects one with fallbacks) */
+export function filterSelector(options, chainOf) {
+    if (typeof options !== "object" || options === null) {
+        throw new TypeError("filter(): options must be an object");
+    }
+    const given = OPTION_NAMES.filter((name) => options[name] !== undefined);
+    if (given.length === 0) {
+        throw new TypeError("filter(): give at least one of hasText, hasNotText, has or hasNot");
+    }
+    checkText("hasText", options.hasText);
+    checkText("hasNotText", options.hasNotText);
+    const tests = {};
+    if (options.hasText !== undefined)
+        tests.hasText = options.hasText;
+    if (options.hasNotText !== undefined)
+        tests.hasNotText = options.hasNotText;
+    if (options.has !== undefined)
+        tests.has = chainOf(options.has, "has");
+    if (options.hasNot !== undefined)
+        tests.hasNot = chainOf(options.hasNot, "hasNot");
+    return { kind: "filter", ...tests };
+}
+/**
+ * Function declaration run in the page as `(elements, hasText, hasNotText)`: the elements whose
+ * `textContent` passes both tests. A string test is a substring match with whitespace collapsed and case
+ * ignored (Playwright's `hasText`); a RegExp is tested on the text as it is, without its `g` and `y` flags.
+ */
+const TEXT_FILTER = `(elements, hasText, hasNotText) => {
+  const collapse = (text) => String(text).replace(/\\s+/g, " ").trim().toLowerCase();
+  const found = (el, wanted) => {
+    const text = el.textContent ?? "";
+    return typeof wanted === "string"
+      ? collapse(text).includes(collapse(wanted))
+      : new RegExp(wanted.source, wanted.flags.replace(/[gy]/g, "")).test(text);
+  };
+  return elements.filter((el) =>
+    (hasText === undefined || found(el, hasText)) &&
+    (hasNotText === undefined || !found(el, hasNotText)));
+}`;
+/** The candidates that pass every test of the filter, in their order */
+export async function applyFilter(candidates, tests, { call, findInside }) {
+    let kept = [...candidates];
+    if (tests.hasText !== undefined || tests.hasNotText !== undefined) {
+        kept = await call(TEXT_FILTER, [
+            kept,
+            tests.hasText,
+            tests.hasNotText,
+        ]);
+    }
+    for (const [chain, wanted] of [
+        [tests.has, true],
+        [tests.hasNot, false],
+    ]) {
+        if (!chain)
+            continue;
+        const passing = [];
+        for (const candidate of kept) {
+            if ((await findInside(chain, candidate)).length > 0 === wanted)
+                passing.push(candidate);
+        }
+        kept = passing;
+    }
+    return kept;
+}

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

@@ -10,4 +10,4 @@
  *
  * A string, so the transpiler cannot inject helpers that do not exist in the page.
  */
-export declare const LABEL_LOCATE = "(starts, value, match, ignoreCase) => {\n  \n  const normalise = (text) => {\n    const collapsed = String(text).replace(/\\s+/g, \" \").trim();\n    return ignoreCase ? collapsed.toLowerCase() : collapsed;\n  };\n  const wanted = normalise(value);\n  const textMatches = (text) => {\n    const normal = normalise(text);\n    return match === \"full\" ? normal === wanted : normal.includes(wanted);\n  };\n  const textOf = (node) => node.innerText ?? node.textContent ?? \"\";\n  const labelsOf = (el) => {\n    const texts = [];\n    if (el.labels) for (const label of el.labels) texts.push(textOf(label));\n    const by = el.getAttribute(\"aria-labelledby\");\n    if (by) {\n      for (const id of by.split(/\\s+/)) {\n        const named = id && document.getElementById(id);\n        if (named) texts.push(textOf(named));\n      }\n    }\n    const own = el.getAttribute(\"aria-label\");\n    if (own) texts.push(own);\n    return texts;\n  };\n  const roots = starts.length > 0 ? starts : [document];\n  const seen = new Set();\n  const matches = [];\n  for (const root of roots) {\n    for (const el of root.querySelectorAll(\"*\")) {\n      if (seen.has(el)) continue;\n      seen.add(el);\n      if (labelsOf(el).some(textMatches)) matches.push(el);\n    }\n  }\n  return matches.sort((a, b) => (a === b ? 0 : a.compareDocumentPosition(b) & 4 ? -1 : 1));\n}";
+export declare const LABEL_LOCATE = "(starts, value, match, ignoreCase) => {\n  \n  const collapse = (text) => String(text).replace(/\\s+/g, \" \").trim();\n  const normalise = (text) => {\n    const collapsed = collapse(text);\n    return ignoreCase ? collapsed.toLowerCase() : collapsed;\n  };\n  const pattern = typeof value === \"string\" ? null : new RegExp(value.source, value.flags.replace(/[gy]/g, \"\"));\n  const wanted = pattern ? \"\" : normalise(value);\n  const textMatches = (text) => {\n    if (pattern) return pattern.test(collapse(text));\n    const normal = normalise(text);\n    return match === \"full\" ? normal === wanted : normal.includes(wanted);\n  };\n  const textOf = (node) => node.innerText ?? node.textContent ?? \"\";\n  const labelsOf = (el) => {\n    const texts = [];\n    if (el.labels) for (const label of el.labels) texts.push(textOf(label));\n    const by = el.getAttribute(\"aria-labelledby\");\n    if (by) {\n      for (const id of by.split(/\\s+/)) {\n        const named = id && document.getElementById(id);\n        if (named) texts.push(textOf(named));\n      }\n    }\n    const own = el.getAttribute(\"aria-label\");\n    if (own) texts.push(own);\n    return texts;\n  };\n  const roots = starts.length > 0 ? starts : [document];\n  const seen = new Set();\n  const matches = [];\n  for (const root of roots) {\n    for (const el of root.querySelectorAll(\"*\")) {\n      if (seen.has(el)) continue;\n      seen.add(el);\n      if (labelsOf(el).some(textMatches)) matches.push(el);\n    }\n  }\n  return matches.sort((a, b) => (a === b ? 0 : a.compareDocumentPosition(b) & 4 ? -1 : 1));\n}";

package/dist/locator/locator.d.ts

@@ -1,12 +1,17 @@
 import type { BiDiConnector } from "../transport/bidi-connection.js";
 import type { BrowsingContext, ElementRectangle } from "../types/bidi-modules/browsing-context.js";
 import { ElementHandle } from "../script/element-handle.js";
-import { type ElementScreenshotOptions } from "../browser/screenshot.js";
+import type { ElementScreenshotOptions } from "../browser/screenshot.js";
 import type { FileInput } from "../browser/generated-files.js";
 import { type ActionOptions } from "./actionability.js";
-import { type WaitForState } from "./element-state.js";
+import { type CheckOptions } from "./check-actions.js";
+import type { WaitForState } from "./element-state.js";
 import type { HelperInstaller } from "./helper-realm.js";
-import { type Selector, type TextOptions } from "./selector.js";
+import { type StrictSource } from "./strict-mode.js";
+import type { RoleOptions } from "./role-locator.js";
+import { type Selector, type ExactOption, type TextOptions } from "./selector.js";
+import { type SelectOptionValue } from "./select-actions.js";
+import { type FilterOptions } from "./filter-step.js";
 export type { ActionOptions } from "./actionability.js";
 export default class Locator {
     private biDiConnector;
@@ -14,19 +19,23 @@ export default class Locator {
     private chain;
     private helpers;
     private alternatives;
+    private strictness;
+    /** Asked once per locator: the answer comes from the config, which a wait would otherwise read on every poll */
+    private strictAnswer;
     private matched;
     private resolver;
     /** What the actionability waits use of this locator */
     private actionability;
-    /** What the file actions use of this locator */
-    private elementContext;
+    /** What the reads and actions use of this locator */
+    private access;
     /**
      * `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: string | readonly Selector[], biDiConnector: BiDiConnector, contextId: BrowsingContext, helpers?: HelperInstaller, alternatives?: readonly Locator[]);
+    constructor(selector: string | readonly Selector[], biDiConnector: BiDiConnector, contextId: BrowsingContext, helpers?: HelperInstaller, alternatives?: readonly Locator[], strictness?: StrictSource);
     /**
      * The description of this locator used in error messages, e.g. `//form >> role=button[name="Save"]`;
      * fallbacks follow as `or …`
@@ -43,6 +52,14 @@ export default class Locator {
      *  page.getByTestId("save").withFallbacks(page.getByRole("button", { name: "Save" }), page.getByText("Save"));
      */
     withFallbacks(...fallbacks: Locator[]): Locator;
+    /**
+     * 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?: boolean): Locator;
     /**
      * 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.
@@ -51,20 +68,49 @@ export default class Locator {
         index: number;
         selector: string;
     } | undefined;
-    /** Elements matching the label text (`<label>`, `aria-labelledby`, `aria-label`), inside this locator's matches */
-    getByLabel(text: string, options?: TextOptions): Locator;
+    /** Elements matching the label text (`<label>`, `aria-labelledby`, `aria-label`), inside this locator's matches. See `TextOptions` for `exact` and RegExp */
+    getByLabel(text: string | RegExp, options?: TextOptions): Locator;
+    /** Elements whose `placeholder` matches, inside this locator's matches. See `TextOptions` for `exact` and RegExp */
+    getByPlaceholder(text: string | RegExp, options?: ExactOption): Locator;
+    /** Elements whose `alt` text matches (images, areas, image inputs), inside this locator's matches. See `TextOptions` */
+    getByAltText(text: string | RegExp, options?: ExactOption): Locator;
+    /** Elements whose `title` attribute matches, inside this locator's matches. See `TextOptions` */
+    getByTitle(text: string | RegExp, options?: ExactOption): Locator;
     /** Elements whose `data-testid` attribute equals `testId`, inside this locator's matches */
     getByTestId(testId: string): Locator;
-    /** Elements matching `xpath` inside this locator's matches (relative and `//` paths search inside them) */
-    locator(xpath: string): Locator;
+    /**
+     * 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: string, options?: FilterOptions<Locator>): Locator;
     /** Elements matching the CSS selector inside this locator's matches */
     getByCss(css: string): Locator;
-    /** Elements whose text matches, inside this locator's matches. Exact match unless `match: "partial"` */
-    getByText(text: string, options?: TextOptions): Locator;
-    /** Elements with the ARIA role (and accessible name, when given), inside this locator's matches */
-    getByRole(role: string, options?: {
-        name?: string;
-    }): Locator;
+    /** 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: string | RegExp, options?: TextOptions): Locator;
+    /** Elements with the ARIA role (and accessible name and state, when given), inside this locator's matches. See `RoleOptions` */
+    getByRole(role: string, options?: RoleOptions): Locator;
+    /** 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: number): Locator;
+    /**
+     * 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: FilterOptions<Locator>): Locator;
+    /** The elements both this locator and `other` match, in this locator's order */
+    and(other: Locator): Locator;
+    /** The elements either this locator or `other` matches, in document order, each once */
+    or(other: Locator): Locator;
+    private combined;
+    /** The chain of a locator used inside another (`has`); a locator with fallbacks cannot be */
+    private chainFor;
+    /** The first match, in document order */
+    first(): Locator;
+    /** The last match, in document order */
+    last(): Locator;
     /** One locator per element currently matching, in document order */
     all(): Promise<Locator[]>;
     /**
@@ -76,24 +122,35 @@ export default class Locator {
     /** The primary or the first fallback that currently matches, without its own fallbacks */
     private firstMatching;
     private withoutFallbacks;
-    private resolveOne;
-    /** Calls `fn` in the page; a throwing function becomes a "Failed to locate element" error */
-    private call;
     /**
-     * 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)
      */
-    private callOnElement;
-    /** Like `callOnElement`, for operations that cannot go on without the element */
-    private callOnExistingElement;
-    /** The error for an operation that needs an element when none matches */
-    private noElementError;
-    /** The element the locator matches now; throws when none does */
-    private requireElement;
-    private probeState;
+    private resolveOne;
     private waitForActionable;
     /** Waits until the element is attached, visible, stable, enabled and not covered, then clicks its centre with real pointer input */
     click(options?: ActionOptions): Promise<void>;
+    /**
+     * 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();
+     */
+    check(options?: CheckOptions): Promise<void>;
+    /** Unchecks a checkbox or `role=checkbox|switch` element; does nothing when it is already unchecked. A radio button cannot be unchecked: throws */
+    uncheck(options?: CheckOptions): Promise<void>;
+    /** `check()` or `uncheck()`, whichever brings the element to `checked` */
+    setChecked(checked: boolean, options?: CheckOptions): Promise<void>;
+    /**
+     * 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" }]);
+     */
+    selectOption(values: SelectOptionValue | SelectOptionValue[], options?: ActionOptions): Promise<string[]>;
     /**
      * Sets the files of an `<input type=file>`; `[]` clears it. Paths are relative to the project folder (absolute
      * ones are used as they are); `generatedFile(…)` writes a file of a given size when the step runs.
@@ -136,6 +193,8 @@ export default class Locator {
     getBoundingClientRect(): Promise<ElementRectangle>;
     /** Whether the element exists, has a non-empty box and is not hidden by CSS */
     isVisible(): Promise<boolean>;
+    /** The opposite of `isVisible`: true for a hidden element and for one that is not there */
+    isHidden(): Promise<boolean>;
     /** Trimmed text content, or null when the element is missing */
     textContent(): Promise<string | null>;
     /** Value of an input/textarea/select, or null when missing */
@@ -148,10 +207,16 @@ export default class Locator {
     count(): Promise<number>;
     /** Whether the element exists and is not disabled; does not wait */
     isEnabled(): Promise<boolean>;
+    /** The opposite of `isEnabled`: true for a disabled element and for one that is not there; does not wait */
+    isDisabled(): Promise<boolean>;
     /** Like `isEnabled`, but null when the element is missing, so callers can tell "disabled" from "not there"; does not wait */
     enabledState(): Promise<boolean | null>;
     /** Whether a checkbox or radio input is checked or the element has `aria-checked="true"`; null when the element is missing */
     isChecked(): Promise<boolean | null>;
+    /** The accessible name (what `getByRole`'s `name` is matched against), "" when there is none, or null when the element is missing */
+    accessibleName(): Promise<string | null>;
+    /** The accessible description (`aria-describedby`, `aria-description`, else `title` when it is not the name), or null when the element is missing */
+    accessibleDescription(): Promise<string | null>;
     /** The class attribute as written ("" when the element has none), or null when the element is missing */
     classAttribute(): Promise<string | null>;
     /** Computed value of a CSS property (camelCase names become kebab-case, `--custom` is kept), or null when the element is missing */