browser-debugger-cli 0.8.0 → 0.9.0

package/dist/daemon/session/interactions.js

@@ -1,12 +1,22 @@
 /**
  * Running page interactions (fill, click, submit, pressKey, scroll) one at a
- * time, reporting the dialogs they caused.
+ * time, reporting the dialogs, network requests and page changes they caused.
  */
+import { watchActionEffects } from '../../runtime/dom/actionEffects.js';
+import { UNBIND_TARGET_SCRIPT } from '../../runtime/dom/targetNode.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { getErrorMessage } from '../../utils/errors.js';
+import { watchTriggeredRequests } from './triggeredRequests.js';
 const log = createLogger('dom');
-/** Removes the node bound for index-based commands from the page */
-const UNBIND_TARGET_SCRIPT = 'delete window.__bdgTarget';
+/**
+ * Whether an action result is a success (results without a `success` flag are).
+ *
+ * @param result - Action result
+ * @returns False for `{ success: false }`
+ */
+function succeeded(result) {
+    return !('success' in result) || result.success !== false;
+}
 /**
  * Create the runner for a session's interactions.
  *
@@ -14,24 +24,41 @@ const UNBIND_TARGET_SCRIPT = 'delete window.__bdgTarget';
  * commands would interleave keystrokes into each other's field, so they are
  * queued. After each one, the bound target (`window.__bdgTarget`) is removed
  * from the page (without waiting: during a pending navigation that takes until
- * the new page commits), and the dialogs it opened are added to its result.
- * Dialogs are attributed by time: one opened by a page timer or a navigation
- * started earlier is reported by whichever interaction is running then.
+ * the new page commits), and the dialogs it opened, what it changed on the
+ * page (see {@link watchActionEffects}) and the network requests it
+ * triggered (see {@link watchTriggeredRequests}) are added to its result.
+ * They are attributed by time: a dialog or request started by a page timer
+ * or a navigation started earlier is reported by whichever interaction is
+ * running then.
  *
- * @param store - Session store recording accepted dialogs
+ * @param store - Session store recording accepted dialogs and network requests
  * @returns Interaction runner
  */
 export function createInteractionRunner(store) {
     let queue = Promise.resolve();
-    return (cdp, action) => {
+    return (cdp, action, options = {}) => {
         const run = queue.then(async () => {
             const firstDialog = store.dialogs.length;
+            const collectRequests = options.reportRequests === false ? undefined : watchTriggeredRequests(store);
+            const effects = options.reportEffects === false ? undefined : watchActionEffects(cdp);
             try {
                 const result = await action();
                 const dialogs = store.dialogs.slice(firstDialog);
-                return dialogs.length > 0 ? { ...result, dialogs } : result;
+                const changes = succeeded(result)
+                    ? await effects?.collect({
+                        dialogs: dialogs.length,
+                        detectNoEffect: options.detectNoEffect === true,
+                    })
+                    : undefined;
+                return {
+                    ...result,
+                    ...(dialogs.length > 0 && { dialogs }),
+                    ...changes,
+                    ...(succeeded(result) && collectRequests?.()),
+                };
             }
             finally {
+                effects?.dispose();
                 void cdp
                     .send('Runtime.evaluate', { expression: UNBIND_TARGET_SCRIPT })
                     .catch((error) => log.debug(`Target not unbound: ${getErrorMessage(error)}`));

package/dist/daemon/session/triggeredRequests.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Network requests an interaction triggered, read from the session's network
+ * telemetry (no CDP listeners of its own).
+ */
+import type { TelemetryStore } from './TelemetryStore.js';
+import type { TriggeredRequest } from '../../ipc/protocol/domTypes.js';
+import type { NetworkRequest } from '../../types.js';
+/**
+ * Requests listed in a result (a click that loads a page triggers its whole
+ * load); notable ones ({@link isNotableRequest}) are kept before assets
+ */
+export declare const MAX_TRIGGERED_REQUESTS = 50;
+/** Requests started since the watch began: the first ones, and how many more there were */
+export interface CollectedRequests {
+    triggeredRequests: TriggeredRequest[];
+    triggeredRequestsOmitted?: number;
+}
+/** Lists the requests started since the watch began */
+export type TriggeredRequestsCollector = () => CollectedRequests | undefined;
+/**
+ * Start attributing requests to an interaction.
+ *
+ * Requests are attributed by time: every request (and WebSocket connection)
+ * bdg saw start between this call and the collector's call belongs to the
+ * interaction, including one a page timer or poller happened to start
+ * meanwhile. Collecting adds no wait: requests
+ * still running then are reported as pending.
+ *
+ * @param store - Session store holding the network telemetry
+ * @returns Collector (at most {@link MAX_TRIGGERED_REQUESTS} requests, plus how
+ *   many more there were); it returns undefined when network telemetry is off
+ */
+export declare function watchTriggeredRequests(store: TelemetryStore): TriggeredRequestsCollector;
+/**
+ * At most `limit` requests, notable ones first (pages, API calls, sockets,
+ * failures), then assets, still in start order.
+ *
+ * @param requests - Requests in start order
+ * @param limit - How many to keep
+ * @returns Kept requests, in start order
+ */
+export declare function keepNotableFirst(requests: TriggeredRequest[], limit: number): TriggeredRequest[];
+/**
+ * Count a submission's network requests as its request list does (the
+ * submit watcher counts every request id CDP reported until the wait ended:
+ * `data:` URLs and preflights included, a redirect chain once), so
+ * `networkRequests`, the listed requests and JSON agree. Without network
+ * telemetry the watcher's count stays.
+ *
+ * @param result - Submit result with the requests it triggered
+ * @returns The result, `networkRequests` matching `triggeredRequests`
+ */
+export declare function withTriggeredRequestCount<T extends {
+    networkRequests?: number | undefined;
+    triggeredRequests?: TriggeredRequest[] | undefined;
+    triggeredRequestsOmitted?: number | undefined;
+}>(result: T): T;
+/**
+ * Summarize a captured request.
+ *
+ * @param request - Captured request
+ * @param inFlight - Whether it was still in flight (a request with a response
+ *   is then still loading its body: a stream, a slow download)
+ * @returns Triggered request entry
+ */
+export declare function toTriggeredRequest(request: NetworkRequest, inFlight?: boolean): TriggeredRequest;
+//# sourceMappingURL=triggeredRequests.d.ts.map

package/dist/daemon/session/triggeredRequests.js

@@ -0,0 +1,157 @@
+/**
+ * Network requests an interaction triggered, read from the session's network
+ * telemetry (no CDP listeners of its own).
+ */
+import { isNotableRequest } from '../../telemetry/requestKinds.js';
+import { failureReason, getRequestState } from '../../telemetry/requestState.js';
+/** URLs that never reach the network (inline data, in-page objects) */
+const LOCAL_URL_PATTERN = /^(data|blob):/i;
+/**
+ * Requests listed in a result (a click that loads a page triggers its whole
+ * load); notable ones ({@link isNotableRequest}) are kept before assets
+ */
+export const MAX_TRIGGERED_REQUESTS = 50;
+/**
+ * Start attributing requests to an interaction.
+ *
+ * Requests are attributed by time: every request (and WebSocket connection)
+ * bdg saw start between this call and the collector's call belongs to the
+ * interaction, including one a page timer or poller happened to start
+ * meanwhile. Collecting adds no wait: requests
+ * still running then are reported as pending.
+ *
+ * @param store - Session store holding the network telemetry
+ * @returns Collector (at most {@link MAX_TRIGGERED_REQUESTS} requests, plus how
+ *   many more there were); it returns undefined when network telemetry is off
+ */
+export function watchTriggeredRequests(store) {
+    if (!store.activeTelemetry.includes('network'))
+        return () => undefined;
+    const startedAt = Date.now();
+    const firstFinished = store.networkRequests.length;
+    const firstWebSocket = store.websocketConnections.length;
+    return () => {
+        const started = [
+            ...store.networkRequests.slice(firstFinished).map((request) => ({ request })),
+            ...[...store.pendingNetworkRequests.values()].map((pending) => ({
+                request: pending.request,
+                inFlight: true,
+            })),
+            ...store.websocketConnections
+                .slice(firstWebSocket)
+                .map((connection) => ({ request: webSocketAsRequest(connection) })),
+        ]
+            .filter(({ request }) => request.timestamp >= startedAt && isReportable(request))
+            .sort((a, b) => byStartTime(a.request, b.request));
+        const triggered = started.map(({ request, inFlight }) => toTriggeredRequest(request, inFlight));
+        const kept = keepNotableFirst(triggered, MAX_TRIGGERED_REQUESTS);
+        const omitted = triggered.length - kept.length;
+        return {
+            triggeredRequests: kept,
+            ...(omitted > 0 && { triggeredRequestsOmitted: omitted }),
+        };
+    };
+}
+/**
+ * At most `limit` requests, notable ones first (pages, API calls, sockets,
+ * failures), then assets, still in start order.
+ *
+ * @param requests - Requests in start order
+ * @param limit - How many to keep
+ * @returns Kept requests, in start order
+ */
+export function keepNotableFirst(requests, limit) {
+    if (requests.length <= limit)
+        return requests;
+    const notable = requests.filter(isNotableRequest).slice(0, limit);
+    const assets = requests
+        .filter((request) => !isNotableRequest(request))
+        .slice(0, limit - notable.length);
+    const kept = new Set([...notable, ...assets]);
+    return requests.filter((request) => kept.has(request));
+}
+/**
+ * Count a submission's network requests as its request list does (the
+ * submit watcher counts every request id CDP reported until the wait ended:
+ * `data:` URLs and preflights included, a redirect chain once), so
+ * `networkRequests`, the listed requests and JSON agree. Without network
+ * telemetry the watcher's count stays.
+ *
+ * @param result - Submit result with the requests it triggered
+ * @returns The result, `networkRequests` matching `triggeredRequests`
+ */
+export function withTriggeredRequestCount(result) {
+    if (result.networkRequests === undefined || result.triggeredRequests === undefined)
+        return result;
+    const total = result.triggeredRequests.length + (result.triggeredRequestsOmitted ?? 0);
+    return { ...result, networkRequests: total };
+}
+/**
+ * A WebSocket connection as a request: its handshake (`GET ws://…`, 101 once
+ * it opened, failed when it closed without one).
+ *
+ * @param connection - Captured WebSocket connection
+ * @returns Request-shaped view of the handshake
+ */
+function webSocketAsRequest(connection) {
+    const failed = connection.status === undefined && connection.closedTime !== undefined;
+    return {
+        requestId: connection.requestId,
+        url: connection.url,
+        method: 'GET',
+        timestamp: connection.timestamp,
+        resourceType: 'WebSocket',
+        ...(connection.status !== undefined && { status: connection.status }),
+        ...(failed && { status: 0 }),
+        ...(failed && connection.errorMessage !== undefined && { errorText: connection.errorMessage }),
+    };
+}
+/**
+ * Order requests by when they started: Chrome's start time when both have
+ * one (bdg's own receipt times are whole milliseconds, so requests started
+ * together tie), otherwise when bdg saw them start.
+ *
+ * @param a - Request
+ * @param b - Request
+ * @returns Sort order
+ */
+function byStartTime(a, b) {
+    if (a.sentTime !== undefined && b.sentTime !== undefined)
+        return a.sentTime - b.sentTime;
+    return a.timestamp - b.timestamp;
+}
+/**
+ * Whether a request is worth reporting: not a local URL and not a CORS
+ * preflight (Chrome reports those beside the request they guard).
+ *
+ * @param request - Captured request
+ * @returns True to report it
+ */
+function isReportable(request) {
+    return request.resourceType !== 'Preflight' && !LOCAL_URL_PATTERN.test(request.url);
+}
+/**
+ * Summarize a captured request.
+ *
+ * @param request - Captured request
+ * @param inFlight - Whether it was still in flight (a request with a response
+ *   is then still loading its body: a stream, a slow download)
+ * @returns Triggered request entry
+ */
+export function toTriggeredRequest(request, inFlight = false) {
+    const state = getRequestState(request);
+    const errorText = failureReason(request);
+    return {
+        requestId: request.requestId,
+        method: request.method,
+        url: request.url,
+        ...(request.resourceType !== undefined && { resourceType: request.resourceType }),
+        ...(state === 'complete' && { status: request.status }),
+        ...(state === 'complete' && inFlight && { loading: true }),
+        ...(state !== 'pending' && request.duration !== undefined && { durationMs: request.duration }),
+        ...(state === 'failed' && { failed: true }),
+        ...(errorText !== undefined && { errorText }),
+        ...(state === 'pending' && { pending: true }),
+    };
+}
+//# sourceMappingURL=triggeredRequests.js.map

package/dist/daemon/session/types.d.ts

@@ -1,4 +1,4 @@
-import type { TelemetryType } from '../../types.js';
+import type { ColorScheme, TelemetryType, ViewportSize } from '../../types.js';
 export interface SessionConfig {
     url: string;
     port: number;
@@ -11,5 +11,9 @@ export interface SessionConfig {
     chromeWsUrl?: string;
     /** Custom Chrome flags (e.g., ['--ignore-certificate-errors']) */
     chromeFlags?: string[];
+    /** Viewport size to emulate (`--viewport`) */
+    viewport?: ViewportSize;
+    /** `prefers-color-scheme` to emulate (`--color-scheme`) */
+    colorScheme?: ColorScheme;
 }
 //# sourceMappingURL=types.d.ts.map