@flrande/browserctl 0.4.0-dev.15.1 → 0.5.0-dev.19.1

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

@@ -115,6 +115,8 @@ export type ManagedLocalPage = {
   content(): Promise<string>;
   screenshot?(options?: Record<string, unknown>): Promise<unknown>;
   locator(selector: string): ManagedLocalLocator;
+  route?(url: string, handler: ManagedLocalNetworkMockHandler): Promise<void>;
+  unroute?(url: string, handler?: ManagedLocalNetworkMockHandler): Promise<void>;
   keyboard?: ManagedLocalKeyboard;
   on?(eventName: string, listener: (payload: unknown) => unknown): void;
 };
@@ -154,8 +156,12 @@ type ManagedLocalTargetOperationState = {
   uploadFiles: string[];
   dialogArmedCount: number;
   triggerCount: number;
+  nextNetworkMockNumber: number;
+  networkMocks: Map<string, ManagedLocalNetworkMockBinding>;
+  requestedDownloadPath?: string;
   downloadInFlight?: Promise<ManagedLocalDownloadArtifact>;
   latestDownload?: ManagedLocalDownloadArtifact;
+  latestRawDownload?: unknown;
 };
 
 type ManagedLocalDownloadArtifact = {
@@ -165,6 +171,12 @@ type ManagedLocalDownloadArtifact = {
   mimeType?: string;
 };
 
+type ManagedLocalNetworkMockHandler = (...args: unknown[]) => Promise<void>;
+type ManagedLocalNetworkMockBinding = {
+  urlPattern: string;
+  handler: ManagedLocalNetworkMockHandler;
+};
+
 type ManagedLocalTargetTelemetryState = {
   consoleEntries: ManagedLocalConsoleEntry[];
   requestSummaries: ManagedLocalNetworkRequestSummary[];
@@ -192,7 +204,9 @@ function createTargetOperationState(): ManagedLocalTargetOperationState {
   return {
     uploadFiles: [],
     dialogArmedCount: 0,
-    triggerCount: 0
+    triggerCount: 0,
+    nextNetworkMockNumber: 1,
+    networkMocks: new Map<string, ManagedLocalNetworkMockBinding>()
   };
 }
 
@@ -889,21 +903,26 @@ export function createManagedLocalDriver(
     profileId: ProfileId,
     targetId: TargetId,
     tab: ManagedLocalTab,
-    operationState: ManagedLocalTargetOperationState
+    operationState: ManagedLocalTargetOperationState,
+    requestedPath?: string
   ): Promise<ManagedLocalDownloadArtifact> {
+    if (requestedPath !== undefined) {
+      operationState.requestedDownloadPath = requestedPath;
+    }
+
     if (operationState.downloadInFlight !== undefined) {
       return operationState.downloadInFlight;
     }
 
-    const fallbackPath = createDownloadPath(
-      profileId,
-      targetId,
-      Math.max(operationState.triggerCount, 1)
-    );
+    const fallbackPath =
+      operationState.requestedDownloadPath ??
+      createDownloadPath(profileId, targetId, Math.max(operationState.triggerCount, 1));
     const waitForEventMethod = getObjectMethod(tab.page, "waitForEvent");
     if (typeof waitForEventMethod !== "function") {
       const artifact: ManagedLocalDownloadArtifact = { path: fallbackPath };
+      operationState.requestedDownloadPath = undefined;
       operationState.latestDownload = artifact;
+      operationState.latestRawDownload = undefined;
       const resolved = Promise.resolve(artifact);
       operationState.downloadInFlight = resolved;
       return resolved;
@@ -911,8 +930,13 @@ export function createManagedLocalDriver(
 
     const inFlight = (async () => {
       const rawDownload = await waitForEventMethod.call(tab.page, "download");
-      const artifact = await readDownloadArtifact(rawDownload, fallbackPath);
+      operationState.latestRawDownload = rawDownload;
+      const persistedPath =
+        operationState.requestedDownloadPath ??
+        createDownloadPath(profileId, targetId, Math.max(operationState.triggerCount, 1));
+      const artifact = await readDownloadArtifact(rawDownload, persistedPath);
       operationState.latestDownload = artifact;
+      operationState.requestedDownloadPath = undefined;
       return artifact;
     })().finally(() => {
       if (operationState.downloadInFlight === inFlight) {
@@ -924,6 +948,30 @@ export function createManagedLocalDriver(
     return inFlight;
   }
 
+  async function resolveDownloadArtifactPath(
+    operationState: ManagedLocalTargetOperationState,
+    artifact: ManagedLocalDownloadArtifact,
+    requestedPath?: string
+  ): Promise<ManagedLocalDownloadArtifact> {
+    if (requestedPath === undefined || requestedPath.trim().length === 0 || artifact.path === requestedPath) {
+      return artifact;
+    }
+
+    const failurePrefix = `Failed to persist download to requested path: ${requestedPath}`;
+    const saveAsMethod = getObjectMethod(operationState.latestRawDownload, "saveAs");
+    if (typeof saveAsMethod !== "function") {
+      throw new Error(failurePrefix);
+    }
+
+    try {
+      await saveAsMethod.call(operationState.latestRawDownload, requestedPath);
+      return { ...artifact, path: requestedPath };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(message.length > 0 ? `${failurePrefix} (${message})` : failurePrefix);
+    }
+  }
+
   return {
     status: async () => ({
       kind: "managed-local",
@@ -1167,6 +1215,141 @@ export function createManagedLocalDriver(
             await tab.page.keyboard.press(key);
             return { ok: true, executed: true };
           }
+          case "networkMockAdd": {
+            const urlPattern = readActionPayloadString(payload, "urlPattern");
+            if (urlPattern === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.urlPattern is required for networkMockAdd action."
+              };
+            }
+
+            const routeMethod = getObjectMethod(tab.page, "route");
+            if (typeof routeMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const methodFilter = readActionPayloadString(payload, "method")?.toUpperCase();
+            const status = readActionPayloadNumber(payload, "status") ?? 200;
+            if (!Number.isInteger(status) || status < 100 || status > 599) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.status must be an integer between 100 and 599 for networkMockAdd action."
+              };
+            }
+            const body = readActionPayloadString(payload, "body") ?? "";
+            const contentType = readActionPayloadString(payload, "contentType") ?? "text/plain";
+            const mockId = `mock:${operationState.nextNetworkMockNumber}`;
+            operationState.nextNetworkMockNumber += 1;
+            const handler: ManagedLocalNetworkMockHandler = async (...args) => {
+              const route = args[0];
+              const explicitRequest = args[1];
+              const request = explicitRequest ?? readObjectMethod<unknown>(route, "request");
+              if (methodFilter !== undefined) {
+                const requestMethod = readObjectMethod<string>(request, "method");
+                if (requestMethod?.toUpperCase() !== methodFilter) {
+                  const continueMethod = getObjectMethod(route, "continue");
+                  if (typeof continueMethod === "function") {
+                    await continueMethod.call(route);
+                    return;
+                  }
+
+                  const fallbackMethod = getObjectMethod(route, "fallback");
+                  if (typeof fallbackMethod === "function") {
+                    await fallbackMethod.call(route);
+                    return;
+                  }
+
+                  return;
+                }
+              }
+
+              const fulfillMethod = getObjectMethod(route, "fulfill");
+              if (typeof fulfillMethod !== "function") {
+                return;
+              }
+
+              await fulfillMethod.call(route, {
+                status,
+                body,
+                headers: {
+                  "content-type": contentType
+                }
+              });
+            };
+
+            await routeMethod.call(tab.page, urlPattern, handler);
+            operationState.networkMocks.set(mockId, {
+              urlPattern,
+              handler
+            });
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                mockId,
+                urlPattern,
+                ...(methodFilter !== undefined ? { method: methodFilter } : {}),
+                status
+              }
+            };
+          }
+          case "networkMockClear": {
+            const unrouteMethod = getObjectMethod(tab.page, "unroute");
+            if (typeof unrouteMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const mockId = readActionPayloadString(payload, "mockId");
+            if (mockId !== undefined) {
+              const binding = operationState.networkMocks.get(mockId);
+              if (binding === undefined) {
+                return {
+                  ok: false,
+                  executed: false,
+                  error: `Unknown network mock id: ${mockId}`
+                };
+              }
+
+              await unrouteMethod.call(tab.page, binding.urlPattern, binding.handler);
+              operationState.networkMocks.delete(mockId);
+              return {
+                ok: true,
+                executed: true,
+                data: {
+                  cleared: 1,
+                  mockId
+                }
+              };
+            }
+
+            let cleared = 0;
+            for (const [registeredId, binding] of operationState.networkMocks.entries()) {
+              try {
+                await unrouteMethod.call(tab.page, binding.urlPattern, binding.handler);
+              } catch {
+                // Ignore per-route cleanup failures.
+              }
+              operationState.networkMocks.delete(registeredId);
+              cleared += 1;
+            }
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                cleared
+              }
+            };
+          }
           case "domQuery": {
             const selector = readActionPayloadString(payload, "selector");
             if (selector === undefined) {
@@ -1982,11 +2165,47 @@ export function createManagedLocalDriver(
       const operationState = getOrCreateTargetOperationState(profileId, targetId);
       operationState.dialogArmedCount += 1;
     },
-    waitDownload: async (targetId, profile) => {
+    waitDownload: async (targetId, profile, path) => {
       const profileId = resolveProfileId(profile);
       const { tab } = requireTargetInProfile(profileId, targetId);
       const operationState = getOrCreateTargetOperationState(profileId, targetId);
-      const download = await ensureDownloadInFlight(profileId, targetId, tab, operationState);
+      const requestedPath = path !== undefined && path.trim().length > 0 ? path : undefined;
+      if (operationState.downloadInFlight === undefined && operationState.latestDownload !== undefined) {
+        const download = await resolveDownloadArtifactPath(
+          operationState,
+          { ...operationState.latestDownload },
+          requestedPath
+        );
+
+        operationState.latestDownload = undefined;
+        operationState.latestRawDownload = undefined;
+        operationState.requestedDownloadPath = undefined;
+        return {
+          path: download.path,
+          profile: profileId,
+          targetId,
+          uploadFiles: [...operationState.uploadFiles],
+          dialogArmedCount: operationState.dialogArmedCount,
+          triggerCount: operationState.triggerCount,
+          ...(download.suggestedFilename !== undefined
+            ? { suggestedFilename: download.suggestedFilename }
+            : {}),
+          ...(download.url !== undefined ? { url: download.url } : {}),
+          ...(download.mimeType !== undefined ? { mimeType: download.mimeType } : {})
+        };
+      }
+
+      const inFlightDownload = await ensureDownloadInFlight(
+        profileId,
+        targetId,
+        tab,
+        operationState,
+        requestedPath
+      );
+      const download = await resolveDownloadArtifactPath(operationState, inFlightDownload, requestedPath);
+      operationState.latestDownload = undefined;
+      operationState.latestRawDownload = undefined;
+      operationState.requestedDownloadPath = undefined;
 
       return {
         path: download.path,
@@ -2007,6 +2226,9 @@ export function createManagedLocalDriver(
       const { tab } = requireTargetInProfile(profileId, targetId);
       const operationState = getOrCreateTargetOperationState(profileId, targetId);
       operationState.triggerCount += 1;
+      operationState.latestDownload = undefined;
+      operationState.latestRawDownload = undefined;
+      operationState.requestedDownloadPath = undefined;
       void ensureDownloadInFlight(profileId, targetId, tab, operationState);
     },
     getConsoleEntries: (targetId, profile) => {

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

@@ -50,6 +50,8 @@ type MockPage = {
     type(value: string): Promise<void>;
     setInputFiles?(files: string[]): Promise<void>;
   };
+  route?(url: string, handler: (...args: unknown[]) => Promise<void>): Promise<void>;
+  unroute?(url: string, handler?: (...args: unknown[]) => Promise<void>): Promise<void>;
   keyboard?: {
     press(key: string): Promise<void>;
   };
@@ -71,6 +73,8 @@ type MockPageRecord = {
   locatorType: ReturnType<typeof vi.fn>;
   locatorSetInputFiles: ReturnType<typeof vi.fn>;
   keyboardPress: ReturnType<typeof vi.fn>;
+  route: ReturnType<typeof vi.fn>;
+  unroute: ReturnType<typeof vi.fn>;
   waitForEvent: ReturnType<typeof vi.fn>;
   on: ReturnType<typeof vi.fn>;
   emitConsole(entry: MockConsoleMessage): Promise<void>;
@@ -125,6 +129,8 @@ function createMockPageRecord(pageNumber: number): MockPageRecord {
     setInputFiles: locatorSetInputFiles
   }));
   const keyboardPress = vi.fn(async (_key: string) => {});
+  const route = vi.fn(async (_url: string, _handler: (...args: unknown[]) => Promise<void>) => {});
+  const unroute = vi.fn(async (_url: string, _handler?: (...args: unknown[]) => Promise<void>) => {});
   const waitForEvent = vi.fn(async (eventName: string) => {
     return await new Promise<unknown>((resolve, reject) => {
       const current = waiters.get(eventName);
@@ -171,6 +177,8 @@ function createMockPageRecord(pageNumber: number): MockPageRecord {
     content,
     screenshot,
     locator,
+    route,
+    unroute,
     on,
     waitForEvent,
     keyboard: {
@@ -192,6 +200,8 @@ function createMockPageRecord(pageNumber: number): MockPageRecord {
     locatorType,
     locatorSetInputFiles,
     keyboardPress,
+    route,
+    unroute,
     waitForEvent,
     on,
     emitConsole: async (entry) => {
@@ -408,6 +418,71 @@ describe("createRemoteCdpDriver", () => {
     expect(pageRecord.keyboardPress).toHaveBeenCalledWith("Enter");
   });
 
+  it("supports network mock add/clear actions when runtime exposes route controls", 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/mock", profile);
+    const pageRecord = harness.pages[0];
+    if (pageRecord === undefined) {
+      throw new Error("Expected a mock page record.");
+    }
+
+    const addResult = await driver.act(
+      {
+        type: "networkMockAdd",
+        payload: {
+          urlPattern: "**/api/**",
+          method: "POST",
+          status: 201,
+          body: '{"ok":true}',
+          contentType: "application/json"
+        }
+      },
+      targetId,
+      profile
+    );
+    expect(addResult).toMatchObject({
+      ok: true,
+      executed: true,
+      data: {
+        mockId: expect.any(String),
+        urlPattern: "**/api/**",
+        method: "POST",
+        status: 201
+      }
+    });
+    expect(pageRecord.route).toHaveBeenCalledWith("**/api/**", expect.any(Function));
+
+    const mockId = (addResult as { data?: { mockId?: string } }).data?.mockId;
+    if (typeof mockId !== "string") {
+      throw new Error("Expected mockId from networkMockAdd action.");
+    }
+
+    const clearResult = await driver.act(
+      {
+        type: "networkMockClear",
+        payload: {
+          mockId
+        }
+      },
+      targetId,
+      profile
+    );
+    expect(clearResult).toMatchObject({
+      ok: true,
+      executed: true,
+      data: {
+        cleared: 1,
+        mockId
+      }
+    });
+    expect(pageRecord.unroute).toHaveBeenCalledWith("**/api/**", expect.any(Function));
+  });
+
   it("captures console + network telemetry and supports request body lookup", async () => {
     const harness = createRuntimeHarness();
     const driver = createRemoteCdpDriver({
@@ -597,15 +672,19 @@ describe("createRemoteCdpDriver", () => {
     });
     expect(dialogAccept).toHaveBeenCalledTimes(1);
 
+    const saveAs = vi.fn(async (_path: string) => {});
     await driver.triggerDownload(targetId, profile);
     await pageRecord.emitDownload({
       path: async () => "C:\\downloads\\alpha.bin",
+      saveAs,
       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",
+    await expect(
+      driver.waitDownload(targetId, profile, "C:\\downloads\\saved-alpha.bin")
+    ).resolves.toMatchObject({
+      path: "C:\\downloads\\saved-alpha.bin",
       profile,
       targetId,
       suggestedFilename: "alpha.bin",
@@ -613,5 +692,36 @@ describe("createRemoteCdpDriver", () => {
       mimeType: "application/octet-stream",
       triggerCount: 1
     });
+    expect(saveAs).toHaveBeenCalledWith("C:\\downloads\\saved-alpha.bin");
+  });
+
+  it("fails waitDownload when requested path cannot be persisted", 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.triggerDownload(targetId, profile);
+    const saveAs = vi.fn(async () => {
+      throw new Error("permission denied");
+    });
+    await pageRecord.emitDownload({
+      path: async () => "C:\\downloads\\alpha.bin",
+      saveAs
+    });
+
+    await expect(
+      driver.waitDownload(targetId, profile, "C:\\downloads\\saved-alpha.bin")
+    ).rejects.toThrow("Failed to persist download to requested path");
+    expect(saveAs).toHaveBeenCalledWith("C:\\downloads\\saved-alpha.bin");
   });
 });