@flrande/browserctl 0.1.0 → 0.2.0-dev.12.1

package/apps/browserctl/src/main.dispatch.test.ts

@@ -0,0 +1,256 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import * as a11ySnapshotCommand from "./commands/a11y-snapshot";
+import * as consoleListCommand from "./commands/console-list";
+import * as cookieClearCommand from "./commands/cookie-clear";
+import * as cookieGetCommand from "./commands/cookie-get";
+import * as cookieSetCommand from "./commands/cookie-set";
+import * as daemonClient from "./daemon-client";
+import * as dialogArmCommand from "./commands/dialog-arm";
+import * as domQueryAllCommand from "./commands/dom-query-all";
+import * as domQueryCommand from "./commands/dom-query";
+import * as downloadTriggerCommand from "./commands/download-trigger";
+import * as downloadWaitCommand from "./commands/download-wait";
+import * as elementScreenshotCommand from "./commands/element-screenshot";
+import * as frameListCommand from "./commands/frame-list";
+import * as frameSnapshotCommand from "./commands/frame-snapshot";
+import * as networkWaitForCommand from "./commands/network-wait-for";
+import * as profileListCommand from "./commands/profile-list";
+import * as profileUseCommand from "./commands/profile-use";
+import * as responseBodyCommand from "./commands/response-body";
+import * as snapshotCommand from "./commands/snapshot";
+import * as storageGetCommand from "./commands/storage-get";
+import * as storageSetCommand from "./commands/storage-set";
+import * as tabCloseCommand from "./commands/tab-close";
+import * as tabFocusCommand from "./commands/tab-focus";
+import * as tabOpenCommand from "./commands/tab-open";
+import * as uploadArmCommand from "./commands/upload-arm";
+import { EXIT_CODES, runCli } from "./main";
+
+function createIoCapture() {
+  const state = {
+    stdout: "",
+    stderr: ""
+  };
+
+  return {
+    state,
+    io: {
+      stdout: {
+        write(content: string) {
+          state.stdout += content;
+        }
+      },
+      stderr: {
+        write(content: string) {
+          state.stderr += content;
+        }
+      }
+    }
+  };
+}
+
+type DispatchCase = {
+  command: string;
+  commandArgs: string[];
+  moduleRef: Record<string, unknown>;
+  handlerName: string;
+};
+
+const COMMAND_DISPATCH_CASES: DispatchCase[] = [
+  {
+    command: "a11y-snapshot",
+    commandArgs: ["target:1"],
+    moduleRef: a11ySnapshotCommand as unknown as Record<string, unknown>,
+    handlerName: "runA11ySnapshotCommand"
+  },
+  {
+    command: "console-list",
+    commandArgs: ["target:1"],
+    moduleRef: consoleListCommand as unknown as Record<string, unknown>,
+    handlerName: "runConsoleListCommand"
+  },
+  {
+    command: "cookie-clear",
+    commandArgs: ["target:1"],
+    moduleRef: cookieClearCommand as unknown as Record<string, unknown>,
+    handlerName: "runCookieClearCommand"
+  },
+  {
+    command: "cookie-get",
+    commandArgs: ["target:1"],
+    moduleRef: cookieGetCommand as unknown as Record<string, unknown>,
+    handlerName: "runCookieGetCommand"
+  },
+  {
+    command: "cookie-set",
+    commandArgs: ["target:1", "sid", "abc"],
+    moduleRef: cookieSetCommand as unknown as Record<string, unknown>,
+    handlerName: "runCookieSetCommand"
+  },
+  {
+    command: "dialog-arm",
+    commandArgs: ["target:1"],
+    moduleRef: dialogArmCommand as unknown as Record<string, unknown>,
+    handlerName: "runDialogArmCommand"
+  },
+  {
+    command: "dom-query",
+    commandArgs: ["target:1", "#root"],
+    moduleRef: domQueryCommand as unknown as Record<string, unknown>,
+    handlerName: "runDomQueryCommand"
+  },
+  {
+    command: "dom-query-all",
+    commandArgs: ["target:1", ".item"],
+    moduleRef: domQueryAllCommand as unknown as Record<string, unknown>,
+    handlerName: "runDomQueryAllCommand"
+  },
+  {
+    command: "download-trigger",
+    commandArgs: ["target:1"],
+    moduleRef: downloadTriggerCommand as unknown as Record<string, unknown>,
+    handlerName: "runDownloadTriggerCommand"
+  },
+  {
+    command: "download-wait",
+    commandArgs: ["target:1"],
+    moduleRef: downloadWaitCommand as unknown as Record<string, unknown>,
+    handlerName: "runDownloadWaitCommand"
+  },
+  {
+    command: "element-screenshot",
+    commandArgs: ["target:1", "#hero"],
+    moduleRef: elementScreenshotCommand as unknown as Record<string, unknown>,
+    handlerName: "runElementScreenshotCommand"
+  },
+  {
+    command: "frame-list",
+    commandArgs: ["target:1"],
+    moduleRef: frameListCommand as unknown as Record<string, unknown>,
+    handlerName: "runFrameListCommand"
+  },
+  {
+    command: "frame-snapshot",
+    commandArgs: ["target:1", "frame:0"],
+    moduleRef: frameSnapshotCommand as unknown as Record<string, unknown>,
+    handlerName: "runFrameSnapshotCommand"
+  },
+  {
+    command: "network-wait-for",
+    commandArgs: ["target:1", "/api", "1000"],
+    moduleRef: networkWaitForCommand as unknown as Record<string, unknown>,
+    handlerName: "runNetworkWaitForCommand"
+  },
+  {
+    command: "profile-list",
+    commandArgs: [],
+    moduleRef: profileListCommand as unknown as Record<string, unknown>,
+    handlerName: "runProfileListCommand"
+  },
+  {
+    command: "profile-use",
+    commandArgs: ["managed"],
+    moduleRef: profileUseCommand as unknown as Record<string, unknown>,
+    handlerName: "runProfileUseCommand"
+  },
+  {
+    command: "response-body",
+    commandArgs: ["target:1", "request:1"],
+    moduleRef: responseBodyCommand as unknown as Record<string, unknown>,
+    handlerName: "runResponseBodyCommand"
+  },
+  {
+    command: "snapshot",
+    commandArgs: ["target:1"],
+    moduleRef: snapshotCommand as unknown as Record<string, unknown>,
+    handlerName: "runSnapshotCommand"
+  },
+  {
+    command: "storage-get",
+    commandArgs: ["target:1", "local", "theme"],
+    moduleRef: storageGetCommand as unknown as Record<string, unknown>,
+    handlerName: "runStorageGetCommand"
+  },
+  {
+    command: "storage-set",
+    commandArgs: ["target:1", "local", "theme", "dark"],
+    moduleRef: storageSetCommand as unknown as Record<string, unknown>,
+    handlerName: "runStorageSetCommand"
+  },
+  {
+    command: "tab-close",
+    commandArgs: ["target:1"],
+    moduleRef: tabCloseCommand as unknown as Record<string, unknown>,
+    handlerName: "runTabCloseCommand"
+  },
+  {
+    command: "tab-focus",
+    commandArgs: ["target:1"],
+    moduleRef: tabFocusCommand as unknown as Record<string, unknown>,
+    handlerName: "runTabFocusCommand"
+  },
+  {
+    command: "tab-open",
+    commandArgs: ["https://example.com"],
+    moduleRef: tabOpenCommand as unknown as Record<string, unknown>,
+    handlerName: "runTabOpenCommand"
+  },
+  {
+    command: "upload-arm",
+    commandArgs: ["target:1", "upload.txt"],
+    moduleRef: uploadArmCommand as unknown as Record<string, unknown>,
+    handlerName: "runUploadArmCommand"
+  }
+];
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("cli dispatch matrix", () => {
+  it.each(COMMAND_DISPATCH_CASES)(
+    "dispatches $command to $handlerName",
+    async ({ command, commandArgs, moduleRef, handlerName }) => {
+      const handler = moduleRef[handlerName] as ((args: string[]) => Promise<unknown>) | undefined;
+      if (typeof handler !== "function") {
+        throw new Error(`Expected ${handlerName} to be a function.`);
+      }
+
+      const handlerSpy = vi.spyOn(moduleRef as Record<string, (...args: unknown[]) => unknown>, handlerName)
+        .mockResolvedValue({ ok: true });
+      const { io, state } = createIoCapture();
+
+      const exitCode = await runCli([command, ...commandArgs], io);
+
+      expect(exitCode).toBe(EXIT_CODES.OK);
+      expect(state.stderr).toBe("");
+      expect(state.stdout).toMatch(new RegExp(`^${command}: `));
+      expect(handlerSpy).toHaveBeenCalledTimes(1);
+      expect(handlerSpy).toHaveBeenCalledWith(commandArgs);
+    }
+  );
+
+  it("dispatches daemon-stop through daemon client", async () => {
+    const stopSpy = vi.spyOn(daemonClient, "stopDaemon").mockResolvedValue({
+      stopped: true,
+      port: 41337,
+      pid: 12345
+    });
+    const { io, state } = createIoCapture();
+
+    const exitCode = await runCli(["daemon-stop", "--json"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.OK);
+    expect(stopSpy).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(state.stdout)).toEqual({
+      ok: true,
+      command: "daemon-stop",
+      data: {
+        stopped: true,
+        port: 41337,
+        pid: 12345
+      }
+    });
+  });
+});

package/apps/browserctl/src/smoke.e2e.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { stopDaemon } from "./daemon-client";
+import { EXIT_CODES, runCli } from "./main";
+import { reserveLoopbackPort } from "./test-port";
+
+let testDaemonPort = 0;
+let activeRelayPort = 0;
+
+function createIoCapture() {
+  const state = {
+    stdout: "",
+    stderr: ""
+  };
+
+  return {
+    state,
+    io: {
+      stdout: {
+        write(content: string) {
+          state.stdout += content;
+        }
+      },
+      stderr: {
+        write(content: string) {
+          state.stderr += content;
+        }
+      }
+    }
+  };
+}
+
+function parseJsonLine(state: { stdout: string }): Record<string, unknown> {
+  return JSON.parse(state.stdout.trim()) as Record<string, unknown>;
+}
+
+beforeEach(async () => {
+  testDaemonPort = await reserveLoopbackPort();
+  activeRelayPort = await reserveLoopbackPort();
+  while (activeRelayPort === testDaemonPort) {
+    activeRelayPort = await reserveLoopbackPort();
+  }
+
+  process.env.BROWSERCTL_DAEMON_PORT = String(testDaemonPort);
+  process.env.BROWSERD_CHROME_RELAY_URL = `http://127.0.0.1:${activeRelayPort}`;
+  delete process.env.BROWSERD_MANAGED_LOCAL_ENABLED;
+  delete process.env.BROWSERD_DEFAULT_DRIVER;
+  delete process.env.BROWSERD_CHROME_RELAY_MODE;
+  delete process.env.BROWSERD_CHROME_RELAY_EXTENSION_TOKEN;
+  await stopDaemon(testDaemonPort);
+});
+
+afterEach(async () => {
+  await stopDaemon(testDaemonPort);
+  delete process.env.BROWSERCTL_DAEMON_PORT;
+  delete process.env.BROWSERD_CHROME_RELAY_URL;
+  delete process.env.BROWSERD_MANAGED_LOCAL_ENABLED;
+  delete process.env.BROWSERD_DEFAULT_DRIVER;
+  delete process.env.BROWSERD_CHROME_RELAY_MODE;
+  delete process.env.BROWSERD_CHROME_RELAY_EXTENSION_TOKEN;
+});
+
+describe("browserctl smoke e2e", () => {
+  it("starts with extension-first defaults and reports chrome-relay status", async () => {
+    const startCapture = createIoCapture();
+    const startExitCode = await runCli(["daemon-start", "--json"], startCapture.io);
+
+    expect(startExitCode).toBe(EXIT_CODES.OK);
+    const startPayload = parseJsonLine(startCapture.state);
+    expect(startPayload.ok).toBe(true);
+
+    const statusCapture = createIoCapture();
+    const statusExitCode = await runCli(["status", "--json"], statusCapture.io);
+
+    expect(statusExitCode).toBe(EXIT_CODES.OK);
+    const statusPayload = parseJsonLine(statusCapture.state);
+    expect(statusPayload.ok).toBe(true);
+    const statusData = statusPayload.data as Record<string, unknown>;
+    expect(statusData.driver).toBe("chrome-relay");
+    expect(statusData.status).toMatchObject({
+      kind: "chrome-relay",
+      connected: false
+    });
+    const relayStatus = statusData.status as Record<string, unknown>;
+    expect(String(relayStatus.relayUrl ?? "")).toContain(`:${activeRelayPort}`);
+
+    const stopCapture = createIoCapture();
+    const stopExitCode = await runCli(["daemon-stop", "--json"], stopCapture.io);
+    expect(stopExitCode).toBe(EXIT_CODES.OK);
+    const stopPayload = parseJsonLine(stopCapture.state);
+    expect(stopPayload.ok).toBe(true);
+    expect(stopPayload.data).toMatchObject({
+      stopped: true,
+      port: testDaemonPort
+    });
+  }, 20_000);
+});

package/apps/browserctl/src/test-port.ts

@@ -0,0 +1,26 @@
+import { createServer } from "node:net";
+
+export async function reserveLoopbackPort(): Promise<number> {
+  return await new Promise<number>((resolve, reject) => {
+    const server = createServer();
+
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (typeof address !== "object" || address === null) {
+        server.close(() => reject(new Error("Failed to reserve loopback port.")));
+        return;
+      }
+
+      const port = address.port;
+      server.close((error) => {
+        if (error !== undefined) {
+          reject(error);
+          return;
+        }
+
+        resolve(port);
+      });
+    });
+  });
+}

package/apps/browserd/src/chrome-relay-extension-bridge.test.ts

@@ -1,33 +1,8 @@
-import { createServer } from "node:net";
-
 import { afterEach, describe, expect, it } from "vitest";
 import { WebSocket } from "ws";
 
 import { createChromeRelayExtensionBridge } from "./chrome-relay-extension-bridge";
-
-async function reservePort(): Promise<number> {
-  return await new Promise<number>((resolve, reject) => {
-    const server = createServer();
-    server.once("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (typeof address !== "object" || address === null) {
-        server.close(() => resolve(0));
-        return;
-      }
-
-      const port = address.port;
-      server.close((closeError) => {
-        if (closeError !== undefined) {
-          reject(closeError);
-          return;
-        }
-
-        resolve(port);
-      });
-    });
-  });
-}
+import { reserveLoopbackPort } from "./test-port";
 
 async function waitForCondition(predicate: () => boolean, timeoutMs = 1000): Promise<void> {
   const start = Date.now();
@@ -61,7 +36,7 @@ afterEach(async () => {
 
 describe("createChromeRelayExtensionBridge", () => {
   it("requires token configuration for extension bridge startup", async () => {
-    const port = await reservePort();
+    const port = await reserveLoopbackPort();
 
     expect(() =>
       createChromeRelayExtensionBridge({
@@ -71,7 +46,7 @@ describe("createChromeRelayExtensionBridge", () => {
   });
 
   it("sends requests to extension client and receives responses", async () => {
-    const port = await reservePort();
+    const port = await reserveLoopbackPort();
     const bridge = createChromeRelayExtensionBridge({
       relayUrl: `http://127.0.0.1:${port}`,
       token: "secret-token",
@@ -134,7 +109,7 @@ describe("createChromeRelayExtensionBridge", () => {
   });
 
   it("rejects invoke when extension is not connected", async () => {
-    const port = await reservePort();
+    const port = await reserveLoopbackPort();
     const bridge = createChromeRelayExtensionBridge({
       relayUrl: `http://127.0.0.1:${port}`,
       token: "secret-token",
@@ -148,7 +123,7 @@ describe("createChromeRelayExtensionBridge", () => {
   });
 
   it("enforces token validation for extension websocket connection", async () => {
-    const port = await reservePort();
+    const port = await reserveLoopbackPort();
     const bridge = createChromeRelayExtensionBridge({
       relayUrl: `http://127.0.0.1:${port}`,
       token: "secret-token",
@@ -188,7 +163,7 @@ describe("createChromeRelayExtensionBridge", () => {
   });
 
   it("forwards extension event envelopes to bridge listeners", async () => {
-    const port = await reservePort();
+    const port = await reserveLoopbackPort();
     const bridge = createChromeRelayExtensionBridge({
       relayUrl: `http://127.0.0.1:${port}`,
       token: "secret-token",

package/apps/browserd/src/container.ts

@@ -53,9 +53,11 @@ export type BrowserdConfig = {
 
 const DEFAULT_DRIVER_KEY = "managed";
 const MANAGED_LOCAL_DRIVER_KEY = "managed-local";
+const DEFAULT_CONFIG_DRIVER_KEY = "chrome-relay";
 const DEFAULT_MANAGED_LOCAL_BROWSER_NAME: ManagedLocalBrowserName = "chromium";
 const DEFAULT_MANAGED_LOCAL_HEADLESS = true;
-const DEFAULT_CHROME_RELAY_MODE: ChromeRelayMode = "cdp";
+const DEFAULT_CHROME_RELAY_MODE: ChromeRelayMode = "extension";
+const DEFAULT_CHROME_RELAY_EXTENSION_TOKEN = "browserctl-relay";
 const DEFAULT_CHROME_RELAY_EXTENSION_REQUEST_TIMEOUT_MS = 5_000;
 const DEFAULT_NETWORK_WAIT_TIMEOUT_MS = 10_000;
 const DEFAULT_NETWORK_WAIT_POLL_MS = 200;
@@ -181,7 +183,11 @@ function parseManagedLocalBrowserName(value: string | undefined): ManagedLocalBr
 
 function parseChromeRelayMode(value: string | undefined): ChromeRelayMode {
   const normalizedValue = value?.trim().toLowerCase();
-  return normalizedValue === "extension" ? "extension" : DEFAULT_CHROME_RELAY_MODE;
+  if (normalizedValue === "extension" || normalizedValue === "cdp") {
+    return normalizedValue;
+  }
+
+  return DEFAULT_CHROME_RELAY_MODE;
 }
 
 export type BrowserdContainer = {
@@ -198,16 +204,12 @@ export function loadBrowserdConfig(
 ): BrowserdConfig {
   const managedLocalEnabled = parseBooleanFlag(env.BROWSERD_MANAGED_LOCAL_ENABLED, true);
   const chromeRelayMode = parseChromeRelayMode(env.BROWSERD_CHROME_RELAY_MODE);
-  const chromeRelayExtensionToken = resolveNonEmptyString(env.BROWSERD_CHROME_RELAY_EXTENSION_TOKEN);
-  if (chromeRelayMode === "extension" && chromeRelayExtensionToken === undefined) {
-    throw new Error(
-      "BROWSERD_CHROME_RELAY_EXTENSION_TOKEN is required when BROWSERD_CHROME_RELAY_MODE=extension."
-    );
-  }
+  const chromeRelayExtensionToken =
+    resolveNonEmptyString(env.BROWSERD_CHROME_RELAY_EXTENSION_TOKEN) ??
+    (chromeRelayMode === "extension" ? DEFAULT_CHROME_RELAY_EXTENSION_TOKEN : undefined);
 
   const defaultDriver =
-    resolveNonEmptyString(env.BROWSERD_DEFAULT_DRIVER) ??
-    (managedLocalEnabled ? MANAGED_LOCAL_DRIVER_KEY : DEFAULT_DRIVER_KEY);
+    resolveNonEmptyString(env.BROWSERD_DEFAULT_DRIVER) ?? DEFAULT_CONFIG_DRIVER_KEY;
 
   return {
     chromeRelayUrl: env.BROWSERD_CHROME_RELAY_URL ?? "http://127.0.0.1:9223",