@nativedesktop/test 0.1.2 → 0.3.0

package/package.json

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

package/src/client.ts

@@ -5,6 +5,11 @@
 import { AutomationClient } from "./socket.ts";
 import type { RpcMethodName, RpcParams, RpcResult } from "@nativedesktop/react/rpc";
 
+/// Room for the host to answer after its own deadline expires, for calls that
+/// declare one (waitFor, webviewEval). Small: the host answers a timeout in
+/// one poll interval.
+const HOST_ANSWER_SLACK_MS = 2000;
+
 export class TimedClient {
   constructor(
     private readonly inner: AutomationClient,
@@ -20,7 +25,12 @@ export class TimedClient {
     method: M,
     ...params: RpcParams<M> extends undefined ? [] : [RpcParams<M>]
   ): Promise<RpcResult<M>> {
-    const ms = this.timeoutMs;
+    // A call that carries its OWN deadline must not be cut short by the
+    // blanket one: a `waitFor` asked to wait 15s failed here at the 8s default,
+    // which reads as a product bug rather than a harness setting.
+    const declared = (params[0] as { timeoutMs?: number } | undefined)?.timeoutMs;
+    const ms =
+      typeof declared === "number" ? Math.max(this.timeoutMs, declared + HOST_ANSWER_SLACK_MS) : this.timeoutMs;
     let timer: ReturnType<typeof setTimeout>;
     const timeout = new Promise<never>((_resolve, reject) => {
       timer = setTimeout(() => {

package/src/launch.ts

@@ -8,21 +8,24 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Backend } from "@nativedesktop/host";
 import { resolveBackend, resolveHostBinary } from "@nativedesktop/host";
-import { AutomationClient } from "./socket.ts";
-import type {
-  DragParams,
-  DragResult,
-  ClickResult,
-  GetTreeResult,
-  JsonNode,
-  KeysResult,
-  ScreenshotResult,
-  ScrollResult,
-  SetValueResult,
-  TypeResult,
-  WaitCondition,
-  WaitForResult,
-  WindowsResult,
+import { AutomationClient, AutomationRpcError } from "./socket.ts";
+import {
+  type DragParams,
+  type DragResult,
+  type ClickResult,
+  type GetTreeResult,
+  type JsonNode,
+  type KeysResult,
+  RPC_ERRORS,
+  type ScreenshotResult,
+  type ScrollResult,
+  type SetValueResult,
+  type TypeResult,
+  type WaitCondition,
+  type WaitForResult,
+  type WebViewEvalResult,
+  type WebViewInfo,
+  type WindowsResult,
 } from "@nativedesktop/react/rpc";
 import { TimedClient } from "./client.ts";
 import { type DialogScript, dialogScriptEnv } from "./dialogs.ts";
@@ -143,8 +146,12 @@ interface ResolvedConfig {
   onStderr?: (line: string) => void;
 }
 
+/// The slice of Bun's FileSink the log pump uses. `write` is typed
+/// `number | Promise<number>` upstream (it buffers, and only awaits on flush),
+/// so narrowing it to `number` here made `bunx tsc --noEmit` fail for every
+/// consumer of this package.
 interface LineSink {
-  write(chunk: Uint8Array): number;
+  write(chunk: Uint8Array): number | Promise<number>;
   end(): void;
 }
 
@@ -345,14 +352,32 @@ export class AppHandle {
     return this.rpc.call("getTree", { window });
   }
 
+  // A window closing between windows() (or an earlier query) and this call
+  // races the window ref out from under `opts.window`; getTree answers the
+  // distinguishable windowGone error rather than invalidParams (see
+  // schema/rpc.json), and every find* helper below treats that exactly like
+  // an unmatched testId: null, an empty list, or a "not found" throw. tree()
+  // itself does NOT swallow it: a raw tree() caller needs to know the window
+  // is gone rather than get a fake empty snapshot that reads the same as
+  // "this window really has no children".
+  private isWindowGone(e: unknown): boolean {
+    return e instanceof AutomationRpcError && e.code === RPC_ERRORS.windowGone.code;
+  }
+
   async find(testId: string, opts: { window?: number } = {}): Promise<JsonNode | null> {
-    const t = await this.tree(opts.window);
-    return findNode(t.root, testId);
+    const t = await this.tree(opts.window).catch((e) => {
+      if (this.isWindowGone(e)) return null;
+      throw e;
+    });
+    return t ? findNode(t.root, testId) : null;
   }
 
   async findAll(testId: string, opts: { window?: number } = {}): Promise<JsonNode[]> {
-    const t = await this.tree(opts.window);
-    return findAllNodes(t.root, testId);
+    const t = await this.tree(opts.window).catch((e) => {
+      if (this.isWindowGone(e)) return null;
+      throw e;
+    });
+    return t ? findAllNodes(t.root, testId) : [];
   }
 
   async mustFind(testId: string, opts: { window?: number } = {}): Promise<JsonNode> {
@@ -362,8 +387,11 @@ export class AppHandle {
   }
 
   async findMatching(pred: (n: JsonNode) => boolean, opts: { window?: number } = {}): Promise<JsonNode | null> {
-    const t = await this.tree(opts.window);
-    return findMatchingNode(t.root, pred);
+    const t = await this.tree(opts.window).catch((e) => {
+      if (this.isWindowGone(e)) return null;
+      throw e;
+    });
+    return t ? findMatchingNode(t.root, pred) : null;
   }
 
   // --- actions (single RPC, host-side resolution, no retry loops) ------------
@@ -444,6 +472,59 @@ export class AppHandle {
     return this.waitFor(contains ? { testId, valueContains: rendered } : { testId, valueEquals: rendered }, rest);
   }
 
+  // --- webview / page ------------------------------------------------------
+  // The page half of the vocabulary. None of it needs the app to forward
+  // events: url and title come off the engine, page text and eval run in the
+  // page itself.
+
+  waitForUrl(testId: string, urlContains: string, opts?: WaitOpts): Promise<WaitForResult> {
+    return this.waitFor({ testId, urlContains }, opts);
+  }
+
+  waitForPageTitle(testId: string, pageTitleContains: string, opts?: WaitOpts): Promise<WaitForResult> {
+    return this.waitFor({ testId, pageTitleContains }, opts);
+  }
+
+  /** Injects `document.body.innerText` into the page, re-probed at most once
+   * per 250ms — so a match can lag the page by one probe. */
+  waitForPageText(testId: string, pageTextContains: string, opts?: WaitOpts): Promise<WaitForResult> {
+    return this.waitFor({ testId, pageTextContains }, opts);
+  }
+
+  webviewInfo(target: Target, opts: { window?: number } = {}): Promise<WebViewInfo> {
+    return this.rpc.call("webviewInfo", { ...resolveTarget(target), ...opts });
+  }
+
+  /** Evaluates `code` in the page (optionally in a named isolated world) and
+   * answers the result's string rendering. A thrown exception comes back as
+   * `{ok: false, error}`, not a rejection — the code ran. */
+  evalInPage(
+    target: Target,
+    code: string,
+    opts: { world?: string; window?: number; timeoutMs?: number } = {},
+  ): Promise<WebViewEvalResult> {
+    return this.rpc.call("webviewEval", { ...resolveTarget(target), code, ...opts });
+  }
+
+  /** Navigates a webview and waits for the page to commit that URL. The
+   * navigate rides the widget's own `url` prop on the app side, so this drives
+   * the engine directly instead: `location.href = ...` in the page, then the
+   * host-side url predicate. */
+  async openAndAwaitLoad(testId: string, url: string, opts: WaitOpts = {}): Promise<WaitForResult> {
+    await this.evalInPage({ testId }, `location.href = ${JSON.stringify(url)}`, { window: opts.window });
+    // Match on the URL minus its scheme: engines normalise (trailing slash,
+    // percent-encoding, http/https upgrades), so the full string rarely
+    // survives verbatim.
+    return this.waitForUrl(testId, url.replace(/^[a-z]+:\/\//i, ""), opts);
+  }
+
+  /** Screenshot of the window holding a webview. On GTK the in-process
+   * snapshot already rasterizes live WebKit content, so this is the ordinary
+   * capture with a floor that rejects a blank frame. */
+  screenshotPage(path: string, opts: ScreenshotOptions = {}): Promise<ScreenshotResult> {
+    return this.screenshot(path, { minBytes: 2048, ...opts });
+  }
+
   async waitForMarker(marker: string, timeoutMs = 5000): Promise<void> {
     const deadline = Date.now() + timeoutMs;
     for (;;) {

package/src/screenshot.ts

@@ -8,8 +8,9 @@
 import { existsSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
 import type { Backend } from "@nativedesktop/host";
-import type { ScreenshotResult } from "@nativedesktop/react/rpc";
+import { RPC_ERRORS, type ScreenshotResult } from "@nativedesktop/react/rpc";
 import { pngSize } from "./png.ts";
+import { AutomationRpcError } from "./socket.ts";
 
 export interface ScreenshotOptions {
   window?: number;
@@ -50,6 +51,11 @@ export async function takeScreenshot(
       }
       return shot;
     } catch (e) {
+      // A closed window is never coming back mid-run, so retrying just
+      // burns the retry budget on a guaranteed repeat failure; fail fast
+      // with the distinguishable error instead of the generic "N attempts"
+      // wrapper the frame-invalidation races below are meant for.
+      if (e instanceof AutomationRpcError && e.code === RPC_ERRORS.windowGone.code) throw e;
       lastErr = e as Error;
       if (attempt < retries - 1) await new Promise((r) => setTimeout(r, 150));
     }

package/src/socket.ts

@@ -21,6 +21,25 @@ interface JsonRpcResponse {
   error?: JsonRpcError;
 }
 
+/**
+ * A rejected call's `code`/`data` survive on the error object (matching
+ * schema/rpc.json's `errors` table, e.g. RPC_ERRORS.windowGone.code), so a
+ * caller can branch on the error kind without parsing `.message` text.
+ * `.message` keeps the existing "<msg> (<code>)" shape so callers that
+ * already substring-match a code keep working.
+ */
+export class AutomationRpcError extends Error {
+  readonly code: number;
+  readonly data: unknown;
+
+  constructor(code: number, message: string, data?: unknown) {
+    super(`${message} (${code})`);
+    this.name = "AutomationRpcError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
 export class AutomationClient {
   private socket!: import("bun").Socket;
   private inbox = new Uint8Array(0);
@@ -75,7 +94,7 @@ export class AutomationClient {
     const pending = this.pending.get(msg.id);
     if (!pending) return; // unknown/stale id — drop
     this.pending.delete(msg.id);
-    if (msg.error) pending.reject(new Error(`${msg.error.message} (${msg.error.code})`));
+    if (msg.error) pending.reject(new AutomationRpcError(msg.error.code, msg.error.message, msg.error.data));
     else pending.resolve(msg.result);
   }