@nativedesktop/test 0.4.1 → 0.4.3

package/src/fixtures/gestures-tree.json

@@ -0,0 +1,291 @@
+{
+  "coordinateSpace": "logical-window-topleft",
+  "root": {
+    "ref": 11,
+    "type": "Window",
+    "testID": null,
+    "text": "ND Gestures",
+    "visible": true,
+    "geometry": {
+      "x": 0,
+      "y": 0,
+      "w": 640,
+      "h": 560
+    },
+    "children": [
+      {
+        "ref": 10,
+        "type": "Box",
+        "testID": null,
+        "text": null,
+        "visible": true,
+        "geometry": {
+          "x": 0,
+          "y": 32,
+          "w": 640,
+          "h": 528
+        },
+        "children": [
+          {
+            "ref": 1,
+            "type": "Slider",
+            "testID": "volume-slider",
+            "text": null,
+            "visible": true,
+            "geometry": {
+              "x": 16,
+              "y": 48,
+              "w": 608,
+              "h": 16
+            },
+            "children": [],
+            "itemCount": null,
+            "rows": null,
+            "role": "slider",
+            "enabled": true,
+            "focused": false,
+            "value": 20,
+            "checked": null,
+            "selected": null,
+            "expanded": null,
+            "placeholder": null,
+            "label": null,
+            "options": null
+          },
+          {
+            "ref": 2,
+            "type": "Label",
+            "testID": "volume-label",
+            "text": "Volume: 20",
+            "visible": true,
+            "geometry": {
+              "x": 14,
+              "y": 72,
+              "w": 72,
+              "h": 16
+            },
+            "children": [],
+            "itemCount": null,
+            "rows": null,
+            "role": "label",
+            "enabled": true,
+            "focused": false,
+            "value": "Volume: 20",
+            "checked": null,
+            "selected": null,
+            "expanded": null,
+            "placeholder": null,
+            "label": null,
+            "options": null
+          },
+          {
+            "ref": 3,
+            "type": "Checkbox",
+            "testID": "agree-check",
+            "text": "I agree",
+            "visible": true,
+            "geometry": {
+              "x": 16,
+              "y": 96,
+              "w": 62,
+              "h": 16
+            },
+            "children": [],
+            "itemCount": null,
+            "rows": null,
+            "role": "checkbox",
+            "enabled": true,
+            "focused": false,
+            "value": false,
+            "checked": false,
+            "selected": null,
+            "expanded": null,
+            "placeholder": null,
+            "label": null,
+            "options": null
+          },
+          {
+            "ref": 4,
+            "type": "Label",
+            "testID": "agree-label",
+            "text": "Agreed: no",
+            "visible": true,
+            "geometry": {
+              "x": 14,
+              "y": 120,
+              "w": 70,
+              "h": 16
+            },
+            "children": [],
+            "itemCount": null,
+            "rows": null,
+            "role": "label",
+            "enabled": true,
+            "focused": false,
+            "value": "Agreed: no",
+            "checked": null,
+            "selected": null,
+            "expanded": null,
+            "placeholder": null,
+            "label": null,
+            "options": null
+          },
+          {
+            "ref": 5,
+            "type": "TextInput",
+            "testID": "name-input",
+            "text": "",
+            "visible": true,
+            "geometry": {
+              "x": 16,
+              "y": 144,
+              "w": 608,
+              "h": 24
+            },
+            "children": [],
+            "itemCount": null,
+            "rows": null,
+            "role": "textbox",
+            "enabled": true,
+            "focused": false,
+            "value": "",
+            "checked": null,
+            "selected": null,
+            "expanded": null,
+            "placeholder": "Type here",
+            "label": null,
+            "options": null
+          },
+          {
+            "ref": 6,
+            "type": "Label",
+            "testID": "echo-label",
+            "text": "Echo: ",
+            "visible": true,
+            "geometry": {
+              "x": 14,
+              "y": 176,
+              "w": 41,
+              "h": 16
+            },
+            "children": [],
+            "itemCount": null,
+            "rows": null,
+            "role": "label",
+            "enabled": true,
+            "focused": false,
+            "value": "Echo: ",
+            "checked": null,
+            "selected": null,
+            "expanded": null,
+            "placeholder": null,
+            "label": null,
+            "options": null
+          },
+          {
+            "ref": 7,
+            "type": "Table",
+            "testID": "people-table",
+            "text": null,
+            "visible": true,
+            "geometry": {
+              "x": 16,
+              "y": 200,
+              "w": 608,
+              "h": 295
+            },
+            "children": [],
+            "itemCount": 3,
+            "rows": null,
+            "role": "table",
+            "enabled": true,
+            "focused": false,
+            "value": 3,
+            "checked": null,
+            "selected": null,
+            "expanded": null,
+            "placeholder": null,
+            "label": null,
+            "options": null
+          },
+          {
+            "ref": 8,
+            "type": "Label",
+            "testID": "activated-label",
+            "text": "Activated: -1",
+            "visible": true,
+            "geometry": {
+              "x": 14,
+              "y": 504,
+              "w": 80,
+              "h": 16
+            },
+            "children": [],
+            "itemCount": null,
+            "rows": null,
+            "role": "label",
+            "enabled": true,
+            "focused": false,
+            "value": "Activated: -1",
+            "checked": null,
+            "selected": null,
+            "expanded": null,
+            "placeholder": null,
+            "label": null,
+            "options": null
+          },
+          {
+            "ref": 9,
+            "type": "Label",
+            "testID": "hover-target",
+            "text": "Hover / right-click target",
+            "visible": true,
+            "geometry": {
+              "x": 14,
+              "y": 528,
+              "w": 152,
+              "h": 16
+            },
+            "children": [],
+            "itemCount": null,
+            "rows": null,
+            "role": "label",
+            "enabled": true,
+            "focused": false,
+            "value": "Hover / right-click target",
+            "checked": null,
+            "selected": null,
+            "expanded": null,
+            "placeholder": null,
+            "label": null,
+            "options": null
+          }
+        ],
+        "itemCount": null,
+        "rows": null,
+        "role": "group",
+        "enabled": true,
+        "focused": false,
+        "value": null,
+        "checked": null,
+        "selected": null,
+        "expanded": null,
+        "placeholder": null,
+        "label": null,
+        "options": null
+      }
+    ],
+    "itemCount": null,
+    "rows": null,
+    "role": "window",
+    "enabled": true,
+    "focused": false,
+    "value": null,
+    "checked": null,
+    "selected": null,
+    "expanded": null,
+    "placeholder": null,
+    "label": null,
+    "options": null
+  }
+}

package/src/index.ts

@@ -1,7 +1,7 @@
 // @nativedesktop/test — §1.4: launchApp/AppHandle over the automation socket.
 // socket.ts's AutomationClient is the repo's ONE copy of the wire framing;
 // packages/mcp and the drive scripts import it from here rather than forking.
-export { AutomationClient } from "./socket.ts";
+export { AutomationClient, AutomationRpcError } from "./socket.ts";
 export { launchApp, AppHandle, killAll } from "./launch.ts";
 export type { LaunchOptions } from "./launch.ts";
 
@@ -22,6 +22,44 @@ export type { DialogScript } from "./dialogs.ts";
 export { pngSize } from "./png.ts";
 export type { PngSize } from "./png.ts";
 
+// Locators: Playwright semantics over getTree plus the action RPCs. A Locator
+// is lazy and re-resolves on every use, so a drive script never holds a ref
+// across a re-render.
+export { AttachedApp, connectApp } from "./attach.ts";
+export { Locator, LocatorFactory, callHost } from "./locator.ts";
+export type { ActionOptions, BoundingBox, LocatorClient, RoleOptions, TextOptions, WaitForState } from "./locator.ts";
+export { expect, LocatorAssertions, ValueAssertions } from "./expect.ts";
+export type { ExpectOptions } from "./expect.ts";
+export { Keyboard, Mouse, toChord } from "./keyboard.ts";
+export { LocatorError, StrictModeError, TimeoutError, describeNode, rankCandidates } from "./errors.ts";
+export { formatSelector, parseSelector } from "./selectors.ts";
+export type { SelectorPart, TextSpec } from "./selectors.ts";
+export {
+  allNodes,
+  asNdNode,
+  hasRealSize,
+  matchPart,
+  nodeChecked,
+  nodeName,
+  nodeText,
+  renderValue,
+  selectNodes,
+  subtreeText,
+} from "./matcher.ts";
+export type { NdNode } from "./matcher.ts";
+export { renderSnapshot } from "./snapshot.ts";
+export type { SnapshotOptions } from "./snapshot.ts";
+
 // Tree types a caller needs to type find()/tree() results, re-exported so
 // nothing outside this package has to import @nativedesktop/react/rpc itself.
-export type { GetTreeResult, JsonNode } from "@nativedesktop/react/rpc";
+export type {
+  Geometry,
+  GetTreeResult,
+  JsonNode,
+  ScreenshotResult,
+  SetWindowFrameParams,
+  WaitCondition,
+  WaitForResult,
+  WindowInfo,
+  WindowsResult,
+} from "@nativedesktop/react/rpc";

package/src/keyboard.ts

@@ -0,0 +1,143 @@
+// Playwright's Keyboard and Mouse over the `keys`, `pointer` and `drag` RPCs.
+//
+// The host chord spec takes lowercase modifier tokens (cmd/ctrl/shift/alt)
+// plus one key token, and lowercases every part it parses, so an uppercase
+// letter has to arrive as an explicit shift. Names outside the host's table
+// (Home/End/PageUp/PageDown/F1-F12) are passed through lowercased rather than
+// rejected here, so the client does not have to ship a new release when the
+// host's table grows.
+import type { LocatorClient } from "./locator.ts";
+
+const MODIFIERS: Record<string, string> = {
+  meta: "cmd",
+  cmd: "cmd",
+  command: "cmd",
+  control: "ctrl",
+  ctrl: "ctrl",
+  shift: "shift",
+  alt: "alt",
+  option: "alt",
+};
+
+const KEY_NAMES: Record<string, string> = {
+  arrowleft: "left",
+  arrowright: "right",
+  arrowup: "up",
+  arrowdown: "down",
+  esc: "escape",
+  escape: "escape",
+  enter: "enter",
+  return: "enter",
+  tab: "tab",
+  space: "space",
+  " ": "space",
+  backspace: "backspace",
+  delete: "delete",
+};
+
+/** "Meta+Shift+A" -> "cmd+shift+a"; "ArrowDown" -> "down"; "a" -> "a". */
+export function toChord(key: string): string {
+  const parts = key.split("+").filter((p) => p.length > 0);
+  const mods: string[] = [];
+  let token = "";
+  for (const raw of parts) {
+    const mod = MODIFIERS[raw.toLowerCase()];
+    if (mod) {
+      if (!mods.includes(mod)) mods.push(mod);
+      continue;
+    }
+    token = raw;
+  }
+  if (!token) throw new Error(`press(${JSON.stringify(key)}): no key left after the modifiers`);
+  if (token.length === 1 && token !== token.toLowerCase()) {
+    if (!mods.includes("shift")) mods.push("shift");
+    token = token.toLowerCase();
+  }
+  const named = KEY_NAMES[token.toLowerCase()];
+  const resolved = named ?? (token.length === 1 ? token : token.toLowerCase());
+  return mods.length ? [...mods, resolved].join("+") : resolved;
+}
+
+export class Keyboard {
+  constructor(
+    private readonly client: LocatorClient,
+    private readonly window?: number,
+  ) {}
+
+  /** One chord, in Playwright key names: press("Meta+A"), press("Escape"). */
+  async press(key: string): Promise<void> {
+    await this.client.callRpc("keys", { keys: toChord(key), window: this.window });
+  }
+
+  /** Types the literal text into the focused widget, one keystroke per
+   * character. A single named key would be read as a chord by the host, so
+   * route those through press(). */
+  async type(text: string): Promise<void> {
+    if (!text) return;
+    await this.client.callRpc("keys", { keys: text, window: this.window });
+  }
+
+  insertText(text: string): Promise<void> {
+    return this.type(text);
+  }
+}
+
+export interface MouseButtonOptions {
+  button?: "left" | "right";
+  clickCount?: number;
+}
+
+export class Mouse {
+  private x = 0;
+  private y = 0;
+
+  constructor(
+    private readonly client: LocatorClient,
+    private readonly window?: number,
+  ) {}
+
+  async move(x: number, y: number): Promise<void> {
+    this.x = x;
+    this.y = y;
+    await this.client.callRpc("pointer", { phase: "move", x, y, window: this.window });
+  }
+
+  async down(opts: MouseButtonOptions = {}): Promise<void> {
+    await this.client.callRpc("pointer", { phase: "down", x: this.x, y: this.y, ...opts, window: this.window });
+  }
+
+  async up(opts: MouseButtonOptions = {}): Promise<void> {
+    await this.client.callRpc("pointer", { phase: "up", x: this.x, y: this.y, ...opts, window: this.window });
+  }
+
+  async click(x: number, y: number, opts: MouseButtonOptions = {}): Promise<void> {
+    this.x = x;
+    this.y = y;
+    await this.down(opts);
+    await this.up(opts);
+  }
+
+  async dblclick(x: number, y: number, opts: MouseButtonOptions = {}): Promise<void> {
+    await this.click(x, y, opts);
+    await this.click(x, y, { ...opts, clickCount: 2 });
+  }
+
+  /** One posted down/dragged/up batch, so a native tracking loop consumes it
+   * as a real gesture. */
+  async dragTo(
+    from: { x: number; y: number },
+    to: { x: number; y: number },
+    opts: { steps?: number; durationMs?: number; button?: "left" | "right" } = {},
+  ): Promise<void> {
+    this.x = to.x;
+    this.y = to.y;
+    await this.client.callRpc("drag", {
+      fromX: from.x,
+      fromY: from.y,
+      toX: to.x,
+      toY: to.y,
+      ...opts,
+      window: this.window,
+    });
+  }
+}

package/src/launch.ts

@@ -20,15 +20,26 @@ import {
   type ScreenshotResult,
   type ScrollResult,
   type SetValueResult,
+  type SetWindowFrameParams,
   type TypeResult,
   type WaitCondition,
   type WaitForResult,
   type WebViewEvalResult,
   type WebViewInfo,
+  type WindowInfo,
   type WindowsResult,
 } from "@nativedesktop/react/rpc";
 import { TimedClient } from "./client.ts";
 import { type DialogScript, dialogScriptEnv } from "./dialogs.ts";
+import type { Keyboard, Mouse } from "./keyboard.ts";
+import {
+  callHost,
+  Locator,
+  LocatorFactory,
+  type LocatorClient,
+  type RoleOptions,
+  type TextOptions,
+} from "./locator.ts";
 import { findAllNodes, findMatchingNode, findNode, resolveTarget, type Target } from "./query.ts";
 import { registerProcess, unregisterProcess } from "./registry.ts";
 import { type ScreenshotOptions, takeScreenshot } from "./screenshot.ts";
@@ -64,6 +75,7 @@ export interface LaunchOptions {
 const DEFAULT_READY_MARKERS = ["ND_AUTOMATION_LISTENING", "ND_COMMIT_APPLIED"];
 const DEFAULT_READY_TIMEOUT_MS = 20_000;
 const DEFAULT_RPC_TIMEOUT_MS = 8_000;
+const DEFAULT_ACTION_TIMEOUT_MS = 5_000;
 const DEFAULT_RETRIES = 2;
 const MAX_STDERR_LINES = 5000;
 const STDERR_DRAIN_GRACE_MS = 1000;
@@ -168,9 +180,13 @@ interface LiveHost {
   exitedPromise: Promise<number>;
 }
 
-export class AppHandle {
+export class AppHandle implements LocatorClient {
+  /** Deadline every locator action, reader and expect matcher inherits. */
+  actionTimeout = DEFAULT_ACTION_TIMEOUT_MS;
+
   private live?: LiveHost;
   private client?: TimedClient;
+  private factory?: LocatorFactory;
 
   private constructor(private readonly config: ResolvedConfig) {}
 
@@ -346,6 +362,84 @@ export class AppHandle {
     return tail(this.live?.stderrLines ?? [], n);
   }
 
+  isAlive(): boolean {
+    return Boolean(this.live) && !this.live!.exited;
+  }
+
+  // --- locators --------------------------------------------------------------
+
+  /** Untyped RPC entry point the Locator layer dispatches through, so one
+   * call site serves every action method. Typed calls should keep going
+   * through `rpc.call`. */
+  callRpc(method: string, params?: Record<string, unknown>): Promise<unknown> {
+    return this.rpc.call(method as "click", params as never);
+  }
+
+  private get locators(): LocatorFactory {
+    return (this.factory ??= new LocatorFactory(this));
+  }
+
+  get keyboard(): Keyboard {
+    return this.locators.keyboard;
+  }
+
+  get mouse(): Mouse {
+    return this.locators.mouse;
+  }
+
+  locator(selector: string): Locator {
+    return this.locators.locator(selector);
+  }
+
+  getByTestId(testId: string): Locator {
+    return this.locators.getByTestId(testId);
+  }
+
+  getByRole(role: string, opts?: RoleOptions): Locator {
+    return this.locators.getByRole(role, opts);
+  }
+
+  getByText(text: string | RegExp, opts?: TextOptions): Locator {
+    return this.locators.getByText(text, opts);
+  }
+
+  getByLabel(text: string | RegExp, opts?: TextOptions): Locator {
+    return this.locators.getByLabel(text, opts);
+  }
+
+  getByPlaceholder(text: string | RegExp, opts?: TextOptions): Locator {
+    return this.locators.getByPlaceholder(text, opts);
+  }
+
+  /** A locator factory, keyboard and mouse 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);
+  }
+
+  /** 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. */
+  async setWindowSize(width: number, height: number, opts: { window?: number } = {}): Promise<WindowInfo> {
+    return (await callHost(this, "setWindowFrame", { window: opts.window, width, height })) as WindowInfo;
+  }
+
+  /** Moves and/or resizes a window; omitted components keep their current
+   * value. GTK ignores x/y (client-side placement is not a Wayland
+   * capability). */
+  async setWindowFrame(frame: SetWindowFrameParams): Promise<WindowInfo> {
+    return (await callHost(this, "setWindowFrame", { ...frame })) as WindowInfo;
+  }
+
   // --- tree queries ----------------------------------------------------------
 
   async tree(window?: number): Promise<GetTreeResult> {