@crewhaus/computer-use-driver 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/computer-use-driver",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Cross-platform mouse/keyboard/screenshot driver — chromium backend (Section 25 BROW)",
   "main": "src/index.ts",
@@ -12,7 +12,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.1"
+    "@crewhaus/errors": "0.1.3"
   },
   "peerDependencies": {
     "playwright": "*"
@@ -25,8 +25,8 @@
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -38,12 +38,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
-  },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+    "access": "public"
+  },
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/backends/backends.test.ts

@@ -13,9 +13,10 @@ describe("host driver — Section 30", () => {
     );
   });
 
-  test("connect + click + screenshot delegates to executor", async () => {
+  test("connect + every operation delegates to the executor", async () => {
     const calls: string[] = [];
     const viewport: Viewport = { width: 1920, height: 1080, devicePixelRatio: 1 };
+    let closed = false;
     const executor: HostExecutor = {
       async click(x, y, button) {
         calls.push(`click ${x},${y} ${button}`);
@@ -34,6 +35,9 @@ describe("host driver — Section 30", () => {
         // "iVBORw0KGgo=" decodes to the PNG magic bytes (0x89 0x50 0x4E 0x47 ...).
         return { pngBase64: "iVBORw0KGgo=", viewport };
       },
+      async close() {
+        closed = true;
+      },
     };
     const driver = createHostDriver({ enabled: true, executor });
     await driver.connect();
@@ -42,7 +46,76 @@ describe("host driver — Section 30", () => {
     expect(shot).toBeInstanceOf(Uint8Array);
     expect(shot[0]).toBe(0x89);
     expect(shot[1]).toBe(0x50);
-    expect(calls).toEqual(["click 100,200 left", "screenshot"]);
+    await driver.type("hello");
+    await driver.key("cmd+space");
+    await driver.scroll(5, 6);
+    const vp = await driver.getViewport();
+    expect(vp).toEqual(viewport);
+    await driver.disconnect();
+    expect(closed).toBe(true);
+    expect(calls).toEqual([
+      "click 100,200 left",
+      "screenshot",
+      "type hello",
+      "key cmd+space",
+      "scroll 0,0 5,6",
+      "screenshot", // getViewport screenshots to read the viewport
+    ]);
+  });
+
+  test("click defaults to the left button when none is given", async () => {
+    const calls: string[] = [];
+    const executor: HostExecutor = {
+      async click(x, y, button) {
+        calls.push(`click ${x},${y} ${button}`);
+      },
+      async type() {},
+      async key() {},
+      async scroll() {},
+      async screenshot() {
+        return { pngBase64: "", viewport: { width: 0, height: 0, devicePixelRatio: 1 } };
+      },
+    };
+    const driver = createHostDriver({ enabled: true, executor });
+    await driver.connect();
+    await driver.click(7, 8);
+    expect(calls).toEqual(["click 7,8 left"]);
+  });
+
+  test("disconnect tolerates an executor without a close() method", async () => {
+    const executor: HostExecutor = {
+      async click() {},
+      async type() {},
+      async key() {},
+      async scroll() {},
+      async screenshot() {
+        return { pngBase64: "", viewport: { width: 0, height: 0, devicePixelRatio: 1 } };
+      },
+      // no close — optional-chaining must not throw
+    };
+    const driver = createHostDriver({ enabled: true, executor });
+    await driver.connect();
+    await expect(driver.disconnect()).resolves.toBeUndefined();
+    // After disconnect, guarded operations throw again.
+    await expect(driver.screenshot()).rejects.toBeInstanceOf(ComputerUseDriverError);
+  });
+
+  test("type / key / getViewport reject before connect", async () => {
+    const executor: HostExecutor = {
+      async click() {},
+      async type() {},
+      async key() {},
+      async scroll() {},
+      async screenshot() {
+        return { pngBase64: "", viewport: { width: 0, height: 0, devicePixelRatio: 1 } };
+      },
+    };
+    const driver = createHostDriver({ enabled: true, executor });
+    await expect(driver.type("x")).rejects.toBeInstanceOf(ComputerUseDriverError);
+    await expect(driver.key("Enter")).rejects.toBeInstanceOf(ComputerUseDriverError);
+    await expect(driver.scroll(0, 0)).rejects.toBeInstanceOf(ComputerUseDriverError);
+    await expect(driver.getViewport()).rejects.toBeInstanceOf(ComputerUseDriverError);
+    await expect(driver.screenshot()).rejects.toBeInstanceOf(ComputerUseDriverError);
   });
 
   test("scroll delegates to executor with zero anchor", async () => {
@@ -165,4 +238,159 @@ describe("remote driver — Section 30", () => {
     expect(ops).toContain("click 50,60 right");
     expect(ops).toContain("close-browser");
   });
+
+  /** Build a fully-stubbed puppeteer-core whose page records into `ops`. */
+  function makeStub(ops: string[], opts?: { screenshotAsString?: boolean }) {
+    const page = {
+      async goto(url: string) {
+        ops.push(`goto ${url}`);
+      },
+      async screenshot(_o?: { encoding?: "base64" }) {
+        ops.push("screenshot");
+        // "aGk=" is base64 for "hi"; cover both the string and Buffer arms.
+        return opts?.screenshotAsString ? "aGk=" : Buffer.from("hi");
+      },
+      mouse: {
+        async click(x: number, y: number, o?: { button?: string }) {
+          ops.push(`click ${x},${y} ${o?.button}`);
+        },
+      },
+      keyboard: {
+        async type(text: string) {
+          ops.push(`type ${text}`);
+        },
+        async press(key: string) {
+          ops.push(`press ${key}`);
+        },
+      },
+      // The real driver casts the page and calls evaluate(fn, arg). Run the fn
+      // against a stub global exposing scrollBy so the closure body executes.
+      async evaluate(fn: (d: { dx: number; dy: number }) => void, arg: { dx: number; dy: number }) {
+        const g = globalThis as Record<string, unknown>;
+        const prev = g["scrollBy"];
+        g["scrollBy"] = (dx: number, dy: number) => {
+          ops.push(`scrollBy ${dx},${dy}`);
+        };
+        try {
+          fn(arg);
+        } finally {
+          g["scrollBy"] = prev;
+        }
+      },
+      async close() {
+        ops.push("close-page");
+      },
+    };
+    const browser = {
+      async newPage() {
+        return page;
+      },
+      async close() {
+        ops.push("close-browser");
+      },
+    };
+    const puppeteer: PuppeteerCoreLike = {
+      async connect(_o) {
+        return browser as never;
+      },
+    };
+    return { puppeteer, page, browser };
+  }
+
+  test("screenshot decodes a base64 string from puppeteer", async () => {
+    const ops: string[] = [];
+    const { puppeteer } = makeStub(ops, { screenshotAsString: true });
+    const driver = createRemoteDriver({ url: "ws://t", _puppeteer: puppeteer });
+    await driver.connect();
+    const png = await driver.screenshot();
+    expect(png).toBeInstanceOf(Uint8Array);
+    expect(Buffer.from(png).toString()).toBe("hi");
+  });
+
+  test("screenshot re-encodes a Buffer from puppeteer", async () => {
+    const ops: string[] = [];
+    const { puppeteer } = makeStub(ops, { screenshotAsString: false });
+    const driver = createRemoteDriver({ url: "ws://t", _puppeteer: puppeteer });
+    await driver.connect();
+    const png = await driver.screenshot();
+    expect(Buffer.from(png).toString()).toBe("hi");
+  });
+
+  test("type / key / scroll delegate through puppeteer", async () => {
+    const ops: string[] = [];
+    const { puppeteer } = makeStub(ops);
+    const driver = createRemoteDriver({ url: "ws://t", _puppeteer: puppeteer });
+    await driver.connect();
+    await driver.type("hello");
+    await driver.key("Enter");
+    await driver.scroll(11, 22);
+    expect(ops).toContain("type hello");
+    expect(ops).toContain("press Enter");
+    // The scroll closure runs in the (stubbed) page context and calls scrollBy.
+    expect(ops).toContain("scrollBy 11,22");
+  });
+
+  test("click defaults to the left button when none is given", async () => {
+    const ops: string[] = [];
+    const { puppeteer } = makeStub(ops);
+    const driver = createRemoteDriver({ url: "ws://t", _puppeteer: puppeteer });
+    await driver.connect();
+    await driver.click(1, 2);
+    expect(ops).toContain("click 1,2 left");
+  });
+
+  test("getViewport returns the override when provided", async () => {
+    const ops: string[] = [];
+    const { puppeteer } = makeStub(ops);
+    const viewport: Viewport = { width: 640, height: 480, devicePixelRatio: 2 };
+    const driver = createRemoteDriver({ url: "ws://t", viewport, _puppeteer: puppeteer });
+    await driver.connect();
+    expect(await driver.getViewport()).toEqual(viewport);
+  });
+
+  test("getViewport falls back to 1280x800 when no override", async () => {
+    const ops: string[] = [];
+    const { puppeteer } = makeStub(ops);
+    const driver = createRemoteDriver({ url: "ws://t", _puppeteer: puppeteer });
+    await driver.connect();
+    expect(await driver.getViewport()).toEqual({ width: 1280, height: 800, devicePixelRatio: 1 });
+  });
+
+  test("operations before connect throw 'not connected'", async () => {
+    const driver = createRemoteDriver({ url: "ws://t", _puppeteer: makeStub([]).puppeteer });
+    await expect(driver.goto("https://x.com")).rejects.toThrow(/not connected/);
+    await expect(driver.screenshot()).rejects.toThrow(/not connected/);
+    await expect(driver.click(0, 0)).rejects.toThrow(/not connected/);
+    await expect(driver.type("x")).rejects.toThrow(/not connected/);
+    await expect(driver.key("Enter")).rejects.toThrow(/not connected/);
+    await expect(driver.scroll(0, 0)).rejects.toThrow(/not connected/);
+  });
+
+  test("disconnect closes page then browser and resets state", async () => {
+    const ops: string[] = [];
+    const { puppeteer } = makeStub(ops);
+    const driver = createRemoteDriver({ url: "ws://t", _puppeteer: puppeteer });
+    await driver.connect();
+    await driver.disconnect();
+    expect(ops).toContain("close-page");
+    expect(ops).toContain("close-browser");
+    // After disconnect the page handle is cleared → operations throw again.
+    await expect(driver.click(0, 0)).rejects.toThrow(/not connected/);
+  });
+
+  test("disconnect swallows close() failures (best-effort)", async () => {
+    const ops: string[] = [];
+    const { puppeteer, page } = makeStub(ops);
+    page.close = async () => {
+      throw new Error("page close failed");
+    };
+    const driver = createRemoteDriver({ url: "ws://t", _puppeteer: puppeteer });
+    await driver.connect();
+    await expect(driver.disconnect()).resolves.toBeUndefined();
+  });
+
+  test("disconnect before connect is a no-op (no page / browser handles)", async () => {
+    const driver = createRemoteDriver({ url: "ws://t", _puppeteer: makeStub([]).puppeteer });
+    await expect(driver.disconnect()).resolves.toBeUndefined();
+  });
 });

package/src/chromium-import-fail.test.ts

@@ -0,0 +1,39 @@
+/**
+ * Catalog R18 — covers the chromium driver's `loadPlaywright` failure path
+ * (the catch arm that rethrows a `ComputerUseDriverError` with an install
+ * hint when `import("playwright")` rejects).
+ *
+ * The failing import is injected via the `_importPlaywright` seam instead of
+ * `mock.module("playwright", throwingFactory)`: bun's `mock.module` is
+ * process-global, and once "playwright" has been successfully imported
+ * anywhere in the test process (chromium.test.ts imports it as a fake), a
+ * *throwing* factory is evaluated eagerly and blows up at registration time.
+ * Because `bun test` runs every file in one process in nondeterministic
+ * order, the module-mock approach worked or exploded depending on which file
+ * ran first; the seam is order-independent.
+ */
+import { expect, test } from "bun:test";
+import { ComputerUseDriverError, createDriver } from "./index.js";
+
+// Rejects the way a missing optional peer dep does, exercising the same
+// catch arm in `loadPlaywright` as a genuine import failure.
+const failingImport = () => Promise.reject(new Error("Cannot find module 'playwright'"));
+
+test("connect surfaces a clean diagnostic when playwright import fails", async () => {
+  const d = createDriver({ backend: "chromium", _importPlaywright: failingImport });
+  await expect(d.connect()).rejects.toThrow(/Playwright not installed/);
+});
+
+test("the import error is preserved as the error cause", async () => {
+  const d = createDriver({ backend: "chromium", _importPlaywright: failingImport });
+  try {
+    await d.connect();
+    throw new Error("should have thrown");
+  } catch (err) {
+    expect(err).toBeInstanceOf(ComputerUseDriverError);
+    // `cause` is the standard Error.cause carrying the original import error.
+    const cause = (err as { cause?: unknown }).cause;
+    expect(cause).toBeInstanceOf(Error);
+    expect((cause as Error).message).toContain("Cannot find module");
+  }
+});