@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/src/locator/element-state.test.ts

@@ -1,181 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import {
-  allPass,
-  evaluateChecks,
-  parseElementState,
-  PROBE_ELEMENT,
-  type CheckName,
-  type ElementState,
-} from "./element-state.js";
-
-const READY: ElementState = {
-  attached: true,
-  visible: true,
-  enabled: true,
-  editable: true,
-  box: { x: 10, y: 20, width: 100, height: 40 },
-  hitTarget: "self",
-};
-const ALL: CheckName[] = ["attached", "visible", "stable", "enabled", "editable", "hit target"];
-
-test("the probe is a function declaration that compiles", () => {
-  assert.doesNotThrow(() => new Function(`return (${PROBE_ELEMENT})`), PROBE_ELEMENT);
-});
-
-test("the probe takes the located element and the options", () => {
-  assert.match(PROBE_ELEMENT, /^\(el, options\) =>/);
-  assert.ok(!PROBE_ELEMENT.includes("document.evaluate"), "the element is found by the browser's locate command");
-});
-
-test("scrolling and hit testing are switched by the options argument", () => {
-  assert.match(PROBE_ELEMENT, /if \(options\.scroll\)/);
-  assert.match(PROBE_ELEMENT, /if \(options\.hitTest\)/);
-});
-
-test("parseElementState accepts a complete state", () => {
-  assert.deepEqual(parseElementState({ ...READY }), READY);
-});
-
-test("parseElementState rejects a non-object result", () => {
-  assert.throws(
-    () => parseElementState(null),
-    /Expected an element state object but received "null"/,
-  );
-  assert.throws(
-    () => parseElementState("string"),
-    /Expected an element state object but received "string"/,
-  );
-});
-
-test("parseElementState rejects malformed state", () => {
-  assert.throws(() => parseElementState({ attached: true }), /Malformed element state/);
-  assert.throws(
-    () => parseElementState({ ...READY, visible: "yes" }),
-    /Malformed element state/,
-  );
-  const { box: _box, ...withoutBox } = READY;
-  assert.throws(() => parseElementState(withoutBox), /Malformed element state/);
-});
-
-test("evaluateChecks passes an actionable element whose box did not move", () => {
-  const results = evaluateChecks(ALL, READY, READY);
-  assert.deepEqual(results, {
-    attached: "pass",
-    visible: "pass",
-    stable: "pass",
-    enabled: "pass",
-    editable: "pass",
-    "hit target": "pass",
-  });
-  assert.equal(allPass(results), true);
-});
-
-test("the first failing check marks later checks pending", () => {
-  const results = evaluateChecks(ALL, { ...READY, visible: false }, READY);
-  assert.deepEqual(results, {
-    attached: "pass",
-    visible: "fail",
-    stable: "pending",
-    enabled: "pending",
-    editable: "pending",
-    "hit target": "pending",
-  });
-  assert.equal(allPass(results), false);
-});
-
-test("stable needs a previous probe with the same box", () => {
-  const stable = (previous: ElementState | undefined) =>
-    evaluateChecks(["stable"], READY, previous).stable;
-  assert.equal(stable(undefined), "fail");
-  assert.equal(stable({ ...READY, box: { ...READY.box!, x: 11 } }), "fail");
-  assert.equal(stable({ ...READY, box: null }), "fail");
-  assert.equal(stable(READY), "pass");
-});
-
-test("hit target passes only when the element itself is hit", () => {
-  const hit = (hitTarget: string | null) =>
-    evaluateChecks(["hit target"], { ...READY, hitTarget }, READY)["hit target"];
-  assert.equal(hit("self"), "pass");
-  assert.equal(hit("div#overlay"), "fail");
-  assert.equal(hit(null), "fail");
-});
-
-test("only the required checks are evaluated, in the given order", () => {
-  assert.deepEqual(Object.keys(evaluateChecks(["attached", "enabled"], READY, undefined)), [
-    "attached",
-    "enabled",
-  ]);
-});
-
-/** Runs the probe against fake DOM objects, the way the page would call it */
-function runProbe(element: object | null, options = { scroll: true, hitTest: true }) {
-  const fakeDocument = {
-    elementFromPoint: () => element,
-  };
-  const fakeWindow = { innerWidth: 1000, innerHeight: 800 };
-  const fakeComputedStyle = () => ({ display: "block", visibility: "visible", opacity: "1" });
-  const probe = new Function(
-    "document",
-    "XPathResult",
-    "getComputedStyle",
-    "window",
-    `return (${PROBE_ELEMENT})`,
-  )(fakeDocument, { FIRST_ORDERED_NODE_TYPE: 9 }, fakeComputedStyle, fakeWindow) as (
-    el: object | null,
-    options: { scroll: boolean; hitTest: boolean },
-  ) => unknown;
-  return parseElementState(probe(element, options));
-}
-
-test("editable is a boolean even for non-HTML elements without isContentEditable", () => {
-  const svg = {
-    isConnected: true,
-    tagName: "svg",
-    id: "",
-    classList: [],
-    matches: () => false,
-    getAttribute: () => null,
-    contains: () => false,
-    getBoundingClientRect: () => ({ left: 0, top: 0, right: 10, bottom: 10, width: 10, height: 10 }),
-  };
-  const state = runProbe(svg);
-  assert.equal(state.attached, true);
-  assert.equal(state.editable, false);
-  assert.equal(typeof state.editable, "boolean");
-  assert.equal(state.hitTarget, "self");
-});
-
-test("the probe reports a missing element as not attached", () => {
-  const state = runProbe(null);
-  assert.equal(state.attached, false);
-  assert.equal(state.box, null);
-  assert.equal(state.hitTarget, null);
-});
-
-test("a node that was removed from the document is not attached, though the browser still resolves it", () => {
-  const removed = {
-    isConnected: false,
-    getBoundingClientRect: () => {
-      throw new Error("must not be measured");
-    },
-  };
-  const state = runProbe(removed);
-  assert.equal(state.attached, false);
-  assert.equal(state.box, null);
-});
-
-test("the probe skips the hit test unless asked", () => {
-  const el = {
-    isConnected: true,
-    tagName: "button",
-    id: "",
-    classList: [],
-    matches: () => false,
-    getAttribute: () => null,
-    contains: () => false,
-    getBoundingClientRect: () => ({ left: 0, top: 0, right: 10, bottom: 10, width: 10, height: 10 }),
-  };
-  assert.equal(runProbe(el, { scroll: false, hitTest: false }).hitTarget, null);
-  assert.equal(runProbe(el, { scroll: false, hitTest: true }).hitTarget, "self");
-});

package/src/locator/element-state.ts

@@ -1,159 +0,0 @@
-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>>;
-
-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: ElementState = {
-  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: unknown): ElementState {
-  if (typeof value !== "object" || value === null) {
-    throw new Error(`Expected an element state object but received "${describeType(value)}"`);
-  }
-  const state = value as Partial<ElementState>;
-  const flags = ["attached", "visible", "enabled", "editable"] as const;
-  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 as ElementState;
-}
-
-function describeType(value: unknown): string {
-  return value === null ? "null" : typeof value;
-}
-
-function sameBox(a: ElementBox | null, b: ElementBox | null) {
-  return (
-    a !== null &&
-    b !== null &&
-    a.x === b.x &&
-    a.y === b.y &&
-    a.width === b.width &&
-    a.height === b.height
-  );
-}
-
-function checkPasses(name: CheckName, current: ElementState, previous: ElementState | undefined) {
-  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: readonly CheckName[],
-  current: ElementState,
-  previous: ElementState | undefined,
-): CheckResults {
-  const results: CheckResults = {};
-  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: CheckResults): boolean {
-  return Object.values(results).every((result) => result === "pass");
-}

package/src/locator/locate-nodes.browser-test.ts

@@ -1,169 +0,0 @@
-import assert from "node:assert/strict";
-import { after, before, test } from "node:test";
-import { Browser } from "../browser/browser.js";
-import type Page from "../browser/page.js";
-import { setContent } from "../testing/browser-fixture.js";
-import { InvalidSelectorError } from "./locator.js";
-
-let browser: Browser;
-let page: Page;
-
-before(async () => {
-  ({ browser, page } = await Browser.launch("firefox", { port: 9235, headless: true }));
-  await page.navigateTo("about:blank", "complete");
-});
-
-after(async () => {
-  await page.dispose();
-  await browser?.close();
-});
-
-const OPTIONS = { timeout: 20000 };
-
-const FORMS = `
-  <form id="login"><h2>Login</h2>
-    <input type="text" name="user" placeholder="user">
-    <button type="submit">Sign in</button>
-  </form>
-  <form id="signup"><h2>Sign up</h2>
-    <input type="text" name="user" placeholder="new user">
-    <button type="submit">Create account</button>
-  </form>`;
-
-test("css locators find elements and count them", OPTIONS, async () => {
-  await setContent(page, FORMS);
-  assert.equal(await page.getByCss("form input[name=user]").count(), 2);
-  assert.equal(await page.getByCss("#signup button").textContent(), "Create account");
-});
-
-test("xpath locators behave as before", OPTIONS, async () => {
-  await setContent(page, FORMS);
-  assert.equal(await page.locator("button[text()='Sign in']").count(), 1);
-  assert.equal(await page.locator("//form[@id='login']//input").getAttribute("placeholder"), "user");
-});
-
-test("text locators match fully by default, partially and case-insensitively on request", OPTIONS, async () => {
-  await setContent(page, FORMS);
-  assert.equal(await page.getByText("Sign in").count(), 1);
-  assert.equal(await page.getByText("Sign").count(), 0, "full match by default");
-  assert.equal(await page.getByText("Sign", { match: "partial" }).count(), 2, "Sign in + Sign up");
-  assert.equal(await page.getByText("sign in").count(), 0);
-  assert.equal(await page.getByText("sign in", { ignoreCase: true }).count(), 1);
-});
-
-test("a chained locator is scoped to its parent", OPTIONS, async () => {
-  await setContent(page, FORMS);
-  const signup = page.locator("//form[@id='signup']");
-  assert.equal(await signup.getByCss("input").getAttribute("placeholder"), "new user");
-  assert.equal(await signup.locator("input").getAttribute("placeholder"), "new user");
-  assert.equal(await signup.locator("//input").getAttribute("placeholder"), "new user", "// is relative to the parent");
-  assert.equal(await signup.getByText("Sign in").count(), 0, "the login button is outside the signup form");
-  assert.equal(await page.getByCss("form").getByCss("button").count(), 2, "several parents");
-});
-
-test("actions work through chained locators", OPTIONS, async () => {
-  await setContent(
-    page,
-    FORMS,
-    `document.querySelectorAll("button").forEach((b) =>
-       b.addEventListener("click", (e) => { e.preventDefault(); b.dataset.clicked = "yes"; }));`,
-  );
-  await page.locator("//form[@id='signup']").getByCss("button").click({ timeout: 5000 });
-  assert.equal(await page.getByCss("#signup button").getAttribute("data-clicked"), "yes");
-  assert.equal(await page.getByCss("#login button").getAttribute("data-clicked"), null);
-  await page.locator("//form[@id='login']").getByCss("input").fill("sam", { timeout: 5000 });
-  assert.equal(await page.getByCss("#login input").inputValue(), "sam");
-});
-
-test("all() on a css locator gives locators for each element", OPTIONS, async () => {
-  await setContent(page, `<ul><li>a</li><li>b</li><li>c</li></ul>`);
-  const items = await page.getByCss("li").all();
-  assert.equal(items.length, 3);
-  assert.deepEqual(
-    await Promise.all(items.map((item) => item.textContent())),
-    ["a", "b", "c"],
-  );
-});
-
-test("the element is re-resolved every poll: a replaced element is found and clicked", OPTIONS, async () => {
-  await setContent(
-    page,
-    `<button id="b" disabled>old</button>`,
-    `setTimeout(() => {
-       document.body.innerHTML = '<button id="b">new</button>';
-       document.getElementById("b").addEventListener("click", (e) => { e.target.dataset.clicked = "yes"; });
-     }, 300);`,
-  );
-  const button = page.getByCss("#b");
-  await button.click({ timeout: 5000 });
-  assert.equal(await button.textContent(), "new");
-  assert.equal(await button.getAttribute("data-clicked"), "yes");
-});
-
-test("a removed element is not attached even though the browser can still resolve it", OPTIONS, async () => {
-  await setContent(page, `<p id="p">x</p>`);
-  const paragraph = page.getByCss("#p");
-  await paragraph.waitFor({ state: "visible", timeout: 2000 });
-  await setContent(page, ``);
-  await paragraph.waitFor({ state: "detached", timeout: 2000 });
-  assert.equal(await paragraph.isVisible(), false);
-});
-
-test("the first match is re-evaluated: a new earlier element becomes the target", OPTIONS, async () => {
-  await setContent(
-    page,
-    `<p class="x">second</p>`,
-    `setTimeout(() => document.body.insertAdjacentHTML("afterbegin", '<p class="x">first</p>'), 300);`,
-  );
-  const first = page.getByCss("p.x");
-  assert.equal(await first.textContent(), "second");
-  await new Promise((resolve) => setTimeout(resolve, 500));
-  assert.equal(await first.textContent(), "first");
-});
-
-test("an invalid css selector fails at once with the selector in the message", OPTIONS, async () => {
-  await setContent(page, FORMS);
-  const started = Date.now();
-  await assert.rejects(page.getByCss("form[").click({ timeout: 5000 }), (err) => {
-    assert.ok(err instanceof InvalidSelectorError, String(err));
-    assert.equal(err.selector, "css=form[");
-    return true;
-  });
-  assert.ok(Date.now() - started < 3000, "not retried until the timeout");
-});
-
-test("role locators use the browser's accessibility tree", OPTIONS, async () => {
-  await setContent(
-    page,
-    FORMS + `<a href="/x">Docs</a><div role="button" aria-label="Custom">x</div>`,
-  );
-  assert.equal(await page.getByRole("button", { name: "Sign in" }).count(), 1);
-  assert.equal(await page.getByRole("button").count(), 3, "two submit buttons and the role=button div");
-  assert.equal(await page.getByRole("link", { name: "Docs" }).getAttribute("href"), "/x");
-  assert.equal(await page.getByRole("button", { name: "Custom" }).count(), 1, "aria-label is the name");
-  assert.equal(
-    await page.locator("//form[@id='signup']").getByRole("button").textContent(),
-    "Create account",
-  );
-  assert.equal(await page.getByRole("textbox").count(), 2);
-});
-
-test("text search finds the innermost element, also without the browser's innerText locator", OPTIONS, async () => {
-  await setContent(page, `<div id="wrap"><span id="inner">  Save   draft </span></div><p>Save</p>`);
-  const found = page.getByText("Save draft");
-  assert.equal(await found.count(), 1);
-  assert.equal(await found.getAttribute("id"), "inner", "not the wrapping div");
-  assert.equal(await page.getByText("Save").count(), 1, "full match: only the paragraph");
-  assert.equal(await page.getByText("save", { match: "partial", ignoreCase: true }).count(), 2);
-});
-
-test("text locators are re-evaluated on every poll", OPTIONS, async () => {
-  await setContent(
-    page,
-    `<p>Loading</p>`,
-    `setTimeout(() => { document.body.innerHTML = '<button id="b">Done</button>'; }, 300);`,
-  );
-  const done = page.getByText("Done");
-  await done.waitFor({ state: "visible", timeout: 5000 });
-  assert.equal(await done.getAttribute("id"), "b");
-});