@flrande/browserctl 0.1.0-dev.7.1

package/packages/driver-managed/src/managed-driver.ts

@@ -0,0 +1,125 @@
+import type { BrowserDriver } from "../../core/src/driver";
+import type { ProfileId, TargetId } from "../../core/src/types";
+
+export type ManagedDriverStatus = {
+  kind: "managed";
+  connected: true;
+};
+
+const DEFAULT_PROFILE_ID: ProfileId = "profile:managed:default";
+
+type ManagedTab = {
+  url: string;
+};
+
+type ManagedProfileState = {
+  nextTargetNumber: number;
+  tabs: Map<TargetId, ManagedTab>;
+  tabOrder: TargetId[];
+  focusedTargetId?: TargetId;
+};
+
+function resolveProfileId(profile?: ProfileId): ProfileId {
+  return profile ?? DEFAULT_PROFILE_ID;
+}
+
+function createTargetId(profileId: ProfileId, targetNumber: number): TargetId {
+  return `target:managed:${profileId}:${targetNumber}`;
+}
+
+function createProfileState(): ManagedProfileState {
+  return {
+    nextTargetNumber: 1,
+    tabs: new Map<TargetId, ManagedTab>(),
+    tabOrder: []
+  };
+}
+
+export function createManagedDriver(): BrowserDriver<ManagedDriverStatus> {
+  const profileStates = new Map<ProfileId, ManagedProfileState>();
+
+  function getOrCreateProfileState(profileId: ProfileId): ManagedProfileState {
+    const existingState = profileStates.get(profileId);
+    if (existingState !== undefined) {
+      return existingState;
+    }
+
+    const createdState = createProfileState();
+    profileStates.set(profileId, createdState);
+    return createdState;
+  }
+
+  function requireTargetInProfile(profileId: ProfileId, targetId: TargetId): ManagedProfileState {
+    const profileState = profileStates.get(profileId);
+    if (profileState === undefined || !profileState.tabs.has(targetId)) {
+      throw new Error(`Unknown targetId: ${targetId} (profile: ${profileId})`);
+    }
+
+    return profileState;
+  }
+
+  return {
+    status: async () => ({ kind: "managed", connected: true }),
+    listProfiles: async () => {
+      const knownProfiles = new Set<ProfileId>([DEFAULT_PROFILE_ID]);
+      for (const profileId of profileStates.keys()) {
+        knownProfiles.add(profileId);
+      }
+
+      return Array.from(knownProfiles).sort();
+    },
+    listTabs: async (profile) => {
+      const profileId = resolveProfileId(profile);
+      const profileState = profileStates.get(profileId);
+      return profileState === undefined ? [] : [...profileState.tabOrder];
+    },
+    openTab: async (url, profile) => {
+      const profileId = resolveProfileId(profile);
+      const profileState = getOrCreateProfileState(profileId);
+      const targetId = createTargetId(profileId, profileState.nextTargetNumber);
+
+      profileState.nextTargetNumber += 1;
+      profileState.tabs.set(targetId, { url });
+      profileState.tabOrder.push(targetId);
+      if (profileState.focusedTargetId === undefined) {
+        profileState.focusedTargetId = targetId;
+      }
+
+      return targetId;
+    },
+    focusTab: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const profileState = requireTargetInProfile(profileId, targetId);
+      profileState.focusedTargetId = targetId;
+    },
+    closeTab: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const profileState = requireTargetInProfile(profileId, targetId);
+
+      profileState.tabs.delete(targetId);
+      profileState.tabOrder = profileState.tabOrder.filter((existingTargetId) => existingTargetId !== targetId);
+      if (profileState.focusedTargetId === targetId) {
+        profileState.focusedTargetId = profileState.tabOrder[0];
+      }
+    },
+    snapshot: async (targetId, profile) => ({
+      kind: "managed",
+      profile: resolveProfileId(profile),
+      targetId,
+      hasTarget:
+        profileStates.get(resolveProfileId(profile))?.tabs.has(targetId) ?? false
+    }),
+    act: async (action, targetId, profile) => ({
+      actionType: action.type,
+      profile: resolveProfileId(profile),
+      targetId,
+      targetKnown:
+        profileStates.get(resolveProfileId(profile))?.tabs.has(targetId) ?? false,
+      ok: true
+    }),
+    armUpload: async () => {},
+    armDialog: async () => {},
+    waitDownload: async () => ({ path: "managed-download.bin" }),
+    triggerDownload: async () => {}
+  };
+}

package/packages/driver-managed/src/managed-local-driver.test.ts

@@ -0,0 +1,506 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createManagedLocalDriver,
+  type ManagedLocalBrowser,
+  type ManagedLocalBrowserContext,
+  type ManagedLocalDriverRuntime,
+  type ManagedLocalPage
+} from "./index";
+
+type MockPageRecord = {
+  page: ManagedLocalPage;
+  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: ManagedLocalDriverRuntime;
+  launch: ReturnType<typeof vi.fn>;
+  newContext: ReturnType<typeof vi.fn>;
+  browserClose: ReturnType<typeof vi.fn>;
+  contextClose: ReturnType<typeof vi.fn>;
+  pages: MockPageRecord[];
+};
+
+type RuntimeHarnessOptions = {
+  newContextDelayMs?: number;
+  supportsDownloadEvents?: boolean;
+};
+
+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 | 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;
+};
+
+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 eventListeners = listeners.get(eventName);
+    if (eventListeners !== undefined) {
+      eventListeners.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: ManagedLocalPage & { on: typeof on; waitForEvent: typeof waitForEvent } = {
+    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 newContextDelayMs = options.newContextDelayMs ?? 0;
+  const supportsDownloadEvents = options.supportsDownloadEvents ?? false;
+  const pages: MockPageRecord[] = [];
+  const contextClose = vi.fn(async () => {});
+  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 newContext = vi.fn(async (): Promise<ManagedLocalBrowserContext> => {
+    if (newContextDelayMs > 0) {
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, newContextDelayMs);
+      });
+    }
+
+    return {
+      newPage,
+      close: contextClose
+    };
+  });
+
+  const browserClose = vi.fn(async () => {});
+  const launch = vi.fn(async (): Promise<ManagedLocalBrowser> => ({
+    newContext,
+    close: browserClose
+  }));
+
+  return {
+    runtime: { launch },
+    launch,
+    newContext,
+    browserClose,
+    contextClose,
+    pages
+  };
+}
+
+describe("createManagedLocalDriver", () => {
+  it("does not launch a browser during status/list-only calls", async () => {
+    const harness = createRuntimeHarness();
+    const driver = createManagedLocalDriver({
+      runtime: harness.runtime,
+      browserName: "firefox",
+      headless: false,
+      channel: "firefox",
+      launchTimeoutMs: 4_000,
+      args: ["--private"]
+    });
+
+    expect(await driver.status()).toMatchObject({
+      kind: "managed-local",
+      launched: false,
+      browserName: "firefox",
+      headless: false
+    });
+    expect(await driver.listTabs()).toEqual([]);
+    expect(harness.launch).toHaveBeenCalledTimes(0);
+  });
+
+  it("lazily launches and supports tab lifecycle, snapshot, and actions", async () => {
+    const harness = createRuntimeHarness();
+    const driver = createManagedLocalDriver({
+      runtime: harness.runtime,
+      browserName: "webkit",
+      headless: true
+    });
+
+    const targetId = await driver.openTab("https://example.com/a");
+
+    expect(harness.launch).toHaveBeenCalledTimes(1);
+    expect(harness.launch).toHaveBeenCalledWith({
+      browserName: "webkit",
+      headless: true,
+      channel: undefined,
+      executablePath: undefined,
+      launchTimeoutMs: undefined,
+      args: []
+    });
+    expect(await driver.listTabs()).toEqual([targetId]);
+
+    await driver.focusTab(targetId);
+    expect(harness.pages[0]?.bringToFront).toHaveBeenCalledTimes(1);
+
+    const clickResult = await driver.act(
+      { type: "click", payload: { selector: "#go" } },
+      targetId
+    );
+    expect(clickResult).toMatchObject({
+      actionType: "click",
+      targetId,
+      targetKnown: true,
+      ok: true
+    });
+    expect(harness.pages[0]?.locator).toHaveBeenCalledWith("#go");
+    expect(harness.pages[0]?.locatorClick).toHaveBeenCalledTimes(1);
+
+    const snapshot = await driver.snapshot(targetId);
+    expect(snapshot).toEqual({
+      kind: "managed-local",
+      profile: "profile:managed-local:default",
+      targetId,
+      hasTarget: true,
+      url: "https://example.com/a",
+      title: "mock-title-1",
+      html: '<html data-page="1" />',
+      requestSummaries: []
+    });
+
+    await expect(driver.screenshot(targetId)).resolves.toEqual({
+      kind: "managed-local",
+      profile: "profile:managed-local:default",
+      targetId,
+      hasTarget: true,
+      mimeType: "image/png",
+      encoding: "base64",
+      imageBase64: "AAECAQ=="
+    });
+    expect(harness.pages[0]?.screenshot).toHaveBeenCalledTimes(1);
+
+    await driver.closeTab(targetId);
+    expect(harness.pages[0]?.close).toHaveBeenCalledTimes(1);
+    expect(await driver.listTabs()).toEqual([]);
+    await expect(driver.snapshot(targetId)).resolves.toMatchObject({
+      hasTarget: false
+    });
+    await expect(driver.screenshot(targetId)).resolves.toMatchObject({
+      hasTarget: false
+    });
+  });
+
+  it("collects console and network events and exposes response-body lookup", async () => {
+    const harness = createRuntimeHarness();
+    const driver = createManagedLocalDriver({ 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 to be created.");
+    }
+
+    await pageRecord.emitConsole({
+      type: () => "warning",
+      text: () => "managed-local warning",
+      location: () => ({
+        url: "https://example.com/app.js",
+        lineNumber: 7,
+        columnNumber: 2
+      })
+    });
+    await pageRecord.emitResponse({
+      url: () => "https://example.com/api/items",
+      status: () => 200,
+      request: () => ({
+        method: () => "GET",
+        resourceType: () => "xhr"
+      }),
+      text: async () => '{"ok":true}'
+    });
+
+    expect(pageRecord.on).toHaveBeenCalledWith("console", expect.any(Function));
+    expect(pageRecord.on).toHaveBeenCalledWith("response", expect.any(Function));
+
+    const telemetryDriver = driver as typeof driver & {
+      getConsoleEntries?: (targetId: string, profile?: string) => unknown[];
+      getNetworkResponseBody?: (
+        requestId: string,
+        targetId: string,
+        profile?: string
+      ) => { body: string; encoding: string } | undefined;
+    };
+    expect(telemetryDriver.getConsoleEntries).toBeTypeOf("function");
+    expect(telemetryDriver.getNetworkResponseBody).toBeTypeOf("function");
+
+    const consoleEntries = telemetryDriver.getConsoleEntries?.(targetId) ?? [];
+    expect(consoleEntries).toEqual([
+      expect.objectContaining({
+        type: "warning",
+        text: "managed-local warning",
+        location: {
+          url: "https://example.com/app.js",
+          lineNumber: 7,
+          columnNumber: 2
+        }
+      })
+    ]);
+
+    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
+        })
+      ]
+    });
+
+    const requestId = (
+      snapshot as {
+        requestSummaries?: Array<{ requestId?: string }>;
+      }
+    ).requestSummaries?.[0]?.requestId;
+    if (typeof requestId !== "string") {
+      throw new Error("Expected requestId in snapshot metadata.");
+    }
+
+    expect(telemetryDriver.getNetworkResponseBody?.(requestId, targetId)).toEqual({
+      body: '{"ok":true}',
+      encoding: "utf8"
+    });
+  });
+
+  it("keeps upload/dialog/download state scoped to profile + target", async () => {
+    const harness = createRuntimeHarness();
+    const driver = createManagedLocalDriver({ runtime: harness.runtime });
+    const profile = "profile:alpha";
+    const targetId = await driver.openTab("https://example.com/download", profile);
+
+    await expect(driver.armUpload(targetId, ["alpha.txt"], "profile:beta")).rejects.toThrowError(
+      `Unknown targetId: ${targetId} (profile: profile:beta)`
+    );
+
+    await driver.armUpload(targetId, ["alpha.txt"], profile);
+    await driver.armDialog(targetId, profile);
+    await driver.triggerDownload(targetId, profile);
+
+    await expect(driver.waitDownload(targetId, profile)).resolves.toMatchObject({
+      profile,
+      targetId,
+      uploadFiles: ["alpha.txt"],
+      dialogArmedCount: 1,
+      triggerCount: 1
+    });
+  });
+
+  it("supports real upload/dialog/download hooks when runtime exposes events", async () => {
+    const harness = createRuntimeHarness({
+      supportsDownloadEvents: true
+    });
+    const driver = createManagedLocalDriver({
+      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
+    });
+  });
+
+  it("reuses one browser launch while creating separate profile contexts", async () => {
+    const harness = createRuntimeHarness();
+    const driver = createManagedLocalDriver({ runtime: harness.runtime });
+
+    await driver.openTab("https://example.com/alpha", "profile:alpha");
+    await driver.openTab("https://example.com/beta", "profile:beta");
+
+    expect(harness.launch).toHaveBeenCalledTimes(1);
+    expect(harness.newContext).toHaveBeenCalledTimes(2);
+  });
+
+  it("serializes same-profile context init during concurrent openTab calls", async () => {
+    const harness = createRuntimeHarness({ newContextDelayMs: 15 });
+    const driver = createManagedLocalDriver({ runtime: harness.runtime });
+
+    const [firstTarget, secondTarget] = await Promise.all([
+      driver.openTab("https://example.com/concurrent/a", "profile:alpha"),
+      driver.openTab("https://example.com/concurrent/b", "profile:alpha")
+    ]);
+
+    const tabs = await driver.listTabs("profile:alpha");
+    expect(tabs).toHaveLength(2);
+    expect(new Set(tabs)).toEqual(new Set([firstTarget, secondTarget]));
+    expect(harness.launch).toHaveBeenCalledTimes(1);
+    expect(harness.newContext).toHaveBeenCalledTimes(1);
+  });
+});