@nativedesktop/test 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nativedesktop/test",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/FormalSnake/NativeDesktop#readme",
@@ -22,7 +22,7 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@nativedesktop/host": "0.4.1",
-    "@nativedesktop/react": "0.4.1"
+    "@nativedesktop/host": "0.4.3",
+    "@nativedesktop/react": "0.4.3"
   }
 }

package/src/attach.ts

@@ -0,0 +1,157 @@
+// Attach to a host somebody else launched (ND_AUTOMATION_SOCKET), with the
+// same locator surface AppHandle carries.
+//
+// The acceptance gates start the host from bash and hand the socket path to a
+// drive script, so those scripts never own a process. This is the half of
+// AppHandle that does not need one: the tree, the host-side waits, the
+// locators, and the keyboard and mouse.
+import type {
+  GetTreeResult,
+  ScreenshotResult,
+  SetWindowFrameParams,
+  WaitCondition,
+  WaitForResult,
+  WindowInfo,
+  WindowsResult,
+} from "@nativedesktop/react/rpc";
+import { AutomationClient } from "./socket.ts";
+import { Locator, LocatorFactory, type LocatorClient, type RoleOptions, type TextOptions } from "./locator.ts";
+import type { Keyboard, Mouse } from "./keyboard.ts";
+import { renderWaitValue, type WaitOpts } from "./wait.ts";
+
+const DEFAULT_ACTION_TIMEOUT_MS = 5_000;
+
+export class AttachedApp implements LocatorClient {
+  /** Deadline every locator action, reader and expect matcher inherits. */
+  actionTimeout = DEFAULT_ACTION_TIMEOUT_MS;
+
+  private readonly factory: LocatorFactory;
+
+  private constructor(readonly rpc: AutomationClient) {
+    this.factory = new LocatorFactory(this);
+  }
+
+  /** Connects to `path`, defaulting to ND_AUTOMATION_SOCKET. */
+  static async connect(path = process.env.ND_AUTOMATION_SOCKET): Promise<AttachedApp> {
+    return new AttachedApp(await AutomationClient.connect(path));
+  }
+
+  tree(window?: number): Promise<GetTreeResult> {
+    return this.rpc.call("getTree", { window });
+  }
+
+  /** Untyped RPC entry point the Locator layer dispatches through, so one
+   * call site serves every action method. */
+  callRpc(method: string, params?: Record<string, unknown>): Promise<unknown> {
+    return this.rpc.call(method as "click", params as never);
+  }
+
+  windows(): Promise<WindowsResult> {
+    return this.rpc.call("windows");
+  }
+
+  /** The host's in-process render. Unlike AppHandle's, there is no
+   * ScreenCaptureKit rung here: this process does not know the host's pid. */
+  screenshot(path: string, opts: { window?: number } = {}): Promise<ScreenshotResult> {
+    return this.rpc.call("screenshot", { path, window: opts.window });
+  }
+
+  isAlive(): boolean {
+    return true;
+  }
+
+  /** Resizes a window in logical units, keeping its origin. The answer is
+   * that window's updated WindowInfo, whose `geometry` is the same w/h
+   * Geometry a node carries. */
+  setWindowSize(width: number, height: number, opts: { window?: number } = {}): Promise<WindowInfo> {
+    return this.rpc.call("setWindowFrame", { window: opts.window, width, height });
+  }
+
+  /** Moves and/or resizes a window; omitted components keep their current
+   * value. GTK ignores x/y (client-side placement is not a Wayland
+   * capability). */
+  setWindowFrame(frame: SetWindowFrameParams): Promise<WindowInfo> {
+    return this.rpc.call("setWindowFrame", frame);
+  }
+
+  // --- host-side waits -------------------------------------------------------
+
+  waitFor(condition: WaitCondition, opts: WaitOpts = {}): Promise<WaitForResult> {
+    return this.rpc.call("waitFor", { condition, timeoutMs: opts.timeoutMs, window: opts.window });
+  }
+
+  waitForText(text: string, opts?: WaitOpts): Promise<WaitForResult> {
+    return this.waitFor({ textContains: text }, opts);
+  }
+
+  waitForPresent(testId: string, opts?: WaitOpts): Promise<WaitForResult> {
+    return this.waitFor({ testId, state: "present" }, opts);
+  }
+
+  waitForGone(testId: string, opts?: WaitOpts): Promise<WaitForResult> {
+    return this.waitFor({ testId, state: "gone" }, opts);
+  }
+
+  waitForValue(testId: string, value: string | number | boolean, opts: WaitOpts = {}): Promise<WaitForResult> {
+    return this.waitFor({ testId, valueEquals: renderWaitValue(value) }, opts);
+  }
+
+  // --- locators --------------------------------------------------------------
+
+  get keyboard(): Keyboard {
+    return this.factory.keyboard;
+  }
+
+  get mouse(): Mouse {
+    return this.factory.mouse;
+  }
+
+  locator(selector: string): Locator {
+    return this.factory.locator(selector);
+  }
+
+  getByTestId(testId: string): Locator {
+    return this.factory.getByTestId(testId);
+  }
+
+  getByRole(role: string, opts?: RoleOptions): Locator {
+    return this.factory.getByRole(role, opts);
+  }
+
+  getByText(text: string | RegExp, opts?: TextOptions): Locator {
+    return this.factory.getByText(text, opts);
+  }
+
+  getByLabel(text: string | RegExp, opts?: TextOptions): Locator {
+    return this.factory.getByLabel(text, opts);
+  }
+
+  getByPlaceholder(text: string | RegExp, opts?: TextOptions): Locator {
+    return this.factory.getByPlaceholder(text, opts);
+  }
+
+  /** A locator factory bound to one window, by index in `windows()` order or
+   * by a substring of its title. */
+  async window(titleOrIndex: string | number): Promise<LocatorFactory> {
+    const { windows } = await this.windows();
+    const info =
+      typeof titleOrIndex === "number"
+        ? windows[titleOrIndex]
+        : windows.find((w) => (w.title ?? "").includes(titleOrIndex));
+    if (!info) {
+      const known = windows.map((w) => JSON.stringify(w.title ?? "")).join(", ") || "(none)";
+      throw new Error(`window(${JSON.stringify(titleOrIndex)}): no such window. Open windows: ${known}`);
+    }
+    return new LocatorFactory(this, info.ref);
+  }
+
+  close(): Promise<void> {
+    this.rpc.close();
+    return Promise.resolve();
+  }
+}
+
+/** Shorthand for AttachedApp.connect(). */
+export function connectApp(path?: string): Promise<AttachedApp> {
+  return AttachedApp.connect(path);
+}

package/src/errors.ts

@@ -0,0 +1,121 @@
+// Locator failures, rendered so the next step is obvious from the message
+// alone: what was waited for, how many nodes answered, and which nodes in the
+// window came closest.
+import { hasRealSize, nodeName, renderValue, type NdNode } from "./matcher.ts";
+
+export class LocatorError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "LocatorError";
+  }
+}
+
+/** More than one node matched a selector used for a single-target action.
+ * Never retried: a second element is a selector bug, not a timing one. */
+export class StrictModeError extends LocatorError {
+  constructor(
+    readonly selector: string,
+    readonly matches: NdNode[],
+    windowLabel: string,
+  ) {
+    super(
+      `strict mode violation: ${selector} resolved to ${matches.length} elements in window ${windowLabel}.\n` +
+        `${renderCandidates(matches, matches.length)}\n` +
+        `Narrow it with .first(), .nth(i), or .filter({ hasText: ... }).`,
+    );
+    this.name = "StrictModeError";
+  }
+}
+
+export class TimeoutError extends LocatorError {
+  constructor(
+    readonly call: string,
+    readonly timeoutMs: number,
+    readonly callLog: string[],
+    candidates: NdNode[],
+    windowLabel: string,
+    extra?: string,
+  ) {
+    const lines = [`${call}: Timeout ${timeoutMs}ms exceeded.`];
+    if (extra) lines.push(extra);
+    lines.push("Call log:");
+    for (const entry of callLog) lines.push(`  - ${entry}`);
+    if (candidates.length) {
+      lines.push(`Nearest candidates in window ${windowLabel} (${candidates.length}):`);
+      lines.push(renderCandidates(candidates, MAX_CANDIDATES));
+    }
+    super(lines.join("\n"));
+    this.name = "TimeoutError";
+  }
+}
+
+const MAX_CANDIDATES = 5;
+
+function quote(s: string): string {
+  return JSON.stringify(s.length > 40 ? `${s.slice(0, 39)}…` : s);
+}
+
+/** One candidate line: type, role, name, testID, state flags, rectangle. */
+export function describeNode(node: NdNode): string {
+  const bits = [node.type.padEnd(14), `role=${node.role ?? "-"}`.padEnd(18)];
+  const name = nodeName(node);
+  if (name) bits.push(`text=${quote(name)}`);
+  if (node.testID) bits.push(`testID=${node.testID}`);
+  const value = renderValue(node.value);
+  if (value && value !== name) bits.push(`value=${quote(value)}`);
+  bits.push([node.visible ? "visible" : "hidden", node.enabled ? "enabled" : "disabled"].join(" "));
+  const g = node.geometry;
+  bits.push(g ? `(${g.x},${g.y} ${g.w}x${g.h})` : "(no geometry)");
+  return `  ${bits.join("  ")}`;
+}
+
+export function renderCandidates(nodes: NdNode[], limit: number): string {
+  const shown = nodes.slice(0, limit).map(describeNode);
+  if (nodes.length > limit) shown.push(`  ... and ${nodes.length - limit} more`);
+  return shown.join("\n");
+}
+
+/** Levenshtein distance, capped at the longer string's length. Only used to
+ * order a handful of candidates, so the plain two-row implementation is
+ * cheaper than anything smarter. */
+export function distance(a: string, b: string): number {
+  if (a === b) return 0;
+  if (!a.length || !b.length) return Math.max(a.length, b.length);
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      row[j] = Math.min(row[j - 1]! + 1, prev[j]! + 1, prev[j - 1]! + cost);
+    }
+    prev = row;
+  }
+  return prev[b.length]!;
+}
+
+/**
+ * Orders every identifiable node in the tree by how close its testID or name
+ * is to what the selector asked for. Actionable nodes win ties, so the first
+ * suggestion is one a click would actually reach.
+ */
+export function rankCandidates(nodes: NdNode[], intended: string | undefined, limit = MAX_CANDIDATES): NdNode[] {
+  const identifiable = nodes.filter((n) => n.testID || nodeName(n) || n.role);
+  const want = (intended ?? "").toLowerCase();
+  const score = (node: NdNode): number => {
+    if (!want) return node.testID ? 0 : 1;
+    const keys = [node.testID ?? "", nodeName(node), node.role ?? "", node.type];
+    let best = Number.POSITIVE_INFINITY;
+    for (const key of keys) {
+      const lower = key.toLowerCase();
+      if (!lower) continue;
+      const d = lower.includes(want) || want.includes(lower) ? 0 : distance(lower, want);
+      if (d < best) best = d;
+    }
+    return best;
+  };
+  return identifiable
+    .map((node) => ({ node, score: score(node), actionable: node.visible && node.enabled && hasRealSize(node) }))
+    .sort((a, b) => a.score - b.score || Number(b.actionable) - Number(a.actionable))
+    .slice(0, limit)
+    .map((e) => e.node);
+}

package/src/expect.ts

@@ -0,0 +1,274 @@
+// Polling assertions over a Locator, plus a small non-polling `expect` for
+// plain values so a drive script needs only one assertion vocabulary.
+//
+// A locator matcher re-reads the tree every 100ms until it passes or the
+// deadline runs out, so nothing in a drive has to sleep before asserting.
+// `.not` inverts the predicate and keeps the polling: `.not.toBeVisible()`
+// waits for the widget to go away rather than failing on the first read.
+import { allNodes, matchText, nodeChecked, nodeName, nodePlaceholder, nodeText, renderValue, type NdNode } from "./matcher.ts";
+import { rankCandidates, StrictModeError, TimeoutError } from "./errors.ts";
+import { intendedName } from "./selectors.ts";
+import { Locator } from "./locator.ts";
+
+const POLL_MS = 100;
+
+export interface ExpectOptions {
+  timeout?: number;
+}
+
+interface Verdict {
+  pass: boolean;
+  actual: string;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function describe(expected: unknown): string {
+  if (expected instanceof RegExp) return String(expected);
+  return typeof expected === "string" ? JSON.stringify(expected) : String(expected);
+}
+
+function textMatches(expected: string | RegExp, actual: string, exact: boolean): boolean {
+  return matchText(expected instanceof RegExp ? { regex: expected } : { value: expected, exact }, actual);
+}
+
+export class LocatorAssertions {
+  constructor(
+    private readonly locator: Locator,
+    private readonly negated = false,
+  ) {}
+
+  get not(): LocatorAssertions {
+    return new LocatorAssertions(this.locator, !this.negated);
+  }
+
+  private async run(
+    name: string,
+    expected: string,
+    strict: boolean,
+    evaluate: (matches: NdNode[]) => Verdict,
+    opts: ExpectOptions,
+  ): Promise<void> {
+    const timeout = opts.timeout ?? this.locator.client.actionTimeout;
+    const deadline = Date.now() + timeout;
+    let root: NdNode | null = null;
+    let count = 0;
+    let actual = "";
+    for (;;) {
+      const snap = await this.locator.snapshot();
+      root = snap.root;
+      count = snap.matches.length;
+      if (strict && count > 1) {
+        throw new StrictModeError(this.locator.selector, snap.matches, root?.text ? JSON.stringify(root.text) : "?");
+      }
+      const verdict = evaluate(snap.matches);
+      actual = verdict.actual;
+      if (verdict.pass !== this.negated) return;
+      if (Date.now() >= deadline) break;
+      await sleep(POLL_MS);
+    }
+    const call = `expect(${this.locator.selector})${this.negated ? ".not" : ""}.${name}`;
+    const extra = `Expected: ${this.negated ? "not " : ""}${expected}\nReceived: ${actual}`;
+    const log = [`waiting for ${this.locator.selector}`, `resolved ${count} element${count === 1 ? "" : "s"}`];
+    const candidates = count === 0 && root ? rankCandidates(allNodes(root), intendedName(this.locator.parts)) : [];
+    throw new TimeoutError(call, timeout, log, candidates, root?.text ? JSON.stringify(root.text) : "?", extra);
+  }
+
+  toBeVisible(opts: ExpectOptions = {}): Promise<void> {
+    return this.run("toBeVisible", "visible", true, (m) => ({
+      pass: m.length > 0 && m[0]!.visible,
+      actual: m.length ? (m[0]!.visible ? "visible" : "hidden") : "not attached",
+    }), opts);
+  }
+
+  toBeHidden(opts: ExpectOptions = {}): Promise<void> {
+    return this.run("toBeHidden", "hidden", true, (m) => ({
+      pass: m.length === 0 || !m[0]!.visible,
+      actual: m.length ? (m[0]!.visible ? "visible" : "hidden") : "not attached",
+    }), opts);
+  }
+
+  toBeAttached(opts: ExpectOptions = {}): Promise<void> {
+    return this.run("toBeAttached", "attached", false, (m) => ({
+      pass: m.length > 0,
+      actual: `${m.length} element${m.length === 1 ? "" : "s"}`,
+    }), opts);
+  }
+
+  toBeEnabled(opts: ExpectOptions = {}): Promise<void> {
+    return this.run("toBeEnabled", "enabled", true, (m) => ({
+      pass: m.length > 0 && m[0]!.enabled,
+      actual: m.length ? (m[0]!.enabled ? "enabled" : "disabled") : "not attached",
+    }), opts);
+  }
+
+  toBeDisabled(opts: ExpectOptions = {}): Promise<void> {
+    return this.run("toBeDisabled", "disabled", true, (m) => ({
+      pass: m.length > 0 && !m[0]!.enabled,
+      actual: m.length ? (m[0]!.enabled ? "enabled" : "disabled") : "not attached",
+    }), opts);
+  }
+
+  toBeChecked(opts: ExpectOptions & { checked?: boolean } = {}): Promise<void> {
+    const want = opts.checked ?? true;
+    return this.run("toBeChecked", String(want), true, (m) => ({
+      pass: m.length > 0 && nodeChecked(m[0]!) === want,
+      actual: m.length ? String(nodeChecked(m[0]!)) : "not attached",
+    }), opts);
+  }
+
+  toBeFocused(opts: ExpectOptions = {}): Promise<void> {
+    return this.run("toBeFocused", "focused", true, (m) => ({
+      pass: m.length > 0 && m[0]!.focused,
+      actual: m.length ? (m[0]!.focused ? "focused" : "not focused") : "not attached",
+    }), opts);
+  }
+
+  toHaveText(expected: string | RegExp, opts: ExpectOptions = {}): Promise<void> {
+    return this.run("toHaveText", describe(expected), true, (m) => ({
+      pass: m.length > 0 && textMatches(expected, nodeText(m[0]!), true),
+      actual: m.length ? JSON.stringify(nodeText(m[0]!)) : "not attached",
+    }), opts);
+  }
+
+  toContainText(expected: string | RegExp, opts: ExpectOptions = {}): Promise<void> {
+    return this.run("toContainText", describe(expected), true, (m) => ({
+      pass: m.length > 0 && textMatches(expected, nodeText(m[0]!), false),
+      actual: m.length ? JSON.stringify(nodeText(m[0]!)) : "not attached",
+    }), opts);
+  }
+
+  toHaveValue(expected: string | number | boolean | RegExp, opts: ExpectOptions = {}): Promise<void> {
+    const want = expected instanceof RegExp ? expected : renderValue(expected);
+    return this.run("toHaveValue", describe(want), true, (m) => ({
+      pass: m.length > 0 && textMatches(want, renderValue(m[0]!.value), true),
+      actual: m.length ? JSON.stringify(renderValue(m[0]!.value)) : "not attached",
+    }), opts);
+  }
+
+  toHaveCount(expected: number, opts: ExpectOptions = {}): Promise<void> {
+    return this.run("toHaveCount", String(expected), false, (m) => ({
+      pass: m.length === expected,
+      actual: String(m.length),
+    }), opts);
+  }
+
+  toHaveAttribute(name: string, expected?: string | RegExp, opts: ExpectOptions = {}): Promise<void> {
+    const read = (node: NdNode): string | null => {
+      switch (name) {
+        case "testId":
+        case "testID":
+          return node.testID;
+        case "role":
+          return node.role;
+        case "type":
+          return node.type;
+        case "text":
+          return node.text;
+        case "label":
+          return nodeName(node) || null;
+        case "placeholder":
+          return nodePlaceholder(node) || null;
+        case "value":
+          return node.value === null || node.value === undefined ? null : renderValue(node.value);
+        default:
+          return null;
+      }
+    };
+    return this.run("toHaveAttribute", expected === undefined ? `${name} present` : `${name}=${describe(expected)}`, true, (m) => {
+      const got = m.length ? read(m[0]!) : null;
+      const pass = expected === undefined ? got !== null : got !== null && textMatches(expected, got, true);
+      return { pass, actual: got === null ? "null" : JSON.stringify(got) };
+    }, opts);
+  }
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const ka = Object.keys(a as object);
+  const kb = Object.keys(b as object);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k) => deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]));
+}
+
+export class ValueAssertions {
+  constructor(
+    private readonly actual: unknown,
+    private readonly negated = false,
+  ) {}
+
+  get not(): ValueAssertions {
+    return new ValueAssertions(this.actual, !this.negated);
+  }
+
+  private assert(name: string, pass: boolean, expected: string): void {
+    if (pass !== this.negated) return;
+    throw new Error(
+      `expect(${describe(this.actual)})${this.negated ? ".not" : ""}.${name}\n` +
+        `Expected: ${this.negated ? "not " : ""}${expected}\nReceived: ${describe(this.actual)}`,
+    );
+  }
+
+  toBe(expected: unknown): void {
+    this.assert("toBe", Object.is(this.actual, expected), describe(expected));
+  }
+
+  toEqual(expected: unknown): void {
+    this.assert("toEqual", deepEqual(this.actual, expected), describe(expected));
+  }
+
+  toBeTruthy(): void {
+    this.assert("toBeTruthy", Boolean(this.actual), "truthy");
+  }
+
+  toBeFalsy(): void {
+    this.assert("toBeFalsy", !this.actual, "falsy");
+  }
+
+  toBeNull(): void {
+    this.assert("toBeNull", this.actual === null, "null");
+  }
+
+  toBeUndefined(): void {
+    this.assert("toBeUndefined", this.actual === undefined, "undefined");
+  }
+
+  toContain(expected: unknown): void {
+    const pass = Array.isArray(this.actual)
+      ? this.actual.includes(expected)
+      : typeof this.actual === "string" && typeof expected === "string" && this.actual.includes(expected);
+    this.assert("toContain", pass, describe(expected));
+  }
+
+  toMatch(expected: RegExp | string): void {
+    const actual = String(this.actual);
+    const pass = expected instanceof RegExp ? expected.test(actual) : actual.includes(expected);
+    this.assert("toMatch", pass, describe(expected));
+  }
+
+  toBeGreaterThan(expected: number): void {
+    this.assert("toBeGreaterThan", Number(this.actual) > expected, `> ${expected}`);
+  }
+
+  toBeGreaterThanOrEqual(expected: number): void {
+    this.assert("toBeGreaterThanOrEqual", Number(this.actual) >= expected, `>= ${expected}`);
+  }
+
+  toBeLessThan(expected: number): void {
+    this.assert("toBeLessThan", Number(this.actual) < expected, `< ${expected}`);
+  }
+
+  toBeLessThanOrEqual(expected: number): void {
+    this.assert("toBeLessThanOrEqual", Number(this.actual) <= expected, `<= ${expected}`);
+  }
+}
+
+export function expect(actual: Locator): LocatorAssertions;
+export function expect(actual: unknown): ValueAssertions;
+export function expect(actual: unknown): LocatorAssertions | ValueAssertions {
+  return actual instanceof Locator ? new LocatorAssertions(actual) : new ValueAssertions(actual);
+}