@itmetsam/samurai-framework 0.1.0 → 0.2.0

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

@@ -0,0 +1,44 @@
+export interface ElementBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ElementState {
+    attached: boolean;
+    visible: boolean;
+    enabled: boolean;
+    editable: boolean;
+    /** Viewport coordinates after any scroll; null when not attached */
+    box: ElementBox | null;
+    /**
+     * "self" when a click at the element's centre reaches it, otherwise a description of
+     * the covering element ("nothing" when no element is there); null when not checked
+     */
+    hitTarget: string | null;
+}
+export interface ProbeOptions {
+    /** Scroll the element into view first when it is not fully inside the viewport */
+    scroll: boolean;
+    /** Check which element receives a click at the element's centre */
+    hitTest: boolean;
+}
+export type WaitForState = "attached" | "detached" | "visible" | "hidden";
+export type CheckName = "attached" | "visible" | "stable" | "enabled" | "editable" | "hit target";
+export type CheckResult = "pass" | "fail" | "pending";
+/** Results keyed by check name, in the order the checks were evaluated */
+export type CheckResults = Partial<Record<CheckName, CheckResult>>;
+/** State of an element that is not in the document (never matched, or gone) */
+export declare const DETACHED_STATE: ElementState;
+/**
+ * Function declaration run in the page through `script.callFunction` as `(el, options)`, where `el`
+ * is the located element. Returns its state as a plain object in one round trip. Kept as a string so
+ * the transpiler cannot inject helpers (`__name`) that do not exist in the page.
+ * A node that was removed from the document stays resolvable in the browser, hence `isConnected`.
+ */
+export declare const PROBE_ELEMENT: string;
+/** Checks the probe result is a complete state; throws on anything else */
+export declare function parseElementState(value: unknown): ElementState;
+/** Evaluates the required checks in order; after the first failure the rest are pending */
+export declare function evaluateChecks(required: readonly CheckName[], current: ElementState, previous: ElementState | undefined): CheckResults;
+export declare function allPass(results: CheckResults): boolean;

package/dist/locator/element-state.js

@@ -0,0 +1,109 @@
+const TEXT_INPUT_TYPES = ["text", "search", "email", "url", "tel", "password", "number"];
+/** State of an element that is not in the document (never matched, or gone) */
+export const DETACHED_STATE = {
+    attached: false,
+    visible: false,
+    enabled: false,
+    editable: false,
+    box: null,
+    hitTarget: null,
+};
+/**
+ * Function declaration run in the page through `script.callFunction` as `(el, options)`, where `el`
+ * is the located element. Returns its state as a plain object in one round trip. Kept as a string so
+ * the transpiler cannot inject helpers (`__name`) that do not exist in the page.
+ * A node that was removed from the document stays resolvable in the browser, hence `isConnected`.
+ */
+export const PROBE_ELEMENT = `(el, options) => {
+  if (!el || !el.isConnected) {
+    return { attached: false, visible: false, enabled: false, editable: false, box: null, hitTarget: null };
+  }
+  if (options.scroll) {
+    const before = el.getBoundingClientRect();
+    const inViewport = before.top >= 0 && before.left >= 0 &&
+      before.bottom <= window.innerHeight && before.right <= window.innerWidth;
+    if (!inViewport) el.scrollIntoView({ block: "center", inline: "center" });
+  }
+  const rect = el.getBoundingClientRect();
+  const style = getComputedStyle(el);
+  const visible = rect.width > 0 && rect.height > 0 &&
+    style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0";
+  const enabled = !el.matches(":disabled") && el.getAttribute("aria-disabled") !== "true";
+  const tag = el.tagName.toLowerCase();
+  const typeable = Boolean(
+    (tag === "input" && ${JSON.stringify(TEXT_INPUT_TYPES)}.includes((el.getAttribute("type") || "text").toLowerCase())) ||
+    tag === "textarea" || el.isContentEditable);
+  const editable = Boolean(enabled && !el.readOnly && typeable);
+  let hitTarget = null;
+  if (options.hitTest) {
+    const top = document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
+    hitTarget = !top ? "nothing"
+      : top === el || el.contains(top) ? "self"
+      : top.tagName.toLowerCase() + (top.id ? "#" + top.id : "") +
+        Array.from(top.classList, (name) => "." + name).join("");
+  }
+  return {
+    attached: true, visible, enabled, editable,
+    box: { x: rect.left, y: rect.top, width: rect.width, height: rect.height },
+    hitTarget,
+  };
+}`;
+/** Checks the probe result is a complete state; throws on anything else */
+export function parseElementState(value) {
+    if (typeof value !== "object" || value === null) {
+        throw new Error(`Expected an element state object but received "${describeType(value)}"`);
+    }
+    const state = value;
+    const flags = ["attached", "visible", "enabled", "editable"];
+    if (flags.some((flag) => typeof state[flag] !== "boolean") ||
+        !("box" in state) ||
+        !("hitTarget" in state)) {
+        throw new Error(`Malformed element state: ${JSON.stringify(value)}`);
+    }
+    return state;
+}
+function describeType(value) {
+    return value === null ? "null" : typeof value;
+}
+function sameBox(a, b) {
+    return (a !== null &&
+        b !== null &&
+        a.x === b.x &&
+        a.y === b.y &&
+        a.width === b.width &&
+        a.height === b.height);
+}
+function checkPasses(name, current, previous) {
+    switch (name) {
+        case "attached":
+            return current.attached;
+        case "visible":
+            return current.visible;
+        case "stable":
+            return sameBox(current.box, previous?.box ?? null);
+        case "enabled":
+            return current.enabled;
+        case "editable":
+            return current.editable;
+        case "hit target":
+            return current.hitTarget === "self";
+    }
+}
+/** Evaluates the required checks in order; after the first failure the rest are pending */
+export function evaluateChecks(required, current, previous) {
+    const results = {};
+    let failed = false;
+    for (const name of required) {
+        if (failed) {
+            results[name] = "pending";
+            continue;
+        }
+        const pass = checkPasses(name, current, previous);
+        results[name] = pass ? "pass" : "fail";
+        failed = !pass;
+    }
+    return results;
+}
+export function allPass(results) {
+    return Object.values(results).every((result) => result === "pass");
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Function declaration run in the page as `(starts, value, match, ignoreCase)`; returns the elements
+ * named by a label whose text matches. BiDi has no label locator, so the framework does it.
+ *
+ * - An element's labels are its `<label>`s (`el.labels`: `for=`, nesting), the elements its
+ *   `aria-labelledby` points to, and its `aria-label`.
+ * - Searches the descendants of every start node (the whole document when there are none).
+ * - Text is whitespace collapsed and trimmed; `full` needs equality, `partial` a substring.
+ * - Results are unique and in document order.
+ *
+ * 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  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 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      const found = labelsOf(el).some((text) => {\n        const normal = normalise(text);\n        return match === \"full\" ? normal === wanted : normal.includes(wanted);\n      });\n      if (found) matches.push(el);\n    }\n  }\n  return matches.sort((a, b) => (a === b ? 0 : a.compareDocumentPosition(b) & 4 ? -1 : 1));\n}";

package/dist/locator/label-locator.js

@@ -0,0 +1,49 @@
+/**
+ * Function declaration run in the page as `(starts, value, match, ignoreCase)`; returns the elements
+ * named by a label whose text matches. BiDi has no label locator, so the framework does it.
+ *
+ * - An element's labels are its `<label>`s (`el.labels`: `for=`, nesting), the elements its
+ *   `aria-labelledby` points to, and its `aria-label`.
+ * - Searches the descendants of every start node (the whole document when there are none).
+ * - Text is whitespace collapsed and trimmed; `full` needs equality, `partial` a substring.
+ * - Results are unique and in document order.
+ *
+ * A string, so the transpiler cannot inject helpers that do not exist in the page.
+ */
+export const LABEL_LOCATE = `(starts, value, match, ignoreCase) => {
+  const normalise = (text) => {
+    const collapsed = String(text).replace(/\\s+/g, " ").trim();
+    return ignoreCase ? collapsed.toLowerCase() : collapsed;
+  };
+  const wanted = normalise(value);
+  const textOf = (node) => node.innerText ?? node.textContent ?? "";
+  const labelsOf = (el) => {
+    const texts = [];
+    if (el.labels) for (const label of el.labels) texts.push(textOf(label));
+    const by = el.getAttribute("aria-labelledby");
+    if (by) {
+      for (const id of by.split(/\\s+/)) {
+        const named = id && document.getElementById(id);
+        if (named) texts.push(textOf(named));
+      }
+    }
+    const own = el.getAttribute("aria-label");
+    if (own) texts.push(own);
+    return texts;
+  };
+  const roots = starts.length > 0 ? starts : [document];
+  const seen = new Set();
+  const matches = [];
+  for (const root of roots) {
+    for (const el of root.querySelectorAll("*")) {
+      if (seen.has(el)) continue;
+      seen.add(el);
+      const found = labelsOf(el).some((text) => {
+        const normal = normalise(text);
+        return match === "full" ? normal === wanted : normal.includes(wanted);
+      });
+      if (found) matches.push(el);
+    }
+  }
+  return matches.sort((a, b) => (a === b ? 0 : a.compareDocumentPosition(b) & 4 ? -1 : 1));
+}`;

package/dist/locator/locator.d.ts

@@ -0,0 +1,168 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BrowsingContext, ElementRectangle } from "../types/bidi-modules/browsing-context.js";
+import { type HelperInstaller } from "../script/helpers.js";
+import { ElementHandle } from "../script/element-handle.js";
+import { type ElementScreenshotOptions } from "../browser/screenshot.js";
+import { type WaitForState } from "./element-state.js";
+import { type Selector, type TextOptions } from "./selector.js";
+export type { WaitForState } from "./element-state.js";
+export { InvalidSelectorError, UnsupportedOperationError, } from "./selector-errors.js";
+export type { TextOptions } from "./selector.js";
+export interface ActionOptions {
+    /**
+     * Time (ms) to wait for the element to become actionable. Defaults to config `expect.timeout`, then 5000.
+     * 0 checks once without waiting; the stability check is skipped because it needs two probes
+     */
+    timeout?: number;
+    /** Skip every actionability check except "attached" */
+    force?: boolean;
+}
+export default class Locator {
+    private biDiConnector;
+    private contextId;
+    private chain;
+    private helpers;
+    private alternatives;
+    private matched;
+    /**
+     * `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: string | readonly Selector[], biDiConnector: BiDiConnector, contextId: BrowsingContext, helpers?: HelperInstaller, alternatives?: readonly Locator[]);
+    /**
+     * The description of this locator used in error messages, e.g. `//form >> role=button[name="Save"]`;
+     * fallbacks follow as `or …`
+     */
+    get selector(): string;
+    /** Steps that keep the fallbacks: each fallback gets the same step, so "inside A or B" stays meaningful */
+    private child;
+    /**
+     * 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: Locator[]): 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.
+     */
+    get matchedBy(): {
+        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 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 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;
+    /** One locator per element currently matching, in document order */
+    all(): Promise<Locator[]>;
+    /**
+     * 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.
+     */
+    private resolve;
+    /** The primary or the first fallback that currently matches, without its own fallbacks */
+    private firstMatching;
+    private withoutFallbacks;
+    private resolveChain;
+    private resolveOne;
+    private locateStep;
+    private locateNatively;
+    /** Text search done in the page, for browsers without BiDi's innerText locator */
+    private locateByText;
+    /** Runs a page-side search `(starts, value, match, ignoreCase) => elements` */
+    private locateInPage;
+    /** 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.
+     */
+    private callOnElement;
+    /** Like `callOnElement`, for operations that cannot go on without the element */
+    private callOnExistingElement;
+    /** Reads the element's actionability state: one search, one probe */
+    private probeState;
+    private callProbe;
+    /**
+     * Probes until every required check passes and returns that state.
+     * Throws ActionTimeoutError describing the last probe on timeout.
+     */
+    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>;
+    /** 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);
+     */
+    clickRect(rect: Pick<ElementRectangle, "x" | "y" | "width" | "height">): Promise<void>;
+    /**
+     * 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([]);
+     */
+    setInputFiles(files: string | string[], options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * 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" });
+     */
+    screenshot(options?: ElementScreenshotOptions & {
+        timeout?: number;
+    }): Promise<Buffer>;
+    /** Waits until the element is attached, then focuses it */
+    focus(options?: ActionOptions): Promise<void>;
+    /** Waits until the element reaches `state` (default "visible"); does not scroll */
+    waitFor({ state, timeout, }?: {
+        state?: WaitForState;
+        timeout?: number;
+    }): Promise<void>;
+    /** Returns the browser's getBoundingClientRect result for the given element */
+    getBoundingClientRect(): Promise<ElementRectangle>;
+    private stringOrNull;
+    /** Whether the element exists, has a non-empty box and is not hidden by CSS */
+    isVisible(): 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 */
+    inputValue(): Promise<string | null>;
+    /** Attribute value, or null when the element or attribute is missing */
+    getAttribute(name: string): Promise<string | null>;
+    /** References to the elements currently matching, in document order. Internal: for tooling that identifies elements */
+    elements(): Promise<ElementHandle[]>;
+    /** Number of elements currently matching */
+    count(): Promise<number>;
+    /** Whether the element exists and is not disabled; does not wait */
+    isEnabled(): Promise<boolean>;
+    /** Whether the element exists and accepts typing (enabled, not readonly, a text field); does not wait */
+    isEditable(): Promise<boolean>;
+    /** Wait for certain time (ms). Default: 300ms  */
+    wait(duration?: number): Promise<void>;
+    /** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
+    fill(value: string, options?: ActionOptions): Promise<void>;
+}