@nativedesktop/test 0.4.1 → 0.4.3

package/src/matcher.ts

@@ -0,0 +1,179 @@
+// SelectorPart -> predicate over a getTree node, plus the node-field readers
+// every layer above (locator, expect, snapshot) shares.
+//
+// checked, selected, expanded, label, placeholder and options are null on
+// every node the field does not apply to, and null on a host that predates
+// them, so each reader falls back to what the older wire already carried (a
+// boolean `value` is the checked state, `text` is the accessible name) and a
+// selector behaves the same against either host.
+import type { JsonNode } from "@nativedesktop/react/rpc";
+import type { SelectorPart, TextSpec } from "./selectors.ts";
+
+/** getTree's node, narrowed so `children` recurses as NdNode. */
+export type NdNode = Omit<JsonNode, "children"> & {
+  children: NdNode[];
+};
+
+export function asNdNode(node: JsonNode): NdNode {
+  return node as NdNode;
+}
+
+export function nodeText(node: NdNode): string {
+  return node.text ?? "";
+}
+
+/** The concatenated text of a node and everything under it, which is what
+ * `filter({hasText})` matches against. */
+export function subtreeText(node: NdNode): string {
+  let out = nodeText(node);
+  for (const child of node.children) {
+    const inner = subtreeText(child);
+    if (inner) out = out ? `${out} ${inner}` : inner;
+  }
+  return out;
+}
+
+/** Accessible name: the label the host sends, else the node's own text, else
+ * a string value (Badge and Kbd carry their content there). */
+export function nodeName(node: NdNode): string {
+  if (typeof node.label === "string" && node.label) return node.label;
+  if (node.text) return node.text;
+  return typeof node.value === "string" ? node.value : "";
+}
+
+export function nodePlaceholder(node: NdNode): string {
+  return typeof node.placeholder === "string" ? node.placeholder : "";
+}
+
+export function nodeChecked(node: NdNode): boolean | undefined {
+  if (typeof node.checked === "boolean") return node.checked;
+  if (typeof node.value === "boolean") return node.value;
+  return undefined;
+}
+
+/** The string rendering the host uses for waitFor's valueEquals, so one
+ * comparison fits a TextInput, a Slider and a Checkbox alike. */
+export function renderValue(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  return typeof value === "string" ? value : String(value);
+}
+
+export function hasRealSize(node: NdNode): boolean {
+  const g = node.geometry;
+  return g != null && g.w > 0 && g.h > 0;
+}
+
+function normalize(s: string): string {
+  return s.replace(/\s+/g, " ").trim();
+}
+
+export function matchText(spec: TextSpec, actual: string): boolean {
+  if (spec.regex) return spec.regex.test(actual);
+  const want = spec.value ?? "";
+  if (spec.exact) return normalize(actual) === normalize(want);
+  return normalize(actual).toLowerCase().includes(normalize(want).toLowerCase());
+}
+
+/** True when `part` holds for `node` itself. Structural parts (nth, has,
+ * has-not, and) are handled by the selection engine, not here. */
+export function matchPart(node: NdNode, part: SelectorPart): boolean {
+  switch (part.kind) {
+    case "testid":
+      return node.testID === part.value;
+    case "type":
+      return node.type === part.value;
+    case "text":
+      return matchText(part, nodeText(node));
+    case "label":
+      return matchText(part, nodeName(node));
+    case "placeholder":
+      return matchText(part, nodePlaceholder(node) || renderValue(node.value));
+    case "has-text":
+      return matchText(part, subtreeText(node));
+    case "role": {
+      if ((node.role ?? "") !== part.role) return false;
+      if (part.name && !matchText(part.name, nodeName(node))) return false;
+      if (part.checked !== undefined && nodeChecked(node) !== part.checked) return false;
+      if (part.disabled !== undefined && node.enabled !== !part.disabled) return false;
+      return true;
+    }
+    default:
+      return true;
+  }
+}
+
+function descendants(node: NdNode, out: NdNode[]): NdNode[] {
+  for (const child of node.children) {
+    out.push(child);
+    descendants(child, out);
+  }
+  return out;
+}
+
+function selfAndDescendants(node: NdNode): NdNode[] {
+  return descendants(node, [node]);
+}
+
+type PositionalPart = Extract<SelectorPart, { kind: "nth" | "has" | "has-not" | "and" }>;
+
+function isPositional(part: SelectorPart): part is PositionalPart {
+  return part.kind === "nth" || part.kind === "has" || part.kind === "has-not" || part.kind === "and";
+}
+
+function pickNth(nodes: NdNode[], index: number): NdNode[] {
+  const at = index < 0 ? nodes.length + index : index;
+  const node = nodes[at];
+  return node ? [node] : [];
+}
+
+/** Whether one node satisfies every positional-free part (used by has/and). */
+function matchesAll(node: NdNode, parts: SelectorPart[]): boolean {
+  return parts.every((p) => (isPositional(p) ? true : matchPart(node, p)));
+}
+
+/**
+ * Resolves a parsed selector against a tree.
+ *
+ * An engine part descends: the first searches the root and everything under
+ * it, each later one searches strictly inside the previous part's matches.
+ * nth/has/has-not/and/has-text refine the current set without descending.
+ */
+export function selectNodes(root: NdNode, parts: SelectorPart[]): NdNode[] {
+  let current: NdNode[] = [root];
+  let descended = false;
+  for (const part of parts) {
+    if (part.kind === "has-text") {
+      current = current.filter((n) => matchPart(n, part));
+      continue;
+    }
+    if (isPositional(part)) {
+      if (part.kind === "nth") {
+        current = pickNth(current, part.index);
+      } else if (part.kind === "and") {
+        current = current.filter((n) => matchesAll(n, part.parts));
+      } else {
+        const wantInner = part.kind === "has";
+        current = current.filter((n) => descendants(n, []).some((d) => matchesAll(d, part.parts)) === wantInner);
+      }
+      continue;
+    }
+    const pool: NdNode[] = [];
+    const seen = new Set<NdNode>();
+    for (const scope of current) {
+      for (const node of descended ? descendants(scope, []) : selfAndDescendants(scope)) {
+        if (seen.has(node)) continue;
+        seen.add(node);
+        pool.push(node);
+      }
+    }
+    current = pool.filter((n) => matchPart(n, part));
+    descended = true;
+  }
+  return descended ? current : [];
+}
+
+/** Every node in the tree, in document order: the candidate pool an error
+ * message ranks. */
+export function allNodes(root: NdNode): NdNode[] {
+  return selfAndDescendants(root);
+}

package/src/selectors.test.ts

@@ -0,0 +1,93 @@
+import { expect, test } from "bun:test";
+import { formatSelector, intendedName, parseSelector } from "./selectors.ts";
+
+test("parses every engine", () => {
+  expect(parseSelector("testid=save-btn")).toEqual([{ kind: "testid", value: "save-btn" }]);
+  expect(parseSelector("type=Button")).toEqual([{ kind: "type", value: "Button" }]);
+  expect(parseSelector("text=Save")).toEqual([{ kind: "text", value: "Save" }]);
+  expect(parseSelector('text="Save As"')).toEqual([{ kind: "text", value: "Save As", exact: true }]);
+  expect(parseSelector("text=/sa.e/i")).toEqual([{ kind: "text", regex: /sa.e/i }]);
+  expect(parseSelector("label=Volume")).toEqual([{ kind: "label", value: "Volume" }]);
+  expect(parseSelector("placeholder=Search")).toEqual([{ kind: "placeholder", value: "Search" }]);
+});
+
+test("parses a role with attributes", () => {
+  expect(parseSelector('role=button[name="Save"][exact]')).toEqual([
+    { kind: "role", role: "button", name: { value: "Save", exact: true } },
+  ]);
+  expect(parseSelector("role=checkbox[checked][disabled]")).toEqual([
+    { kind: "role", role: "checkbox", checked: true, disabled: true },
+  ]);
+  expect(parseSelector("role=checkbox[checked=false]")).toEqual([
+    { kind: "role", role: "checkbox", checked: false },
+  ]);
+  expect(parseSelector("role=button[name=/save/i]")).toEqual([
+    { kind: "role", role: "button", name: { regex: /save/i } },
+  ]);
+});
+
+test("chains parts on >> and reads the positional shorthands", () => {
+  expect(parseSelector('role=button[name="Save"] >> nth=1')).toEqual([
+    { kind: "role", role: "button", name: { value: "Save", exact: true } },
+    { kind: "nth", index: 1 },
+  ]);
+  expect(parseSelector("testid=list >> first")).toEqual([
+    { kind: "testid", value: "list" },
+    { kind: "nth", index: 0 },
+  ]);
+  expect(parseSelector("testid=list >> last")).toEqual([
+    { kind: "testid", value: "list" },
+    { kind: "nth", index: -1 },
+  ]);
+  expect(parseSelector("nth=-1")).toEqual([{ kind: "nth", index: -1 }]);
+});
+
+test("a >> inside a quoted value or a regex is not a separator", () => {
+  expect(parseSelector('text=">> keep"')).toEqual([{ kind: "text", value: ">> keep", exact: true }]);
+  expect(parseSelector("text=/a>>b/")).toEqual([{ kind: "text", regex: /a>>b/ }]);
+});
+
+test("parses nested filter parts", () => {
+  expect(parseSelector("type=Row >> has=(role=button)")).toEqual([
+    { kind: "type", value: "Row" },
+    { kind: "has", parts: [{ kind: "role", role: "button" }] },
+  ]);
+  expect(parseSelector("type=Row >> has-not=(testid=x) >> has-text=Ada")).toEqual([
+    { kind: "type", value: "Row" },
+    { kind: "has-not", parts: [{ kind: "testid", value: "x" }] },
+    { kind: "has-text", value: "Ada" },
+  ]);
+});
+
+test("format round-trips through parse", () => {
+  const cases = [
+    "testid=save-btn",
+    'role=button[name="Save"]',
+    "role=button[name=Save]",
+    "role=checkbox[checked][disabled]",
+    "text=/sa.e/i",
+    "type=Table >> has-text=Ada >> nth=-1",
+    "type=Row >> has=(role=button >> nth=0)",
+    "label=Volume >> and=(type=Label)",
+  ];
+  for (const selector of cases) {
+    const parsed = parseSelector(selector);
+    expect(formatSelector(parsed)).toBe(selector);
+    expect(parseSelector(formatSelector(parsed))).toEqual(parsed);
+  }
+});
+
+test("rejects a malformed selector", () => {
+  expect(() => parseSelector("button")).toThrow(/no engine/);
+  expect(() => parseSelector("nope=1")).toThrow(/unknown engine/);
+  expect(() => parseSelector("role=button[bogus]")).toThrow(/unknown role attribute/);
+  expect(() => parseSelector("nth=x")).toThrow(/not an integer/);
+});
+
+test("intendedName picks the last naming part", () => {
+  expect(intendedName(parseSelector("testid=save-btn >> nth=1"))).toBe("save-btn");
+  expect(intendedName(parseSelector('role=button[name="Save"]'))).toBe("Save");
+  expect(intendedName(parseSelector("role=button"))).toBe("button");
+  expect(intendedName(parseSelector("testid=a >> text=Ada"))).toBe("Ada");
+  expect(intendedName([])).toBeUndefined();
+});

package/src/selectors.ts

@@ -0,0 +1,229 @@
+// Playwright-shaped selector strings, parsed into the SelectorPart list the
+// matcher and Locator work on. A selector is one or more parts joined by
+// ">>"; each engine part descends into the previous part's subtree, while the
+// positional and filter parts refine the current match set in place.
+//
+//   testid=save-btn
+//   role=button[name="Save"][exact] >> nth=1
+//   type=Table >> has-text=Ada >> first
+//
+// Every part is representable as a string, so a Locator built through the
+// getBy*/filter helpers can print itself back as a selector in an error.
+
+export interface TextSpec {
+  /** Substring or exact literal; absent when `regex` is set. */
+  value?: string;
+  regex?: RegExp;
+  /** Equality after whitespace normalisation, rather than a case-insensitive substring. */
+  exact?: boolean;
+}
+
+export type SelectorPart =
+  | { kind: "testid"; value: string }
+  | ({ kind: "role"; role: string; checked?: boolean; disabled?: boolean } & { name?: TextSpec })
+  | ({ kind: "text" | "label" | "placeholder" } & TextSpec)
+  | { kind: "type"; value: string }
+  | { kind: "nth"; index: number }
+  | ({ kind: "has-text" } & TextSpec)
+  | { kind: "has" | "has-not" | "and"; parts: SelectorPart[] };
+
+const TEXT_ENGINES = new Set(["text", "label", "placeholder"]);
+
+/** Splits on top-level ">>", ignoring separators inside quotes, brackets,
+ * parens and regex literals. */
+function splitParts(selector: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let quote: string | null = null;
+  let inRegex = false;
+  let start = 0;
+  for (let i = 0; i < selector.length; i++) {
+    const c = selector[i]!;
+    if (quote) {
+      if (c === "\\") i++;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (inRegex) {
+      if (c === "\\") i++;
+      else if (c === "/") inRegex = false;
+      continue;
+    }
+    if (c === '"' || c === "'") quote = c;
+    else if (c === "/" && selector[i - 1] === "=") inRegex = true;
+    else if (c === "[" || c === "(") depth++;
+    else if (c === "]" || c === ")") depth--;
+    else if (depth === 0 && c === ">" && selector[i + 1] === ">") {
+      out.push(selector.slice(start, i));
+      i++;
+      start = i + 1;
+    }
+  }
+  out.push(selector.slice(start));
+  return out.map((p) => p.trim()).filter((p) => p.length > 0);
+}
+
+function parseRegex(body: string): RegExp | null {
+  if (!body.startsWith("/")) return null;
+  const end = body.lastIndexOf("/");
+  if (end <= 0) return null;
+  return new RegExp(body.slice(1, end), body.slice(end + 1));
+}
+
+function parseTextSpec(body: string): TextSpec {
+  const trimmed = body.trim();
+  const regex = parseRegex(trimmed);
+  if (regex) return { regex };
+  if (trimmed.length >= 2 && (trimmed[0] === '"' || trimmed[0] === "'") && trimmed.at(-1) === trimmed[0]) {
+    return { value: unquote(trimmed), exact: true };
+  }
+  return { value: trimmed };
+}
+
+function unquote(s: string): string {
+  const q = s[0]!;
+  let out = "";
+  for (let i = 1; i < s.length - 1; i++) {
+    const c = s[i]!;
+    if (c === "\\") {
+      const next = s[++i];
+      out += next === "n" ? "\n" : next === "t" ? "\t" : (next ?? "");
+    } else if (c !== q) {
+      out += c;
+    }
+  }
+  return out;
+}
+
+/** `[name="Save"]`, `[name=/sa/i]`, `[exact]`, `[checked]`, `[disabled]`. */
+function parseRoleAttrs(part: SelectorPart & { kind: "role" }, attrs: string, selector: string): void {
+  const re = /\[([a-zA-Z-]+)(?:=([^\]]*))?\]/g;
+  let m: RegExpExecArray | null;
+  let consumed = 0;
+  while ((m = re.exec(attrs))) {
+    consumed = re.lastIndex;
+    const key = m[1]!;
+    const raw = m[2];
+    switch (key) {
+      case "name":
+        part.name = parseTextSpec(raw ?? "");
+        break;
+      case "exact":
+        part.name = { ...(part.name ?? {}), exact: raw !== "false" };
+        break;
+      case "checked":
+        part.checked = raw !== "false";
+        break;
+      case "disabled":
+        part.disabled = raw !== "false";
+        break;
+      default:
+        throw new Error(`selector "${selector}": unknown role attribute [${key}]`);
+    }
+  }
+  if (consumed !== attrs.length) throw new Error(`selector "${selector}": malformed role attributes "${attrs}"`);
+}
+
+function parseNested(body: string, selector: string): SelectorPart[] {
+  const trimmed = body.trim();
+  const inner = trimmed.startsWith("(") && trimmed.endsWith(")") ? trimmed.slice(1, -1) : trimmed;
+  const parts = parseSelector(inner);
+  if (!parts.length) throw new Error(`selector "${selector}": empty nested selector`);
+  return parts;
+}
+
+export function parseSelector(selector: string): SelectorPart[] {
+  const out: SelectorPart[] = [];
+  for (const raw of splitParts(selector)) {
+    if (raw === "first") {
+      out.push({ kind: "nth", index: 0 });
+      continue;
+    }
+    if (raw === "last") {
+      out.push({ kind: "nth", index: -1 });
+      continue;
+    }
+    const eq = raw.indexOf("=");
+    if (eq < 0) throw new Error(`selector "${selector}": part "${raw}" has no engine (want engine=value)`);
+    const engine = raw.slice(0, eq).trim().toLowerCase();
+    const body = raw.slice(eq + 1).trim();
+    if (engine === "nth") {
+      const index = Number(body);
+      if (!Number.isInteger(index)) throw new Error(`selector "${selector}": nth=${body} is not an integer`);
+      out.push({ kind: "nth", index });
+    } else if (engine === "testid" || engine === "test-id") {
+      out.push({ kind: "testid", value: body.startsWith('"') || body.startsWith("'") ? unquote(body) : body });
+    } else if (engine === "type") {
+      out.push({ kind: "type", value: body });
+    } else if (engine === "role") {
+      const bracket = body.indexOf("[");
+      const part: SelectorPart & { kind: "role" } = {
+        kind: "role",
+        role: (bracket < 0 ? body : body.slice(0, bracket)).trim(),
+      };
+      if (bracket >= 0) parseRoleAttrs(part, body.slice(bracket), selector);
+      if (!part.role) throw new Error(`selector "${selector}": role= needs a role name`);
+      out.push(part);
+    } else if (TEXT_ENGINES.has(engine)) {
+      out.push({ kind: engine as "text" | "label" | "placeholder", ...parseTextSpec(body) });
+    } else if (engine === "has-text") {
+      out.push({ kind: "has-text", ...parseTextSpec(body) });
+    } else if (engine === "has" || engine === "has-not" || engine === "and") {
+      out.push({ kind: engine, parts: parseNested(body, selector) });
+    } else {
+      throw new Error(`selector "${selector}": unknown engine "${engine}"`);
+    }
+  }
+  return out;
+}
+
+function formatTextSpec(spec: TextSpec): string {
+  if (spec.regex) return String(spec.regex);
+  if (spec.exact) return JSON.stringify(spec.value ?? "");
+  return spec.value ?? "";
+}
+
+function formatPart(part: SelectorPart): string {
+  switch (part.kind) {
+    case "testid":
+      return `testid=${part.value}`;
+    case "type":
+      return `type=${part.value}`;
+    case "nth":
+      return `nth=${part.index}`;
+    case "role": {
+      let out = `role=${part.role}`;
+      // A quoted name already means exact, so [exact] is only emitted for the
+      // degenerate [exact]-with-no-name form.
+      if (part.name?.regex || part.name?.value) out += `[name=${formatTextSpec(part.name)}]`;
+      else if (part.name?.exact) out += "[exact]";
+      if (part.checked !== undefined) out += part.checked ? "[checked]" : "[checked=false]";
+      if (part.disabled !== undefined) out += part.disabled ? "[disabled]" : "[disabled=false]";
+      return out;
+    }
+    case "has":
+    case "has-not":
+    case "and":
+      return `${part.kind}=(${formatSelector(part.parts)})`;
+    default:
+      return `${part.kind}=${formatTextSpec(part)}`;
+  }
+}
+
+export function formatSelector(parts: SelectorPart[]): string {
+  return parts.map(formatPart).join(" >> ");
+}
+
+/** The literal a candidate list ranks against: the name/id the last engine
+ * part was reaching for. */
+export function intendedName(parts: SelectorPart[]): string | undefined {
+  for (let i = parts.length - 1; i >= 0; i--) {
+    const part = parts[i]!;
+    if (part.kind === "testid" || part.kind === "type") return part.value;
+    if (part.kind === "role") return part.name?.value ?? part.role;
+    if (part.kind === "text" || part.kind === "label" || part.kind === "placeholder" || part.kind === "has-text") {
+      return part.value ?? part.regex?.source;
+    }
+  }
+  return undefined;
+}

package/src/snapshot.ts

@@ -0,0 +1,72 @@
+// Compact accessibility-tree rendering, shared by the MCP `snapshot` tool and
+// anything that wants a tree in an error or a log.
+//
+// One line per node, indented by depth:
+//
+//   - window "Notes" [ref=e1]
+//     - button "Save" [ref=e12] [testid=save-btn] [enabled]
+//
+// A node with no role, text or testID carries no information a caller can act
+// on, so it collapses: its children move up to its own depth. That turns the
+// layout boxes that make up most of a real tree into nothing at all.
+import { hasRealSize, nodeChecked, nodeName, renderValue, type NdNode } from "./matcher.ts";
+
+export interface SnapshotOptions {
+  /** Keep only nodes an agent can act on (a role, plus visible and enabled),
+   * and the ancestors that lead to them. */
+  interactiveOnly?: boolean;
+  /** Cap the emitted lines; the renderer notes how many it dropped. */
+  maxLines?: number;
+}
+
+const NON_INTERACTIVE_ROLES = new Set(["window", "group", "label", "image", "toolbar", "list", "tree", "table"]);
+
+function identifies(node: NdNode): boolean {
+  return Boolean(node.role || node.testID || nodeName(node));
+}
+
+function actionable(node: NdNode): boolean {
+  if (!node.role || NON_INTERACTIVE_ROLES.has(node.role)) return false;
+  return node.visible && node.enabled && hasRealSize(node);
+}
+
+function line(node: NdNode, depth: number): string {
+  const bits = [`- ${node.role ?? node.type.toLowerCase()}`];
+  const name = nodeName(node);
+  if (name) bits.push(JSON.stringify(name));
+  bits.push(`[ref=e${node.ref}]`);
+  if (node.testID) bits.push(`[testid=${node.testID}]`);
+  const checked = nodeChecked(node);
+  if (checked !== undefined) bits.push(`[checked=${checked}]`);
+  else {
+    const value = renderValue(node.value);
+    if (value && value !== name) bits.push(`[value=${JSON.stringify(value)}]`);
+  }
+  if (!node.visible) bits.push("[hidden]");
+  bits.push(node.enabled ? "[enabled]" : "[disabled]");
+  return `${"  ".repeat(depth)}${bits.join(" ")}`;
+}
+
+/** True when the node or anything under it survives the interactive filter. */
+function keeps(node: NdNode, interactiveOnly: boolean): boolean {
+  if (!interactiveOnly) return true;
+  if (actionable(node)) return true;
+  return node.children.some((c) => keeps(c, interactiveOnly));
+}
+
+export function renderSnapshot(root: NdNode, opts: SnapshotOptions = {}): string {
+  const out: string[] = [];
+  const interactiveOnly = opts.interactiveOnly ?? false;
+  const walk = (node: NdNode, depth: number): void => {
+    if (!keeps(node, interactiveOnly)) return;
+    const show = identifies(node) && (!interactiveOnly || actionable(node) || node.children.length > 0);
+    if (show) out.push(line(node, depth));
+    for (const child of node.children) walk(child, show ? depth + 1 : depth);
+  };
+  walk(root, 0);
+  const max = opts.maxLines;
+  if (max !== undefined && out.length > max) {
+    return [...out.slice(0, max), `... ${out.length - max} more nodes (raise maxLines or scope to a window)`].join("\n");
+  }
+  return out.join("\n");
+}

package/src/socket.ts

@@ -98,9 +98,15 @@ export class AutomationClient {
     else pending.resolve(msg.result);
   }
 
+  // A method whose params are all optional (getTree) may be called with none
+  // at all, and then sends no params member rather than an empty object.
   call<M extends RpcMethodName>(
     method: M,
-    ...params: RpcParams<M> extends undefined ? [] : [RpcParams<M>]
+    ...params: RpcParams<M> extends undefined
+      ? []
+      : Record<string, never> extends RpcParams<M>
+        ? [RpcParams<M>?]
+        : [RpcParams<M>]
   ): Promise<RpcResult<M>> {
     const id = this.nextId++;
     const json = new TextEncoder().encode(JSON.stringify({ jsonrpc: "2.0", id, method, params: params[0] }));