@flrande/browserctl 0.4.0 → 0.5.0

package/packages/core/src/session-store.ts

@@ -4,30 +4,135 @@ function createEmptySession(sessionId: SessionId): SessionState {
   return { sessionId };
 }
 
+type SessionStoreOptions = {
+  ttlMs?: number;
+  now?: () => number;
+};
+
+type SessionEntry = {
+  state: SessionState;
+  touchedAt: number;
+};
+
+export type SessionSnapshot = {
+  state: SessionState;
+  touchedAt: number;
+};
+
 export class SessionStore {
-  private readonly sessions = new Map<SessionId, SessionState>();
+  private readonly sessions = new Map<SessionId, SessionEntry>();
+  private readonly ttlMs: number;
+  private readonly now: () => number;
+
+  constructor(options: SessionStoreOptions = {}) {
+    this.ttlMs = options.ttlMs === undefined ? 0 : Math.max(0, Math.trunc(options.ttlMs));
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  private isExpired(entry: SessionEntry, now: number): boolean {
+    return this.ttlMs > 0 && now - entry.touchedAt > this.ttlMs;
+  }
+
+  private readActiveEntry(sessionId: SessionId, touch = false): SessionEntry | undefined {
+    const existing = this.sessions.get(sessionId);
+    if (existing === undefined) {
+      return undefined;
+    }
+
+    const currentTime = this.now();
+    if (this.isExpired(existing, currentTime)) {
+      this.sessions.delete(sessionId);
+      return undefined;
+    }
+
+    if (touch) {
+      const touchedEntry: SessionEntry = {
+        state: existing.state,
+        touchedAt: currentTime
+      };
+      this.sessions.set(sessionId, touchedEntry);
+      return touchedEntry;
+    }
+
+    return existing;
+  }
 
   get(sessionId: SessionId): SessionState | undefined {
-    return this.sessions.get(sessionId);
+    return this.readActiveEntry(sessionId)?.state;
   }
 
   useProfile(sessionId: SessionId, profile: ProfileId): SessionState {
-    const current = this.sessions.get(sessionId) ?? createEmptySession(sessionId);
+    const current = this.readActiveEntry(sessionId, true)?.state ?? createEmptySession(sessionId);
     const next = { ...current, profile };
 
-    this.sessions.set(sessionId, next);
+    this.sessions.set(sessionId, {
+      state: next,
+      touchedAt: this.now()
+    });
     return next;
   }
 
   useTarget(sessionId: SessionId, targetId: TargetId): SessionState {
-    const current = this.sessions.get(sessionId) ?? createEmptySession(sessionId);
+    const current = this.readActiveEntry(sessionId, true)?.state ?? createEmptySession(sessionId);
     const next = { ...current, targetId };
 
-    this.sessions.set(sessionId, next);
+    this.sessions.set(sessionId, {
+      state: next,
+      touchedAt: this.now()
+    });
     return next;
   }
 
   delete(sessionId: SessionId): boolean {
     return this.sessions.delete(sessionId);
   }
+
+  cleanupExpired(): number {
+    if (this.ttlMs <= 0 || this.sessions.size === 0) {
+      return 0;
+    }
+
+    const currentTime = this.now();
+    let removedCount = 0;
+    for (const [sessionId, entry] of this.sessions.entries()) {
+      if (!this.isExpired(entry, currentTime)) {
+        continue;
+      }
+
+      this.sessions.delete(sessionId);
+      removedCount += 1;
+    }
+
+    return removedCount;
+  }
+
+  has(sessionId: SessionId): boolean {
+    return this.readActiveEntry(sessionId) !== undefined;
+  }
+
+  listSnapshots(): SessionSnapshot[] {
+    const snapshots: SessionSnapshot[] = [];
+    const currentTime = this.now();
+    for (const [sessionId, entry] of this.sessions.entries()) {
+      if (this.isExpired(entry, currentTime)) {
+        this.sessions.delete(sessionId);
+        continue;
+      }
+
+      snapshots.push({
+        state: entry.state,
+        touchedAt: entry.touchedAt
+      });
+    }
+
+    return snapshots;
+  }
+
+  list(): SessionState[] {
+    return this.listSnapshots().map((snapshot) => snapshot.state);
+  }
+
+  size(): number {
+    return this.listSnapshots().length;
+  }
 }

package/packages/driver-chrome-relay/src/chrome-relay-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>;
@@ -132,6 +136,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);
@@ -178,6 +184,8 @@ function createMockPageRecord(pageNumber: number): MockPageRecord {
     content,
     screenshot,
     locator,
+    route,
+    unroute,
     on,
     waitForEvent,
     keyboard: {
@@ -199,6 +207,8 @@ function createMockPageRecord(pageNumber: number): MockPageRecord {
     locatorType,
     locatorSetInputFiles,
     keyboardPress,
+    route,
+    unroute,
     waitForEvent,
     on,
     emitConsole: async (entry) => {
@@ -433,6 +443,71 @@ describe("createChromeRelayDriver", () => {
     expect(pageRecord.keyboardPress).toHaveBeenCalledWith("Enter");
   });
 
+  it("supports network mock add/clear actions when runtime exposes route controls", async () => {
+    const harness = createRuntimeHarness();
+    const driver = createChromeRelayDriver({
+      relayUrl: "ws://127.0.0.1:9333/devtools/browser/relay",
+      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 = createChromeRelayDriver({
@@ -614,15 +689,19 @@ describe("createChromeRelayDriver", () => {
     });
     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",
@@ -630,5 +709,36 @@ describe("createChromeRelayDriver", () => {
       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 = createChromeRelayDriver({
+      relayUrl: "ws://127.0.0.1:9333/devtools/browser/relay",
+      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");
   });
 });

package/packages/driver-chrome-relay/src/chrome-relay-driver.ts

@@ -97,6 +97,8 @@ export type ChromeRelayPage = {
   frameSnapshot?(frameId: string): Promise<unknown>;
   scroll?(deltaX?: number, deltaY?: number): Promise<unknown>;
   locator(selector: string): ChromeRelayLocator;
+  route?(url: string, handler: ChromeRelayNetworkMockHandler): Promise<void>;
+  unroute?(url: string, handler?: ChromeRelayNetworkMockHandler): Promise<void>;
   keyboard?: ChromeRelayKeyboard;
   on?(eventName: string, listener: (payload: unknown) => unknown): void;
 };
@@ -149,8 +151,12 @@ type ChromeRelayTargetOperationState = {
   uploadFiles: string[];
   dialogArmedCount: number;
   triggerCount: number;
+  nextNetworkMockNumber: number;
+  networkMocks: Map<string, ChromeRelayNetworkMockBinding>;
+  requestedDownloadPath?: string;
   downloadInFlight?: Promise<ChromeRelayDownloadArtifact>;
   latestDownload?: ChromeRelayDownloadArtifact;
+  latestRawDownload?: unknown;
 };
 
 type ChromeRelayDownloadArtifact = {
@@ -160,6 +166,12 @@ type ChromeRelayDownloadArtifact = {
   mimeType?: string;
 };
 
+type ChromeRelayNetworkMockHandler = (...args: unknown[]) => Promise<void>;
+type ChromeRelayNetworkMockBinding = {
+  urlPattern: string;
+  handler: ChromeRelayNetworkMockHandler;
+};
+
 type ChromeRelayTargetTelemetryState = {
   consoleEntries: ChromeRelayConsoleEntry[];
   requestSummaries: ChromeRelayNetworkRequestSummary[];
@@ -187,7 +199,9 @@ function createTargetOperationState(): ChromeRelayTargetOperationState {
   return {
     uploadFiles: [],
     dialogArmedCount: 0,
-    triggerCount: 0
+    triggerCount: 0,
+    nextNetworkMockNumber: 1,
+    networkMocks: new Map<string, ChromeRelayNetworkMockBinding>()
   };
 }
 
@@ -988,21 +1002,26 @@ export function createChromeRelayDriver(
     profileId: ProfileId,
     targetId: TargetId,
     tab: ChromeRelayTab,
-    operationState: ChromeRelayTargetOperationState
+    operationState: ChromeRelayTargetOperationState,
+    requestedPath?: string
   ): Promise<ChromeRelayDownloadArtifact> {
+    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: ChromeRelayDownloadArtifact = { path: fallbackPath };
+      operationState.requestedDownloadPath = undefined;
       operationState.latestDownload = artifact;
+      operationState.latestRawDownload = undefined;
       const resolved = Promise.resolve(artifact);
       operationState.downloadInFlight = resolved;
       return resolved;
@@ -1010,8 +1029,13 @@ export function createChromeRelayDriver(
 
     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) {
@@ -1023,6 +1047,30 @@ export function createChromeRelayDriver(
     return inFlight;
   }
 
+  async function resolveDownloadArtifactPath(
+    operationState: ChromeRelayTargetOperationState,
+    artifact: ChromeRelayDownloadArtifact,
+    requestedPath?: string
+  ): Promise<ChromeRelayDownloadArtifact> {
+    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 () => {
       const runtimeConnected = await readRuntimeConnectionStatus(runtime);
@@ -1324,7 +1372,142 @@ export function createChromeRelayDriver(
                 : {
                     deltaX,
                     deltaY
+                }
+            };
+          }
+          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: ChromeRelayNetworkMockHandler = 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": {
@@ -2166,11 +2349,48 @@ export function createChromeRelayDriver(
       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,
+          relayUrl,
+          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,
@@ -2192,6 +2412,9 @@ export function createChromeRelayDriver(
       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) => {