effect-browser 0.2.0-beta.9 → 0.3.0-beta.5

package/src/internal/reading/controls.inpage.ts

@@ -0,0 +1,158 @@
+/**
+ * In the page: a control's states and value as the outline shows them, and as a value; the elements a CSS selector scopes a
+ * read to; and a condition `Page.waitFor` waits for. See `names.inpage.ts` for what a page-side part
+ * may use.
+ */
+import type { Control } from "../../Snapshot.ts";
+import type { Names } from "./names.inpage.ts";
+import type { Subjects } from "./subjects.inpage.ts";
+import type { Texts } from "./text.inpage.ts";
+import type { Walk } from "./walk.inpage.ts";
+
+/** What `waitUntil` waits for, as `Page.waitFor` asks it. */
+export interface ConditionRequest {
+  readonly selector: string | null;
+  readonly text: string | null;
+  readonly state: "visible" | "hidden" | "enabled";
+}
+
+/** Whether the condition held by the deadline, or why the selector is not CSS. */
+export type ConditionResult = { readonly met: boolean } | { readonly invalid: string };
+
+export const controls = (names: Names, walked: Walk, subjects: Subjects, texts: Texts) => {
+  const { clean, isDisabled, isHtml, isInput, isSelect, isTextArea, refFor, textOf } = names;
+  const { visible } = walked;
+  const { stateOf } = subjects;
+  const { shown } = texts;
+
+  // The states that hold, in the order `stateOf` gives them, after a heading's level.
+  const states = (element: Element, role: string | null): string => {
+    const { level, ...flags } = stateOf(element, role);
+    const held = Object.entries(flags).flatMap(([name, value]) => (value === true ? [name] : []));
+
+    return [...(level === undefined ? [] : [`level=${level}`]), ...held]
+      .map((name) => ` [${name}]`)
+      .join("");
+  };
+
+  const valueOf = (element: Element): string => {
+    if (isSelect(element)) {
+      const selected = Array.from(element.selectedOptions, (option) => clean(option.text, 40));
+
+      const options = Array.from(element.options)
+        .slice(0, 12)
+        .map((option) => clean(option.text, 40));
+
+      const more = element.options.length > 12 ? ` +${element.options.length - 12} more` : "";
+
+      return ` value=${JSON.stringify(selected.join(", "))} options=${JSON.stringify(options.join(" | ") + more)}`;
+    }
+    // The model sees what it typed, but never what a secret field holds.
+    const value = isInput(element) || isTextArea(element) ? shown(element, true) : undefined;
+
+    return value === undefined || value === "" ? "" : ` value=${JSON.stringify(clean(value, 80))}`;
+  };
+
+  // Inputs that take no typed text.
+  const untyped = ["button", "reset", "submit", "image", "checkbox", "radio", "file", "range"];
+
+  /** A control as a value, as its outline line shows it. */
+  const controlOf = (element: Element, role: string | null, kind: string, name: string) => {
+    const { disabled, checked } = stateOf(element, role);
+    const select = isSelect(element) ? element : undefined;
+
+    const value =
+      select !== undefined
+        ? Array.from(select.selectedOptions, (option) => clean(option.text, 80)).join(", ")
+        : isInput(element) || isTextArea(element)
+          ? clean(shown(element, true), 200)
+          : "";
+
+    const editable =
+      isTextArea(element) ||
+      (isInput(element) && !untyped.includes(element.type)) ||
+      (isHtml(element) && element.isContentEditable);
+
+    const control: typeof Control.Encoded = {
+      ref: refFor(element),
+      kind,
+      name,
+      value,
+      ...(select === undefined
+        ? {}
+        : {
+            options: Array.from(select.options)
+              .slice(0, 64)
+              .map((option) => clean(option.text, 80)),
+            optionCount: select.options.length,
+          }),
+      ...(disabled ? { disabled } : {}),
+      ...(checked === undefined ? {} : { checked }),
+      ...(editable ? { editable } : {}),
+    };
+
+    return control;
+  };
+
+  /**
+   * The elements a selector matches, each read whole, so one inside another that matched is left
+   * to it; or why the selector is not CSS.
+   */
+  const rootsOf = (selector: string): ReadonlyArray<Element> | { readonly invalid: string } => {
+    let matched: ReadonlyArray<Element>;
+
+    try {
+      matched = Array.from(document.querySelectorAll(selector));
+    } catch {
+      return { invalid: `${JSON.stringify(selector)} is not a CSS selector` };
+    }
+
+    return matched.filter(
+      (root) => !matched.some((other) => other !== root && other.contains(root)),
+    );
+  };
+
+  // Whether the condition holds now: what the selector matches, or the body, and shows, with the
+  // text when one is asked, case and all. A document has no body until its parser reaches one.
+  const holds = (request: ConditionRequest): ConditionResult => {
+    const roots =
+      request.selector === null ? [document.body].filter(Boolean) : rootsOf(request.selector);
+
+    if ("invalid" in roots) return roots;
+    const text = request.text === null ? null : clean(request.text, Infinity);
+
+    const showing = roots.filter(
+      (element) =>
+        visible(element) && (text === null || clean(textOf(element), Infinity).includes(text)),
+    );
+
+    return {
+      met:
+        request.state === "hidden"
+          ? showing.length === 0
+          : request.state === "enabled"
+            ? showing.some((element) => !isDisabled(element))
+            : showing.length > 0,
+    };
+  };
+
+  // Looks every 100 ms until the condition holds or the deadline passes.
+  const waitUntil = async (request: ConditionRequest, millis: number) => {
+    const until = performance.now() + millis;
+
+    for (;;) {
+      const result = holds(request);
+      const left = until - performance.now();
+
+      if ("invalid" in result || result.met || left <= 0) return result;
+      const { promise, resolve } = Promise.withResolvers<void>();
+
+      setTimeout(resolve, Math.min(100, left));
+      await promise;
+    }
+  };
+
+  return { controlOf, rootsOf, states, valueOf, waitUntil };
+};
+
+export type Controls = ReturnType<typeof controls>;

package/src/internal/reading/expect.inpage.ts

@@ -0,0 +1,70 @@
+/**
+ * In the page: the wait an expectation takes on what `find` matches, and the mark that stands for
+ * what the matches show. See `names.inpage.ts` for what a page-side part may use.
+ */
+import type { FindRequest } from "./match.inpage.ts";
+import type { Names } from "./names.inpage.ts";
+import type { Subjects } from "./subjects.inpage.ts";
+
+/**
+ * What an expectation waits for of a query's matches: some, none, or a mark other than one `until`
+ * gave before.
+ */
+export type Want = "some" | "none" | { readonly other: string };
+
+export const expectations = (names: Names, subjected: Subjects) => {
+  const { isInput, isSelect, isTextArea, roleOf, textOf } = names;
+  const { elementsOf, stateOf } = subjected;
+
+  // What matched elements show, their text, values and states but focus, as a mark that carries
+  // none of it: a count and FNV-1a over each in turn.
+  const markOf = (elements: ReadonlyArray<Element>) => {
+    let hash = 0x811c9dc5;
+
+    for (const element of elements) {
+      const { focused: _focused, ...state } = stateOf(element, roleOf(element));
+
+      const value =
+        isInput(element) || isSelect(element) || isTextArea(element) ? element.value : "";
+
+      const shown = `${textOf(element)}\u0000${value}\u0000${JSON.stringify(state)}\u0001`;
+
+      for (let index = 0; index < shown.length; index++)
+        hash = Math.imul(hash ^ shown.charCodeAt(index), 0x01000193);
+    }
+
+    return `${elements.length}:${(hash >>> 0).toString(16)}`;
+  };
+
+  /**
+   * What `find` matches, looked at every 100 ms until `want` holds of it or `millis` have passed,
+   * with its mark then. It gives no refs.
+   */
+  const until = async (request: FindRequest, want: Want, millis: number) => {
+    const deadline = performance.now() + millis;
+
+    for (;;) {
+      const elements = elementsOf(request);
+      const mark = markOf(elements);
+
+      const met =
+        want === "some"
+          ? elements.length > 0
+          : want === "none"
+            ? elements.length === 0
+            : mark !== want.other;
+
+      const left = deadline - performance.now();
+
+      if (met || left <= 0) return { met, mark };
+      const { promise, resolve } = Promise.withResolvers<void>();
+
+      setTimeout(resolve, Math.min(100, left));
+      await promise;
+    }
+  };
+
+  return { until };
+};
+
+export type Expectations = ReturnType<typeof expectations>;

package/src/internal/reading/match.inpage.ts

@@ -0,0 +1,92 @@
+/**
+ * In the page: the rules `find` matches by. It touches no DOM, so it also runs outside a page.
+ *
+ * - A role matches when it is the same token, ignoring case and the space around it.
+ * - A name given as a string matches when the two read the same once their spaces are collapsed,
+ *   their case folded and their characters given one Unicode form; a pattern matches when it
+ *   finds itself in the name.
+ * - Text matches when it appears, read the same way, in the element's text.
+ * - `near` matches when its words appear, whole and in order, in any of the element's context:
+ *   its row, column, label or heading. Replay chooses among candidates by the same rule.
+ */
+import type { SubjectContext } from "../../BrowserEvent.ts";
+
+/** A string, or a pattern sent to the page as its source and flags. */
+export type Wanted = string | { readonly source: string; readonly flags: string };
+
+export interface FindRequest {
+  readonly role: string | null;
+  readonly name: Wanted | null;
+  readonly text: Wanted | null;
+  readonly near: string | null;
+  readonly at: { readonly x: number; readonly y: number } | null;
+  readonly scope: "viewport" | "document";
+  readonly firstRef: number;
+}
+
+/** What a query is matched against, read only when a rule needs it. */
+export interface Candidate {
+  readonly role: string | null;
+  readonly name: () => string;
+  readonly text: () => string;
+  readonly context: () => SubjectContext;
+}
+
+export const match = () => {
+  /**
+   * How names, text and context compare: one Unicode form, without invisible format characters,
+   * spaces collapsed, and case folded upper first, so that "ß" and "SS" read the same.
+   */
+  const normalize = (value: string): string =>
+    value
+      .normalize("NFKC")
+      .replace(/\p{Cf}/gu, "")
+      .replace(/\s+/g, " ")
+      .trim()
+      .toUpperCase()
+      .toLowerCase();
+
+  /** A string that reads the same, or, unless `whole`, appears within; or a pattern found within. */
+  const rule = (wanted: Wanted, whole: boolean) => {
+    if (typeof wanted !== "string") {
+      // `g` and `y` keep a position from one test to the next, so one pattern would answer
+      // differently for each element. A pattern is tried on the text as the page shows it.
+      const found = new RegExp(wanted.source, wanted.flags.replace(/[gy]/g, ""));
+
+      return (value: string) => found.test(value.replace(/\s+/g, " ").trim());
+    }
+    const target = normalize(wanted);
+
+    return whole
+      ? (value: string) => normalize(value) === target
+      : (value: string) => normalize(value).includes(target);
+  };
+
+  /** Whether a value's words appear, whole and in order, among a text's: "BTC" not in "WBTC". */
+  const holds = (text: string, value: string) =>
+    ` ${normalize(text)} `.includes(` ${normalize(value)} `);
+
+  /** Whether a candidate meets every rule a query gives; a rule left out always holds. */
+  const compile = (request: Pick<FindRequest, "role" | "name" | "text" | "near">) => {
+    const role = request.role === null ? null : normalize(request.role);
+    const name = request.name === null ? null : rule(request.name, true);
+    const text = request.text === null ? null : rule(request.text, false);
+    const { near } = request;
+
+    return (candidate: Candidate): boolean => {
+      if (role !== null && normalize(candidate.role ?? "") !== role) return false;
+      if (text !== null && !text(candidate.text())) return false;
+      if (name !== null && !name(candidate.name())) return false;
+      if (near === null) return true;
+      const { row, column, label, heading } = candidate.context();
+
+      return [row, column, label, heading].some(
+        (value) => value !== undefined && holds(value, near),
+      );
+    };
+  };
+
+  return { compile, holds, normalize };
+};
+
+export type Match = ReturnType<typeof match>;

package/src/internal/reading/names.inpage.ts

@@ -0,0 +1,306 @@
+/**
+ * In the page: the foundation the other parts build on. It gives elements refs and reads the
+ * roles, names and states that the outline and the input checks report.
+ *
+ * Every `*.inpage.ts` part runs inside the page. The page receives it as source text, so it must
+ * stay self-contained: it uses only its parameters, the DOM and what it defines itself.
+ */
+
+export const names = () => {
+  const byElement = new WeakMap<Element, string>();
+  const byRef = new Map<string, WeakRef<Element>>();
+  const refs = { next: 1 };
+
+  const interactiveRoles = new Set(
+    "button link checkbox radio tab menuitem menuitemcheckbox menuitemradio option switch slider combobox listbox textbox searchbox spinbutton treeitem".split(
+      " ",
+    ),
+  );
+
+  const containers: Record<string, string> = {
+    HEADER: "banner",
+    NAV: "navigation",
+    MAIN: "main",
+    ASIDE: "complementary",
+    FOOTER: "contentinfo",
+    FORM: "form",
+    DIALOG: "dialog",
+  };
+
+  // Elements of a same-origin frame come from another realm, so tag names decide, not instanceof.
+  const isInput = (element: Element): element is HTMLInputElement => element.tagName === "INPUT";
+
+  const isTextArea = (element: Element): element is HTMLTextAreaElement =>
+    element.tagName === "TEXTAREA";
+
+  const isSelect = (element: Element): element is HTMLSelectElement => element.tagName === "SELECT";
+  const isFrame = (element: Element): element is HTMLIFrameElement => element.tagName === "IFRAME";
+  const isHtml = (element: Element): element is HTMLElement => "innerText" in element;
+
+  const isButton = (element: Element): element is HTMLButtonElement => element.tagName === "BUTTON";
+
+  const isLabel = (element: Element): element is HTMLLabelElement => element.tagName === "LABEL";
+
+  const textOf = (element: Element): string =>
+    isHtml(element) ? element.innerText : (element.textContent ?? "");
+
+  const isElement = (node: Node): node is Element => node.nodeType === Node.ELEMENT_NODE;
+  const isDocument = (node: Node): node is Document => node.nodeType === Node.DOCUMENT_NODE;
+
+  // Controls whose text is a value or a choice, not words of a label around them.
+  const valueRoles = new Set(
+    "combobox listbox option textbox searchbox spinbutton slider".split(" "),
+  );
+
+  /**
+   * A label's own words, without the options or values of the controls inside it, native or
+   * scripted, such as the custom select Browserbase puts in place of a native one.
+   */
+  const labelText = (label: Element): string => {
+    let text = "";
+
+    const collect = (node: Node): void => {
+      for (const child of Array.from(node.childNodes)) {
+        if (child.nodeType === Node.TEXT_NODE) text += child.textContent ?? "";
+        else if (
+          isElement(child) &&
+          !["SELECT", "TEXTAREA", "INPUT", "SCRIPT", "STYLE"].includes(child.tagName) &&
+          !valueRoles.has(roleOf(child) ?? "")
+        )
+          collect(child);
+      }
+    };
+
+    collect(label);
+
+    return text;
+  };
+
+  const clean = (value: string | null | undefined, max = 160): string => {
+    const text = (value ?? "").replace(/\s+/g, " ").trim();
+
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+  };
+
+  const roleOf = (element: Element): string | null => {
+    const explicit = element.getAttribute("role");
+
+    if (explicit !== null && explicit.trim() !== "") return explicit.trim().split(/\s+/)[0] ?? null;
+    const tag = element.tagName;
+
+    if (tag === "A") return element.hasAttribute("href") ? "link" : null;
+    if (tag === "BUTTON" || tag === "SUMMARY") return "button";
+    if (isSelect(element)) return element.multiple ? "listbox" : "combobox";
+    if (tag === "TEXTAREA") return "textbox";
+    if (isInput(element)) {
+      const type = element.type;
+
+      if (type === "hidden") return null;
+      if (type === "checkbox" || type === "radio") return type;
+      if (type === "range") return "slider";
+      if (type === "number") return "spinbutton";
+      if (type === "search") return "searchbox";
+      if (type === "button" || type === "submit" || type === "reset" || type === "image")
+        return "button";
+
+      return "textbox";
+    }
+    if (/^H[1-6]$/.test(tag)) return "heading";
+    if (tag === "IMG") return "img";
+    if (tag === "CANVAS") return "canvas";
+    if (tag === "IFRAME") return "iframe";
+    if (element.getAttribute("contenteditable") === "true") return "textbox";
+
+    return containers[tag] ?? null;
+  };
+
+  const nameOf = (element: Element, role: string | null): string => {
+    const label = element.getAttribute("aria-label");
+
+    if (label !== null && clean(label) !== "") return clean(label);
+    const labelledBy = element.getAttribute("aria-labelledby");
+
+    if (labelledBy !== null) {
+      const text = labelledBy
+        .split(/\s+/)
+        .map((id) => {
+          const labelling = element.ownerDocument.getElementById(id);
+
+          return labelling === null ? "" : labelText(labelling);
+        })
+        .join(" ");
+
+      if (clean(text) !== "") return clean(text);
+    }
+    if (isInput(element) || isTextArea(element) || isSelect(element)) {
+      const labels = element.labels === null ? "" : Array.from(element.labels, labelText).join(" ");
+
+      if (clean(labels) !== "") return clean(labels);
+      if (
+        isInput(element) &&
+        (element.type === "button" || element.type === "submit" || element.type === "reset")
+      )
+        return clean(element.value);
+
+      return clean(
+        element.getAttribute("placeholder") ??
+          element.getAttribute("title") ??
+          element.getAttribute("name"),
+      );
+    }
+    if (role === "img") return clean(element.getAttribute("alt") ?? element.getAttribute("title"));
+    if (role === "iframe")
+      return clean(element.getAttribute("title") ?? element.getAttribute("name"));
+    if (role === null || interactiveRoles.has(role) || role === "heading") {
+      // An editable secret field's text is what was typed into it.
+      const text = isSecret(element) ? "" : clean(textOf(element), 120);
+
+      if (text !== "") return text;
+      const titled = element.querySelector("[title],img[alt],svg title");
+
+      const fallback =
+        titled === null
+          ? null
+          : titled.tagName === "IMG"
+            ? titled.getAttribute("alt")
+            : titled.tagName.toLowerCase() === "title"
+              ? titled.textContent
+              : titled.getAttribute("title");
+
+      return clean(element.getAttribute("title") ?? fallback);
+    }
+
+    return "";
+  };
+
+  const isDisabled = (element: Element): boolean =>
+    ("disabled" in element && element.disabled === true) ||
+    element.getAttribute("aria-disabled") === "true";
+
+  const refFor = (element: Element): string => {
+    const known = byElement.get(element);
+
+    if (known !== undefined && byRef.get(known)?.deref() === element) return known;
+    const ref = `e${refs.next++}`;
+
+    byElement.set(element, ref);
+    byRef.set(ref, new WeakRef(element));
+
+    return ref;
+  };
+
+  // A ref names an element of the current documents only: nodes of a navigated frame can stay
+  // connected to their old document, and must not be measured or typed into.
+  const lookup = (ref: string): Element | undefined => {
+    const element = byRef.get(ref)?.deref();
+
+    return element !== undefined && element.isConnected && inCurrentDocument(element)
+      ? element
+      : undefined;
+  };
+
+  const describe = (element: Element): string => {
+    const id = element.id === "" ? "" : `#${element.id}`;
+    const name = clean(nameOf(element, roleOf(element)), 40);
+
+    return `<${element.tagName.toLowerCase()}${id}>${name === "" ? "" : ` "${name}"`}`;
+  };
+
+  const isRoot = (node: Node): node is Document | ShadowRoot =>
+    node.nodeType === Node.DOCUMENT_NODE || node.nodeType === Node.DOCUMENT_FRAGMENT_NODE;
+
+  const parentOf = (element: Element): Element | null => {
+    const root = element.getRootNode();
+
+    return element.parentElement ?? (isRoot(root) && "host" in root ? root.host : null);
+  };
+
+  const activeElement = (): Element | null => {
+    let active = document.activeElement;
+
+    while (active !== null) {
+      const inner =
+        active.shadowRoot?.activeElement ??
+        (isFrame(active) ? active.contentDocument?.activeElement : null);
+
+      if (inner === null || inner === undefined || inner === active) return active;
+      active = inner;
+    }
+
+    return null;
+  };
+
+  const inCurrentDocument = (element: Element): boolean => {
+    let owner = element.ownerDocument;
+
+    // Nodes in a navigated iframe can remain connected to their old Document. Approval
+    // requires the current frame chain as well as the ref's weakly held node identity.
+    while (owner !== document) {
+      const frame = owner.defaultView?.frameElement;
+
+      if (
+        frame === null ||
+        frame === undefined ||
+        !frame.isConnected ||
+        (isFrame(frame) && frame.contentDocument !== owner)
+      )
+        return false;
+      owner = frame.ownerDocument;
+    }
+
+    return true;
+  };
+
+  // Autocomplete tokens for a password, a one-time code, or a payment card's number, code or expiry.
+  const secretToken =
+    /(?:^|\s)(?:current-password|new-password|one-time-code|cc-number|cc-csc|cc-exp(?:-month|-year)?)(?=\s|$)/i;
+
+  // A field once secret stays secret, such as a password its page lets the user reveal.
+  const secrets = new WeakSet<Element>();
+
+  /**
+   * A field the DOM marks as secret, now or before: by its type, its autocomplete tokens, or a
+   * style that shows dots for what it holds, as a PIN field may.
+   */
+  const isSecret = (element: Element): boolean => {
+    if (
+      (isInput(element) && element.type === "password") ||
+      secretToken.test(element.getAttribute("autocomplete") ?? "") ||
+      ((isInput(element) || isTextArea(element)) &&
+        !/^(none)?$/.test(getComputedStyle(element).getPropertyValue("-webkit-text-security")))
+    )
+      secrets.add(element);
+
+    return secrets.has(element);
+  };
+
+  return {
+    activeElement,
+    clean,
+    containers,
+    describe,
+    inCurrentDocument,
+    interactiveRoles,
+    isButton,
+    isDisabled,
+    isDocument,
+    isElement,
+    isFrame,
+    isHtml,
+    isInput,
+    isLabel,
+    isRoot,
+    isSecret,
+    isSelect,
+    isTextArea,
+    lookup,
+    nameOf,
+    parentOf,
+    refFor,
+    refs,
+    roleOf,
+    textOf,
+  };
+};
+
+export type Names = ReturnType<typeof names>;