npm - @flrande/browserctl - Versions diffs - 0.1.0 - Mend

@flrande/browserctl 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (90) hide show

package/LICENSE +21 -0
package/README-CN.md +1155 -0
package/README.md +1155 -0
package/apps/browserctl/src/commands/a11y-snapshot.ts +20 -0
package/apps/browserctl/src/commands/act.ts +20 -0
package/apps/browserctl/src/commands/common.test.ts +87 -0
package/apps/browserctl/src/commands/common.ts +191 -0
package/apps/browserctl/src/commands/console-list.ts +20 -0
package/apps/browserctl/src/commands/cookie-clear.ts +18 -0
package/apps/browserctl/src/commands/cookie-get.ts +18 -0
package/apps/browserctl/src/commands/cookie-set.ts +22 -0
package/apps/browserctl/src/commands/dialog-arm.ts +20 -0
package/apps/browserctl/src/commands/dom-query-all.ts +18 -0
package/apps/browserctl/src/commands/dom-query.ts +18 -0
package/apps/browserctl/src/commands/download-trigger.ts +22 -0
package/apps/browserctl/src/commands/download-wait.test.ts +67 -0
package/apps/browserctl/src/commands/download-wait.ts +27 -0
package/apps/browserctl/src/commands/element-screenshot.ts +20 -0
package/apps/browserctl/src/commands/frame-list.ts +16 -0
package/apps/browserctl/src/commands/frame-snapshot.ts +18 -0
package/apps/browserctl/src/commands/network-wait-for.ts +100 -0
package/apps/browserctl/src/commands/profile-list.ts +16 -0
package/apps/browserctl/src/commands/profile-use.ts +18 -0
package/apps/browserctl/src/commands/response-body.ts +24 -0
package/apps/browserctl/src/commands/screenshot.ts +16 -0
package/apps/browserctl/src/commands/snapshot.ts +16 -0
package/apps/browserctl/src/commands/status.ts +10 -0
package/apps/browserctl/src/commands/storage-get.ts +20 -0
package/apps/browserctl/src/commands/storage-set.ts +22 -0
package/apps/browserctl/src/commands/tab-close.ts +20 -0
package/apps/browserctl/src/commands/tab-focus.ts +20 -0
package/apps/browserctl/src/commands/tab-open.ts +19 -0
package/apps/browserctl/src/commands/tabs.ts +13 -0
package/apps/browserctl/src/commands/upload-arm.ts +26 -0
package/apps/browserctl/src/daemon-client.test.ts +253 -0
package/apps/browserctl/src/daemon-client.ts +632 -0
package/apps/browserctl/src/e2e.test.ts +99 -0
package/apps/browserctl/src/main.test.ts +215 -0
package/apps/browserctl/src/main.ts +372 -0
package/apps/browserctl/src/smoke.test.ts +16 -0
package/apps/browserctl/src/smoke.ts +5 -0
package/apps/browserd/src/bootstrap.ts +432 -0
package/apps/browserd/src/chrome-relay-extension-bridge.test.ts +275 -0
package/apps/browserd/src/chrome-relay-extension-bridge.ts +506 -0
package/apps/browserd/src/container.ts +1531 -0
package/apps/browserd/src/main.test.ts +864 -0
package/apps/browserd/src/main.ts +7 -0
package/bin/browserctl.cjs +21 -0
package/bin/browserd.cjs +21 -0
package/extensions/chrome-relay/README.md +36 -0
package/extensions/chrome-relay/background.js +1687 -0
package/extensions/chrome-relay/manifest.json +15 -0
package/extensions/chrome-relay/popup.html +369 -0
package/extensions/chrome-relay/popup.js +972 -0
package/package.json +51 -0
package/packages/core/src/bootstrap.test.ts +10 -0
package/packages/core/src/driver-registry.test.ts +45 -0
package/packages/core/src/driver-registry.ts +22 -0
package/packages/core/src/driver.ts +47 -0
package/packages/core/src/index.ts +5 -0
package/packages/core/src/ref-cache.test.ts +61 -0
package/packages/core/src/ref-cache.ts +28 -0
package/packages/core/src/session-store.test.ts +49 -0
package/packages/core/src/session-store.ts +33 -0
package/packages/core/src/types.ts +9 -0
package/packages/driver-chrome-relay/src/chrome-relay-driver.test.ts +634 -0
package/packages/driver-chrome-relay/src/chrome-relay-driver.ts +2206 -0
package/packages/driver-chrome-relay/src/chrome-relay-extension-runtime.test.ts +264 -0
package/packages/driver-chrome-relay/src/chrome-relay-extension-runtime.ts +521 -0
package/packages/driver-chrome-relay/src/index.ts +26 -0
package/packages/driver-managed/src/index.ts +22 -0
package/packages/driver-managed/src/managed-driver.test.ts +59 -0
package/packages/driver-managed/src/managed-driver.ts +125 -0
package/packages/driver-managed/src/managed-local-driver.test.ts +506 -0
package/packages/driver-managed/src/managed-local-driver.ts +2021 -0
package/packages/driver-remote-cdp/src/index.ts +19 -0
package/packages/driver-remote-cdp/src/remote-cdp-driver.test.ts +617 -0
package/packages/driver-remote-cdp/src/remote-cdp-driver.ts +2042 -0
package/packages/protocol/src/envelope.test.ts +25 -0
package/packages/protocol/src/envelope.ts +31 -0
package/packages/protocol/src/errors.test.ts +17 -0
package/packages/protocol/src/errors.ts +11 -0
package/packages/protocol/src/index.ts +3 -0
package/packages/protocol/src/tools.ts +3 -0
package/packages/transport-mcp-stdio/src/index.ts +3 -0
package/packages/transport-mcp-stdio/src/sdk-server.ts +139 -0
package/packages/transport-mcp-stdio/src/server.test.ts +281 -0
package/packages/transport-mcp-stdio/src/server.ts +183 -0
package/packages/transport-mcp-stdio/src/tool-map.ts +67 -0
package/scripts/smoke.ps1 +127 -0

package/packages/driver-remote-cdp/src/index.ts ADDED Viewed

@@ -0,0 +1,19 @@
+export { createRemoteCdpDriver } from "./remote-cdp-driver";
+export type {
+  RemoteCdpBrowser,
+  RemoteCdpBrowserContext,
+  RemoteCdpConsoleEntry,
+  RemoteCdpConsoleEntryLocation,
+  RemoteCdpDriverConfig,
+  RemoteCdpDriverRuntime,
+  RemoteCdpDriverStatus,
+  RemoteCdpEndpoint,
+  RemoteCdpKeyboard,
+  RemoteCdpLocator,
+  RemoteCdpNetworkRequestSummary,
+  RemoteCdpNetworkResponseBody,
+  RemoteCdpPage,
+  RemoteCdpScreenshot,
+  RemoteCdpSnapshot,
+  RemoteCdpTelemetryDriverExtensions
+} from "./remote-cdp-driver";

package/packages/driver-remote-cdp/src/remote-cdp-driver.test.ts ADDED Viewed

@@ -0,0 +1,617 @@
+import { describe, expect, it, vi } from "vitest";
+import { createRemoteCdpDriver } from "./index";
+type MockConsoleMessage = {
+  type(): string;
+  text(): string;
+  location?(): {
+    url?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+  };
+};
+type MockNetworkResponse = {
+  url(): string;
+  status(): number;
+  request(): {
+    method(): string;
+    resourceType?(): string;
+  };
+  text?(): Promise<string>;
+  body?(): Promise<Uint8Array | ArrayBuffer | string>;
+};
+type MockDialog = {
+  accept?(): Promise<void>;
+  dismiss?(): Promise<void>;
+};
+type MockDownload = {
+  path?(): Promise<string>;
+  saveAs?(path: string): Promise<void>;
+  suggestedFilename?(): string;
+  url?(): string;
+  mimeType?(): string;
+};
+type MockPage = {
+  goto(url: string): Promise<void>;
+  bringToFront(): Promise<void>;
+  close(): Promise<void>;
+  url(): string;
+  title(): Promise<string>;
+  content(): Promise<string>;
+  screenshot?(options?: Record<string, unknown>): Promise<unknown>;
+  locator(selector: string): {
+    click(): Promise<void>;
+    fill(value: string): Promise<void>;
+    type(value: string): Promise<void>;
+    setInputFiles?(files: string[]): Promise<void>;
+  };
+  keyboard?: {
+    press(key: string): Promise<void>;
+  };
+  on?(eventName: string, listener: (payload: unknown) => unknown): void;
+  waitForEvent?(eventName: string): Promise<unknown>;
+};
+type MockPageRecord = {
+  page: MockPage;
+  goto: ReturnType<typeof vi.fn>;
+  bringToFront: ReturnType<typeof vi.fn>;
+  close: ReturnType<typeof vi.fn>;
+  title: ReturnType<typeof vi.fn>;
+  content: ReturnType<typeof vi.fn>;
+  screenshot: ReturnType<typeof vi.fn>;
+  locator: ReturnType<typeof vi.fn>;
+  locatorClick: ReturnType<typeof vi.fn>;
+  locatorFill: ReturnType<typeof vi.fn>;
+  locatorType: ReturnType<typeof vi.fn>;
+  locatorSetInputFiles: ReturnType<typeof vi.fn>;
+  keyboardPress: ReturnType<typeof vi.fn>;
+  waitForEvent: ReturnType<typeof vi.fn>;
+  on: ReturnType<typeof vi.fn>;
+  emitConsole(entry: MockConsoleMessage): Promise<void>;
+  emitResponse(response: MockNetworkResponse): Promise<void>;
+  emitDialog(dialog: MockDialog): Promise<void>;
+  emitDownload(download: MockDownload): Promise<void>;
+  getUrl(): string;
+};
+type RuntimeHarness = {
+  runtime: {
+    connectOverCDP(endpointUrl: string): Promise<{
+      contexts(): Array<{
+        newPage(): Promise<MockPage>;
+      }>;
+      close(): Promise<void>;
+    }>;
+  };
+  connectOverCDP: ReturnType<typeof vi.fn>;
+  browserClose: ReturnType<typeof vi.fn>;
+  pages: MockPageRecord[];
+};
+type RuntimeHarnessOptions = {
+  supportsDownloadEvents?: boolean;
+};
+function createMockPageRecord(pageNumber: number): MockPageRecord {
+  let currentUrl = "about:blank";
+  const listeners = new Map<string, Array<(payload: unknown) => unknown>>();
+  const waiters = new Map<
+    string,
+    Array<{ resolve: (value: unknown) => void; reject: (error: unknown) => void }>
+  >();
+  const goto = vi.fn(async (url: string) => {
+    currentUrl = url;
+  });
+  const bringToFront = vi.fn(async () => {});
+  const close = vi.fn(async () => {});
+  const title = vi.fn(async () => `mock-title-${pageNumber}`);
+  const content = vi.fn(async () => `<html data-page="${pageNumber}" />`);
+  const screenshot = vi.fn(async () => new Uint8Array([0, 1, 2, pageNumber]));
+  const locatorClick = vi.fn(async () => {});
+  const locatorFill = vi.fn(async (_value: string) => {});
+  const locatorType = vi.fn(async (_value: string) => {});
+  const locatorSetInputFiles = vi.fn(async (_files: string[]) => {});
+  const locator = vi.fn((_selector: string) => ({
+    click: locatorClick,
+    fill: locatorFill,
+    type: locatorType,
+    setInputFiles: locatorSetInputFiles
+  }));
+  const keyboardPress = vi.fn(async (_key: string) => {});
+  const waitForEvent = vi.fn(async (eventName: string) => {
+    return await new Promise<unknown>((resolve, reject) => {
+      const current = waiters.get(eventName);
+      if (current !== undefined) {
+        current.push({ resolve, reject });
+        return;
+      }
+      waiters.set(eventName, [{ resolve, reject }]);
+    });
+  });
+  const on = vi.fn((eventName: string, listener: (payload: unknown) => unknown) => {
+    const existing = listeners.get(eventName);
+    if (existing !== undefined) {
+      existing.push(listener);
+      return;
+    }
+    listeners.set(eventName, [listener]);
+  });
+  const emit = async (eventName: string, payload: unknown): Promise<void> => {
+    const eventListeners = listeners.get(eventName);
+    if (eventListeners !== undefined) {
+      for (const listener of eventListeners) {
+        await listener(payload);
+      }
+    }
+    const eventWaiters = waiters.get(eventName);
+    if (eventWaiters === undefined || eventWaiters.length === 0) {
+      return;
+    }
+    const nextWaiter = eventWaiters.shift();
+    nextWaiter?.resolve(payload);
+  };
+  const page: MockPage = {
+    goto,
+    bringToFront,
+    close,
+    url: () => currentUrl,
+    title,
+    content,
+    screenshot,
+    locator,
+    on,
+    waitForEvent,
+    keyboard: {
+      press: keyboardPress
+    }
+  };
+  return {
+    page,
+    goto,
+    bringToFront,
+    close,
+    title,
+    content,
+    screenshot,
+    locator,
+    locatorClick,
+    locatorFill,
+    locatorType,
+    locatorSetInputFiles,
+    keyboardPress,
+    waitForEvent,
+    on,
+    emitConsole: async (entry) => {
+      await emit("console", entry);
+    },
+    emitResponse: async (response) => {
+      await emit("response", response);
+    },
+    emitDialog: async (dialog) => {
+      await emit("dialog", dialog);
+    },
+    emitDownload: async (download) => {
+      await emit("download", download);
+    },
+    getUrl: () => currentUrl
+  };
+}
+function createRuntimeHarness(options: RuntimeHarnessOptions = {}): RuntimeHarness {
+  const supportsDownloadEvents = options.supportsDownloadEvents ?? false;
+  const pages: MockPageRecord[] = [];
+  const newPage = vi.fn(async () => {
+    const pageRecord = createMockPageRecord(pages.length + 1);
+    if (!supportsDownloadEvents) {
+      delete (pageRecord.page as Record<string, unknown>).waitForEvent;
+    }
+    pages.push(pageRecord);
+    return pageRecord.page;
+  });
+  const browserClose = vi.fn(async () => {});
+  const connectOverCDP = vi.fn(async () => ({
+    contexts: () => [
+      {
+        newPage
+      }
+    ],
+    close: browserClose
+  }));
+  return {
+    runtime: {
+      connectOverCDP
+    },
+    connectOverCDP,
+    browserClose,
+    pages
+  };
+}
+describe("createRemoteCdpDriver", () => {
+  it("throws when cdpUrl is empty", () => {
+    expect(() => createRemoteCdpDriver({ cdpUrl: "" })).toThrowError(
+      "Invalid cdpUrl: value must not be empty."
+    );
+  });
+  it("keeps status lazy and reports parsed endpoint", async () => {
+    const harness = createRuntimeHarness();
+    const driver = createRemoteCdpDriver({
+      cdpUrl: "  ws://localhost:9222/devtools/browser/example  ",
+      runtime: harness.runtime
+    });
+    expect(await driver.status()).toEqual({
+      kind: "remote-cdp",
+      connected: false,
+      endpoint: {
+        url: "ws://localhost:9222/devtools/browser/example",
+        protocol: "ws:",
+        host: "localhost:9222"
+      }
+    });
+    expect(await driver.listTabs()).toEqual([]);
+    expect(harness.connectOverCDP).toHaveBeenCalledTimes(0);
+    await driver.openTab("https://example.com/a", "profile:alpha");
+    expect(harness.connectOverCDP).toHaveBeenCalledWith(
+      "ws://localhost:9222/devtools/browser/example"
+    );
+    expect(await driver.status()).toMatchObject({
+      kind: "remote-cdp",
+      connected: true
+    });
+  });
+  it("open/list/focus/close keeps deterministic ids per profile", async () => {
+    const harness = createRuntimeHarness();
+    const driver = createRemoteCdpDriver({
+      cdpUrl: "ws://localhost:9222/devtools/browser/example",
+      runtime: harness.runtime
+    });
+    const alpha = "profile:alpha";
+    const firstTarget = await driver.openTab("https://example.com/1", alpha);
+    const secondTarget = await driver.openTab("https://example.com/2", alpha);
+    const betaTarget = await driver.openTab("https://example.com/3", "profile:beta");
+    expect(firstTarget).toBe("target:remote-cdp:profile:alpha:1");
+    expect(secondTarget).toBe("target:remote-cdp:profile:alpha:2");
+    expect(betaTarget).toBe("target:remote-cdp:profile:beta:1");
+    expect(await driver.listTabs(alpha)).toEqual([firstTarget, secondTarget]);
+    await driver.focusTab(secondTarget, alpha);
+    expect(harness.pages[1]?.bringToFront).toHaveBeenCalledTimes(1);
+    await driver.closeTab(firstTarget, alpha);
+    expect(await driver.listTabs(alpha)).toEqual([secondTarget]);
+    await driver.closeTab(secondTarget, alpha);
+    expect(await driver.listTabs(alpha)).toEqual([]);
+  });
+  it("snapshot reports hasTarget true for active tab and false after close", async () => {
+    const harness = createRuntimeHarness();
+    const driver = createRemoteCdpDriver({
+      cdpUrl: "ws://localhost:9222/devtools/browser/example",
+      runtime: harness.runtime
+    });
+    const profile = "profile:alpha";
+    const targetId = await driver.openTab("https://example.com/snapshot", profile);
+    await expect(driver.snapshot(targetId, profile)).resolves.toEqual({
+      kind: "remote-cdp",
+      profile,
+      targetId,
+      endpoint: {
+        url: "ws://localhost:9222/devtools/browser/example",
+        protocol: "ws:",
+        host: "localhost:9222"
+      },
+      hasTarget: true,
+      url: "https://example.com/snapshot",
+      title: "mock-title-1",
+      html: '<html data-page="1" />',
+      requestSummaries: []
+    });
+    await expect(driver.screenshot(targetId, profile)).resolves.toEqual({
+      kind: "remote-cdp",
+      profile,
+      targetId,
+      endpoint: {
+        url: "ws://localhost:9222/devtools/browser/example",
+        protocol: "ws:",
+        host: "localhost:9222"
+      },
+      hasTarget: true,
+      mimeType: "image/png",
+      encoding: "base64",
+      imageBase64: "AAECAQ=="
+    });
+    expect(harness.pages[0]?.screenshot).toHaveBeenCalledTimes(1);
+    await driver.closeTab(targetId, profile);
+    await expect(driver.snapshot(targetId, profile)).resolves.toEqual({
+      kind: "remote-cdp",
+      profile,
+      targetId,
+      endpoint: {
+        url: "ws://localhost:9222/devtools/browser/example",
+        protocol: "ws:",
+        host: "localhost:9222"
+      },
+      hasTarget: false
+    });
+    await expect(driver.screenshot(targetId, profile)).resolves.toMatchObject({
+      hasTarget: false
+    });
+  });
+  it("act supports goto/click/fill/type/press and unknown action fallback", async () => {
+    const harness = createRuntimeHarness();
+    const driver = createRemoteCdpDriver({
+      cdpUrl: "ws://localhost:9222/devtools/browser/example",
+      runtime: harness.runtime
+    });
+    const profile = "profile:alpha";
+    const targetId = await driver.openTab("https://example.com/start", profile);
+    const pageRecord = harness.pages[0];
+    if (pageRecord === undefined) {
+      throw new Error("Expected a mock page record.");
+    }
+    await driver.act({ type: "goto", payload: { url: "https://example.com/next" } }, targetId, profile);
+    await driver.act({ type: "click", payload: { selector: "#go" } }, targetId, profile);
+    await driver.act(
+      { type: "fill", payload: { selector: "#name", value: "remote" } },
+      targetId,
+      profile
+    );
+    await driver.act(
+      { type: "type", payload: { selector: "#query", text: "remote cdp" } },
+      targetId,
+      profile
+    );
+    await driver.act({ type: "press", payload: { key: "Enter" } }, targetId, profile);
+    await expect(driver.act({ type: "unknown:noop" }, targetId, profile)).resolves.toMatchObject({
+      actionType: "unknown:noop",
+      profile,
+      targetId,
+      targetKnown: true,
+      ok: true,
+      executed: false
+    });
+    expect(pageRecord.getUrl()).toBe("https://example.com/next");
+    expect(pageRecord.locator).toHaveBeenCalledWith("#go");
+    expect(pageRecord.locatorClick).toHaveBeenCalledTimes(1);
+    expect(pageRecord.locatorFill).toHaveBeenCalledWith("remote");
+    expect(pageRecord.locatorType).toHaveBeenCalledWith("remote cdp");
+    expect(pageRecord.keyboardPress).toHaveBeenCalledWith("Enter");
+  });
+  it("captures console + network telemetry and supports request body lookup", async () => {
+    const harness = createRuntimeHarness();
+    const driver = createRemoteCdpDriver({
+      cdpUrl: "ws://localhost:9222/devtools/browser/example",
+      runtime: harness.runtime
+    });
+    const profile = "profile:alpha";
+    const targetId = await driver.openTab("https://example.com/events", profile);
+    const pageRecord = harness.pages[0];
+    if (pageRecord === undefined) {
+      throw new Error("Expected a mock page record.");
+    }
+    await pageRecord.emitConsole({
+      type: () => "warning",
+      text: () => "remote warning",
+      location: () => ({
+        url: "https://example.com/app.js",
+        lineNumber: 9,
+        columnNumber: 4
+      })
+    });
+    await pageRecord.emitResponse({
+      url: () => "https://example.com/api/items",
+      status: () => 200,
+      request: () => ({
+        method: () => "GET",
+        resourceType: () => "xhr"
+      }),
+      text: async () => '{"ok":true}'
+    });
+    await pageRecord.emitResponse({
+      url: () => "https://example.com/api/binary",
+      status: () => 201,
+      request: () => ({
+        method: () => "POST",
+        resourceType: () => "fetch"
+      }),
+      body: async () => new Uint8Array([0, 1, 2])
+    });
+    const telemetryDriver = driver as typeof driver & {
+      getConsoleEntries?: (targetId: string, profile?: string) => Array<{
+        text: string;
+        type: string;
+      }>;
+      getNetworkResponseBody?: (
+        requestId: string,
+        targetId: string,
+        profile?: string
+      ) => { body: string; encoding: "utf8" | "base64" } | undefined;
+    };
+    const consoleEntries = telemetryDriver.getConsoleEntries?.(targetId, profile) ?? [];
+    expect(consoleEntries).toEqual([
+      expect.objectContaining({
+        type: "warning",
+        text: "remote warning",
+        location: {
+          url: "https://example.com/app.js",
+          lineNumber: 9,
+          columnNumber: 4
+        }
+      })
+    ]);
+    consoleEntries[0].text = "mutated";
+    expect(telemetryDriver.getConsoleEntries?.(targetId, profile)?.[0]?.text).toBe("remote warning");
+    const snapshot = await driver.snapshot(targetId, profile);
+    expect(snapshot).toMatchObject({
+      hasTarget: true,
+      requestSummaries: [
+        expect.objectContaining({
+          requestId: expect.any(String),
+          url: "https://example.com/api/items",
+          method: "GET",
+          resourceType: "xhr",
+          status: 200
+        }),
+        expect.objectContaining({
+          requestId: expect.any(String),
+          url: "https://example.com/api/binary",
+          method: "POST",
+          resourceType: "fetch",
+          status: 201
+        })
+      ]
+    });
+    const requestSummaries = (
+      snapshot as {
+        requestSummaries?: Array<{ requestId: string; url: string }>;
+      }
+    ).requestSummaries;
+    const firstRequestId = requestSummaries?.[0]?.requestId;
+    const secondRequestId = requestSummaries?.[1]?.requestId;
+    if (typeof firstRequestId !== "string" || typeof secondRequestId !== "string") {
+      throw new Error("Expected request ids from telemetry snapshot.");
+    }
+    expect(telemetryDriver.getNetworkResponseBody?.(firstRequestId, targetId, profile)).toEqual({
+      body: '{"ok":true}',
+      encoding: "utf8"
+    });
+    expect(telemetryDriver.getNetworkResponseBody?.(secondRequestId, targetId, profile)).toEqual({
+      body: "AAEC",
+      encoding: "base64"
+    });
+    expect(telemetryDriver.getNetworkResponseBody?.("request:missing", targetId, profile)).toBeUndefined();
+  });
+  it("keeps upload/dialog/download state scoped to target + profile", async () => {
+    const harness = createRuntimeHarness();
+    const driver = createRemoteCdpDriver({
+      cdpUrl: "ws://localhost:9222/devtools/browser/example",
+      runtime: harness.runtime
+    });
+    const alphaProfile = "profile:alpha";
+    const betaProfile = "profile:beta";
+    const alphaTarget = await driver.openTab("https://example.com/alpha", alphaProfile);
+    const betaTarget = await driver.openTab("https://example.com/beta", betaProfile);
+    await expect(driver.armUpload(alphaTarget, ["wrong-profile.txt"], betaProfile)).rejects.toThrowError(
+      `Unknown targetId: ${alphaTarget} (profile: ${betaProfile})`
+    );
+    await driver.armUpload(alphaTarget, ["alpha.txt"], alphaProfile);
+    await driver.armUpload(betaTarget, ["beta.txt"], betaProfile);
+    await driver.armDialog(betaTarget, betaProfile);
+    await driver.triggerDownload(alphaTarget, alphaProfile);
+    await driver.triggerDownload(betaTarget, betaProfile);
+    await expect(driver.waitDownload(alphaTarget, alphaProfile)).resolves.toEqual({
+      path: "remote-cdp-profile%3Aalpha-target%3Aremote-cdp%3Aprofile%3Aalpha%3A1-1.bin",
+      profile: alphaProfile,
+      targetId: alphaTarget,
+      endpoint: {
+        url: "ws://localhost:9222/devtools/browser/example",
+        protocol: "ws:",
+        host: "localhost:9222"
+      },
+      uploadFiles: ["alpha.txt"],
+      dialogArmedCount: 0,
+      triggerCount: 1
+    });
+    await expect(driver.waitDownload(betaTarget, betaProfile)).resolves.toEqual({
+      path: "remote-cdp-profile%3Abeta-target%3Aremote-cdp%3Aprofile%3Abeta%3A1-1.bin",
+      profile: betaProfile,
+      targetId: betaTarget,
+      endpoint: {
+        url: "ws://localhost:9222/devtools/browser/example",
+        protocol: "ws:",
+        host: "localhost:9222"
+      },
+      uploadFiles: ["beta.txt"],
+      dialogArmedCount: 1,
+      triggerCount: 1
+    });
+  });
+  it("supports real upload/dialog/download hooks when runtime exposes events", async () => {
+    const harness = createRuntimeHarness({
+      supportsDownloadEvents: true
+    });
+    const driver = createRemoteCdpDriver({
+      cdpUrl: "ws://localhost:9222/devtools/browser/example",
+      runtime: harness.runtime
+    });
+    const profile = "profile:alpha";
+    const targetId = await driver.openTab("https://example.com/upload", profile);
+    const pageRecord = harness.pages[0];
+    if (pageRecord === undefined) {
+      throw new Error("Expected page record.");
+    }
+    await driver.armUpload(targetId, ["C:\\upload\\alpha.txt"], profile);
+    await driver.act({ type: "click", payload: { selector: "#file" } }, targetId, profile);
+    expect(pageRecord.locatorSetInputFiles).toHaveBeenCalledWith(["C:\\upload\\alpha.txt"]);
+    const dialogAccept = vi.fn(async () => {});
+    await driver.armDialog(targetId, profile);
+    await pageRecord.emitDialog({
+      accept: dialogAccept
+    });
+    expect(dialogAccept).toHaveBeenCalledTimes(1);
+    await driver.triggerDownload(targetId, profile);
+    await pageRecord.emitDownload({
+      path: async () => "C:\\downloads\\alpha.bin",
+      suggestedFilename: () => "alpha.bin",
+      url: () => "https://example.com/alpha.bin",
+      mimeType: () => "application/octet-stream"
+    });
+    await expect(driver.waitDownload(targetId, profile)).resolves.toMatchObject({
+      path: "C:\\downloads\\alpha.bin",
+      profile,
+      targetId,
+      suggestedFilename: "alpha.bin",
+      url: "https://example.com/alpha.bin",
+      mimeType: "application/octet-stream",
+      triggerCount: 1
+    });
+  });
+});