browser-debugger-cli 0.15.0 → 0.16.0

package/dist/daemon/session/chromeConnection.js

@@ -14,23 +14,47 @@ import { writeChromePid } from '../../session/chrome.js';
 import { findConflictingOwner } from '../../session/chromeOwners.js';
 import { getSessionDir } from '../../session/paths.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
-import { createPageTarget, fetchCDPTargets, probeDevToolsEndpoint } from '../../utils/http.js';
+import { createPageTarget, fetchBrowserWsUrl, fetchCDPTargets, probeDevToolsEndpoint, } from '../../utils/http.js';
 import { filterDefined } from '../../utils/objects.js';
 /**
  * Setup Chrome connection - either launch new instance or connect to existing.
  *
+ * @param config - Session configuration
+ * @param telemetryStore - Store receiving the target info
+ * @param log - Logger
+ * @param notify - Receives notices about an external Chrome
+ * @param signal - Ends a launch at once when aborted (the session was stopped)
  * @returns Launched Chrome instance (null if connecting to external Chrome)
  */
-export async function setupChromeConnection(config, telemetryStore, log, notify) {
+export async function setupChromeConnection(config, telemetryStore, log, notify, signal) {
     if (config.chromeWsUrl) {
         return setupExternalChrome(config, telemetryStore, log, notify);
     }
     else {
-        return setupLaunchedChrome(config, log);
+        return setupLaunchedChrome(config, log, signal);
     }
 }
 /** Path of browser-level DevTools WebSocket URLs (`/devtools/browser/<uuid>`) */
 const BROWSER_WS_PATH = '/devtools/browser/';
+/**
+ * Browser-level DevTools WebSocket URL of the session's Chrome: a launched
+ * Chrome's, or for `--chrome-ws-url` the URL itself when it is browser-level,
+ * else the one Chrome reports, reached the way the user's URL is.
+ *
+ * @param config - Session configuration (port resolved)
+ * @param log - Logger
+ * @returns The URL, or null when Chrome does not answer `/json/version`
+ */
+export async function browserWebSocketUrl(config, log) {
+    if (!config.chromeWsUrl)
+        return fetchBrowserWsUrl(config.port, log);
+    const { hostname, pathname, protocol, port } = new URL(config.chromeWsUrl);
+    if (pathname.startsWith(BROWSER_WS_PATH))
+        return config.chromeWsUrl;
+    const http = { host: hostname, secure: protocol === 'wss:' };
+    const reported = await fetchBrowserWsUrl(config.port, log, http);
+    return reported && withEndpoint(reported, protocol, hostname, port);
+}
 /**
  * Debugging port of an external Chrome, taken from its WebSocket URL.
  *
@@ -162,12 +186,18 @@ export function windowSizeFlags(config) {
 }
 /**
  * Launch a new Chrome instance and record its PID for crash cleanup.
+ *
+ * @param config - Session configuration
+ * @param log - Logger
+ * @param signal - Ends the launch at once when aborted
+ * @returns Launched Chrome
  */
-async function setupLaunchedChrome(config, log) {
+async function setupLaunchedChrome(config, log, signal) {
     const chrome = await launchChrome({
         port: config.port,
         logger: log,
         sessionDir: getSessionDir(),
+        signal,
         ...filterDefined({
             userDataDir: config.userDataDir,
             headless: config.headless,

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

@@ -4,5 +4,20 @@ import type { SessionConfig } from './types.js';
 import type { CDPConnection } from '../../connection/cdp.js';
 import type { CleanupFunction } from '../../types.js';
 import type { Logger } from '../../ui/logging/index.js';
+/**
+ * Start the session's collectors (telemetry plugins) in order.
+ *
+ * When one fails to start, the ones already started are cleaned up (their
+ * failures logged) before the error is rethrown, so nothing they opened (a
+ * browser-level connection, event handlers) outlives the failed start.
+ *
+ * @param cdp - Page connection
+ * @param config - Session configuration
+ * @param store - Telemetry store
+ * @param logger - Logger
+ * @param plugins - Plugins to start (default: the registered ones)
+ * @returns Cleanup functions of the started collectors
+ * @throws The error of the collector that failed to start
+ */
 export declare function startTelemetryCollectors(cdp: CDPConnection, config: SessionConfig, store: TelemetryStore, logger: Logger, plugins?: TelemetryPlugin[]): Promise<CleanupFunction[]>;
 //# sourceMappingURL=collectors.d.ts.map

package/dist/daemon/session/collectors.js

@@ -1,6 +1,22 @@
 import { sessionActivatingCollector, sessionCollectorsActivated } from '../messages.js';
+import { getErrorMessage } from '../../utils/errors.js';
 import { getRegisteredTelemetryPlugins, shouldActivatePlugin } from './plugins.js';
 const DEFAULT_TELEMETRY = ['network', 'console', 'dom'];
+/**
+ * Start the session's collectors (telemetry plugins) in order.
+ *
+ * When one fails to start, the ones already started are cleaned up (their
+ * failures logged) before the error is rethrown, so nothing they opened (a
+ * browser-level connection, event handlers) outlives the failed start.
+ *
+ * @param cdp - Page connection
+ * @param config - Session configuration
+ * @param store - Telemetry store
+ * @param logger - Logger
+ * @param plugins - Plugins to start (default: the registered ones)
+ * @returns Cleanup functions of the started collectors
+ * @throws The error of the collector that failed to start
+ */
 export async function startTelemetryCollectors(cdp, config, store, logger, plugins) {
     const cleanupFunctions = [];
     store.activeTelemetry = config.telemetry ?? DEFAULT_TELEMETRY;
@@ -10,10 +26,31 @@ export async function startTelemetryCollectors(cdp, config, store, logger, plugi
             continue;
         }
         logger.debug(sessionActivatingCollector(plugin.name));
-        const cleanup = await plugin.start({ cdp, config, store, logger });
-        cleanupFunctions.push(cleanup);
+        try {
+            cleanupFunctions.push(await plugin.start({ cdp, config, store, logger }));
+        }
+        catch (error) {
+            await runCleanups(cleanupFunctions, logger);
+            throw error;
+        }
     }
     logger.debug(sessionCollectorsActivated(store.activeTelemetry));
     return cleanupFunctions;
 }
+/**
+ * Run cleanup functions, logging (not throwing) their failures.
+ *
+ * @param cleanups - Cleanup functions
+ * @param logger - Logger
+ */
+async function runCleanups(cleanups, logger) {
+    for (const cleanup of cleanups) {
+        try {
+            await cleanup();
+        }
+        catch (error) {
+            logger.debug(`Collector cleanup error: ${getErrorMessage(error)}`);
+        }
+    }
+}
 //# sourceMappingURL=collectors.js.map

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

@@ -1,11 +1,24 @@
 import type { TelemetryStore } from './TelemetryStore.js';
 import type { CDPConnection } from '../../connection/cdp.js';
+import { CommandError } from '../../errors/index.js';
 import type { CommandName, CommandSchemas } from '../../ipc/index.js';
 import { type SessionEmulation } from '../../runtime/page/emulation.js';
-type Handler<K extends CommandName> = (cdp: CDPConnection, params: CommandSchemas[K]['requestSchema']) => Promise<CommandSchemas[K]['responseSchema']>;
+/** A command's handler; `abandoned` aborts when its client disconnects */
+type Handler<K extends CommandName> = (cdp: CDPConnection, params: CommandSchemas[K]['requestSchema'], abandoned?: AbortSignal) => Promise<CommandSchemas[K]['responseSchema']>;
 export type CommandRegistry = {
     [K in CommandName]: Handler<K>;
 };
+/**
+ * A `bdg cdp` failure that is the caller's: a method this Chrome doesn't
+ * implement (83), wrong parameters (81), or an id of a node, target or frame
+ * that does not exist (83). Other failures (internal errors, a detached
+ * page) stay software errors.
+ *
+ * @param method - CDP method
+ * @param error - What the call threw
+ * @returns The error to report, or undefined to keep the original
+ */
+export declare function callerError(method: string, error: unknown): CommandError | undefined;
 /** The session's page emulation, which `page emulate` reads and changes */
 export interface EmulationState {
     get: () => SessionEmulation;

package/dist/daemon/session/commandRegistry.js

@@ -1,9 +1,10 @@
+import { missingMethodCause } from '../../cdp/methodTarget.js';
 import { CDPConnectionError, CDPProtocolError } from '../../connection/errors.js';
 import { PatternDetector } from '../patternDetector.js';
 import { createInteractionRunner } from './interactions.js';
 import { withTriggeredRequestCount } from './triggeredRequests.js';
 import { CommandError } from '../../errors/index.js';
-import { cdpCallError, formDiscoveryFailedError } from '../../errors/messages.js';
+import { cdpCallError, cdpMethodNotImplementedError, formDiscoveryFailedError, } from '../../errors/messages.js';
 import { searchStyleSheets } from '../../runtime/css/search.js';
 import { auditPage } from '../../runtime/dom/audit.js';
 import { evaluateScript, withBusyPageRecovery } from '../../runtime/dom/evalHelpers.js';
@@ -21,6 +22,8 @@ import { evaluateInBdgWorld, sendForBdgScript } from '../../runtime/page/bdgWorl
 import { emulatePage, pageAppearance } from '../../runtime/page/emulation.js';
 import { readDocumentReadyState } from '../../runtime/page/loadingState.js';
 import { navigatePage } from '../../runtime/page/navigation.js';
+import { takeScreenshot } from '../../runtime/page/screenshot.js';
+import { toDownloadInfo } from '../../telemetry/downloads.js';
 import { skippedBodyReason } from '../../telemetry/networkRetention.js';
 import { consoleMessageDroppedError } from '../../ui/messages/consoleMessages.js';
 import { sessionCommand } from '../../ui/messages/sessionCommand.js';
@@ -140,6 +143,15 @@ function webSocketAsRequest(connection) {
         webSocket: { frames: connection.frames, ...(closedTime !== undefined && { closedTime }) },
     };
 }
+/**
+ * The session's downloads for `status` and `peek`, left out when none began.
+ *
+ * @param store - Telemetry store
+ * @returns `downloads`, oldest first, as they stand now
+ */
+function sessionDownloads(store) {
+    return store.downloads.length > 0 ? { downloads: store.downloads.map(toDownloadInfo) } : {};
+}
 /**
  * Status activity counts of what the network capture let go at its limits,
  * left out when nothing was.
@@ -169,18 +181,28 @@ function allNetworkRequests(store) {
     ].sort((a, b) => a.timestamp - b.timestamp);
 }
 /**
- * Present a body bdg chose not to fetch as `bodyNotCaptured` (the reason)
- * instead of a placeholder string in `responseBody`.
+ * Present bodies bdg did not fetch or keep as their reasons
+ * (`requestBodyNotCaptured`, `bodyNotCaptured`) instead of placeholder
+ * strings in `requestBody` and `responseBody`.
  *
  * @param request - Captured request
  * @returns The request as `details` reports it
  */
 function withBodyNotCaptured(request) {
-    const reason = skippedBodyReason(request.responseBody);
-    if (reason === undefined)
+    const requestReason = skippedBodyReason(request.requestBody);
+    const responseReason = skippedBodyReason(request.responseBody);
+    if (requestReason === undefined && responseReason === undefined)
         return request;
-    const { responseBody: _placeholder, ...rest } = request;
-    return { ...rest, bodyNotCaptured: reason };
+    const result = { ...request };
+    if (requestReason !== undefined) {
+        delete result.requestBody;
+        result.requestBodyNotCaptured = requestReason;
+    }
+    if (responseReason !== undefined) {
+        delete result.responseBody;
+        result.bodyNotCaptured = responseReason;
+    }
+    return result;
 }
 /**
  * Find a network request by ID: finished, in flight, or a WebSocket.
@@ -287,18 +309,25 @@ function pageWebSocketUrl(store) {
 }
 /** Chrome's "server error" code, used for failures on the page's state (a missing node, a bad id…) */
 const CDP_SERVER_ERROR = -32000;
+/** JSON-RPC "method not found": Chrome has no such method (for the target) */
+const CDP_METHOD_NOT_FOUND = -32601;
 /**
- * A `bdg cdp` failure that is the caller's: wrong parameters (81), or an
- * id of a node, target or frame that does not exist (83). Other failures
- * (internal errors, a detached page) stay software errors.
+ * A `bdg cdp` failure that is the caller's: a method this Chrome doesn't
+ * implement (83), wrong parameters (81), or an id of a node, target or frame
+ * that does not exist (83). Other failures (internal errors, a detached
+ * page) stay software errors.
  *
  * @param method - CDP method
  * @param error - What the call threw
  * @returns The error to report, or undefined to keep the original
  */
-function callerError(method, error) {
+export function callerError(method, error) {
     if (!(error instanceof CDPProtocolError))
         return undefined;
+    if (error.code === CDP_METHOD_NOT_FOUND) {
+        const missing = cdpMethodNotImplementedError(method, error.message, missingMethodCause(method));
+        return new CommandError(missing.message, { suggestion: missing.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+    }
     const err = cdpCallError(method, error.message);
     if (error.isRequestError()) {
         return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
@@ -364,6 +393,7 @@ export function createCommandRegistry(store, emulation) {
                 ...(dropped > 0 && { droppedConsole: dropped }),
                 ...(requestsDropped > 0 && { droppedNetwork: requestsDropped }),
                 ...(bodiesEvicted > 0 && { evictedNetworkBodies: bodiesEvicted }),
+                ...sessionDownloads(store),
                 hasMoreNetwork: networkBounds.start > 0,
                 hasMoreConsole: consoleBounds.start > 0,
             });
@@ -400,6 +430,10 @@ export function createCommandRegistry(store, emulation) {
                     ...(lastNetworkRequest && { lastNetworkRequestAt: lastNetworkRequest.timestamp }),
                     ...(lastConsoleMessage && { lastConsoleMessageAt: lastConsoleMessage.timestamp }),
                     ...networkEvictionActivity(store),
+                    ...sessionDownloads(store),
+                    ...(store.downloadsWarning !== undefined && {
+                        downloadsWarning: store.downloadsWarning,
+                    }),
                 },
                 navigationId: store.getCurrentNavigationId?.() ?? 0,
             };
@@ -499,6 +533,7 @@ export function createCommandRegistry(store, emulation) {
         dom_inspect: async (cdp, params) => withBusyPageRecovery(cdp, inspectElement(cdp, params).then((result) => result.theme === 'dark' && emulation.get().colorScheme === 'dark'
             ? { ...result, themeFrom: 'emulation' }
             : result)),
+        dom_screenshot: async (cdp, params, abandoned) => takeScreenshot(cdp, params, () => emulation.get().viewport, { abandoned }),
         dom_wait: async (cdp, params) => waitForCondition(cdp, params),
         page_navigate: async (cdp, params) => interact(cdp, () => navigatePage(cdp, params.action, {
             ...filterDefined({ url: params.url, wait: params.wait }),

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

@@ -0,0 +1,32 @@
+/**
+ * Setting up a session's download tracking: where downloads go, and the
+ * connection their events arrive on.
+ */
+import type { TelemetryPluginContext } from './plugins.js';
+import type { SessionConfig } from './types.js';
+import { CDPConnection } from '../../connection/cdp.js';
+import type { CleanupFunction } from '../../types.js';
+import type { Logger } from '../../ui/logging/index.js';
+/**
+ * Opens a browser-level connection to the session's Chrome, or null when
+ * there is none; `onLost` is called if it closes while the session runs.
+ */
+export type BrowserConnector = (config: SessionConfig, logger: Logger, onLost: () => void) => Promise<CDPConnection | null>;
+/**
+ * Track the session's downloads (see {@link DownloadTracker}).
+ *
+ * For a Chrome bdg launched, on a browser-level connection, so downloads of
+ * tabs the page opens are named and recorded too; on the page's connection
+ * when there is none, or once it is lost (Chrome drops a connection's
+ * download behavior with it, so it is applied again there). An attached
+ * Chrome (`--chrome-ws-url`) is followed on the page's connection only: a
+ * browser-level one would count the user's other tabs' downloads as the
+ * session's, and a Chrome that allows one connection (toggle mode) would
+ * ask again for each.
+ *
+ * @param context - Plugin context
+ * @param connectBrowser - Opens the browser-level connection
+ * @returns Cleanup: stops tracking and closes the browser-level connection
+ */
+export declare function startSessionDownloads(context: TelemetryPluginContext, connectBrowser?: BrowserConnector): Promise<CleanupFunction>;
+//# sourceMappingURL=downloads.d.ts.map

package/dist/daemon/session/downloads.js

@@ -0,0 +1,96 @@
+/**
+ * Setting up a session's download tracking: where downloads go, and the
+ * connection their events arrive on.
+ */
+import { CDPConnection } from '../../connection/cdp.js';
+import { browserWebSocketUrl } from './chromeConnection.js';
+import { ensureSessionDownloadsDir } from '../../session/paths.js';
+import { DownloadTracker } from '../../telemetry/downloads.js';
+import { downloadsDirUnavailableReason } from '../../ui/messages/commands.js';
+import { getErrorMessage } from '../../utils/errors.js';
+/** Connection attempts for the browser-level connection (Chrome is already running) */
+const BROWSER_CONNECT_ATTEMPTS = 2;
+/**
+ * Track the session's downloads (see {@link DownloadTracker}).
+ *
+ * For a Chrome bdg launched, on a browser-level connection, so downloads of
+ * tabs the page opens are named and recorded too; on the page's connection
+ * when there is none, or once it is lost (Chrome drops a connection's
+ * download behavior with it, so it is applied again there). An attached
+ * Chrome (`--chrome-ws-url`) is followed on the page's connection only: a
+ * browser-level one would count the user's other tabs' downloads as the
+ * session's, and a Chrome that allows one connection (toggle mode) would
+ * ask again for each.
+ *
+ * @param context - Plugin context
+ * @param connectBrowser - Opens the browser-level connection
+ * @returns Cleanup: stops tracking and closes the browser-level connection
+ */
+export async function startSessionDownloads(context, connectBrowser = openBrowserConnection) {
+    const { cdp, config, store, logger } = context;
+    const tracker = new DownloadTracker(store, downloadDestination(config, logger));
+    const browser = config.chromeWsUrl
+        ? null
+        : await connectBrowser(config, logger, () => void followOnPage(tracker, cdp, logger));
+    await tracker.attach(browser ?? cdp);
+    return () => {
+        tracker.stop();
+        browser?.close();
+    };
+}
+/**
+ * Follow downloads on the page's connection after the browser-level one was lost.
+ *
+ * @param tracker - Session download tracker
+ * @param cdp - Page connection
+ * @param logger - Logger
+ */
+async function followOnPage(tracker, cdp, logger) {
+    logger.info('Browser connection for downloads lost; download behavior set again on the page');
+    await tracker.attach(cdp);
+}
+/**
+ * Open a browser-level connection to the session's Chrome.
+ *
+ * @param config - Session configuration
+ * @param logger - Logger
+ * @param onLost - Called if the connection closes while the session runs
+ * @returns Open connection, or null when there is none to open
+ */
+async function openBrowserConnection(config, logger, onLost) {
+    const url = await browserWebSocketUrl(config, logger);
+    if (!url)
+        return null;
+    const browser = new CDPConnection(logger);
+    try {
+        await browser.connect(url, { maxRetries: BROWSER_CONNECT_ATTEMPTS, onDisconnect: onLost });
+        return browser;
+    }
+    catch (error) {
+        logger.debug(`No browser-level connection for downloads: ${getErrorMessage(error)}`);
+        return null;
+    }
+}
+/**
+ * Where the session's downloads go: the session's `downloads/` for a Chrome
+ * bdg launched (refused when it cannot be created, rather than saved to the
+ * browser's default `~/Downloads`), the browser's own place for an attached
+ * Chrome.
+ *
+ * @param config - Session configuration
+ * @param logger - Logger
+ * @returns Destination
+ */
+function downloadDestination(config, logger) {
+    if (config.chromeWsUrl)
+        return { kind: 'browser' };
+    try {
+        return { kind: 'directory', dir: ensureSessionDownloadsDir() };
+    }
+    catch (error) {
+        const reason = downloadsDirUnavailableReason(getErrorMessage(error));
+        logger.info(reason);
+        return { kind: 'refused', reason };
+    }
+}
+//# sourceMappingURL=downloads.js.map

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

@@ -52,8 +52,9 @@ export type InteractionRunner = <T extends object>(cdp: CDPConnection, action: (
  * from the page (without waiting: during a pending navigation that takes until
  * the new page commits), and the dialogs it opened, what it changed on the
  * page (see {@link watchActionEffects}; a console message logged meanwhile
- * counts as an effect) and the network requests it
- * triggered (see {@link watchTriggeredRequests}) are added to its result,
+ * counts as an effect), the network requests it
+ * triggered (see {@link watchTriggeredRequests}) and the downloads that began
+ * meanwhile (as they stand when it returns) are added to its result,
  * and, when asked, what the page was still working on (see
  * {@link pendingChanges}). They are attributed by time: a dialog or request
  * started by a page timer or a navigation started earlier is reported by

package/dist/daemon/session/interactions.js

@@ -5,6 +5,7 @@
  */
 import { pendingChanges, watchActionEffects } from '../../runtime/dom/actionEffects.js';
 import { UNBIND_TARGET_SCRIPT } from '../../runtime/dom/targetNode.js';
+import { toDownloadInfo } from '../../telemetry/downloads.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { watchTriggeredRequests } from './triggeredRequests.js';
@@ -36,8 +37,9 @@ function consoleMessagesLogged(store) {
  * from the page (without waiting: during a pending navigation that takes until
  * the new page commits), and the dialogs it opened, what it changed on the
  * page (see {@link watchActionEffects}; a console message logged meanwhile
- * counts as an effect) and the network requests it
- * triggered (see {@link watchTriggeredRequests}) are added to its result,
+ * counts as an effect), the network requests it
+ * triggered (see {@link watchTriggeredRequests}) and the downloads that began
+ * meanwhile (as they stand when it returns) are added to its result,
  * and, when asked, what the page was still working on (see
  * {@link pendingChanges}). They are attributed by time: a dialog or request
  * started by a page timer or a navigation started earlier is reported by
@@ -51,6 +53,7 @@ export function createInteractionRunner(store) {
     return (cdp, action, options = {}) => {
         const run = queue.then(async () => {
             const firstDialog = store.dialogs.length;
+            const firstDownload = store.downloads.length;
             const firstConsoleMessage = consoleMessagesLogged(store);
             const collectRequests = options.reportRequests === false ? undefined : watchTriggeredRequests(store);
             const effects = options.reportEffects === false ? undefined : watchActionEffects(cdp);
@@ -68,6 +71,7 @@ export function createInteractionRunner(store) {
                 });
                 const { work, ...changes } = collected ?? {};
                 const requests = collectRequests?.();
+                const downloads = store.downloads.slice(firstDownload).map(toDownloadInfo);
                 const pending = options.detectUnsettled && work
                     ? pendingChanges(work, requests?.triggeredRequests)
                     : undefined;
@@ -76,6 +80,7 @@ export function createInteractionRunner(store) {
                     ...(dialogs.length > 0 && { dialogs }),
                     ...changes,
                     ...(pending && { settled: false, pending }),
+                    ...(downloads.length > 0 && { downloads }),
                     ...requests,
                 };
             }

package/dist/daemon/session/plugins.js

@@ -1,3 +1,4 @@
+import { startSessionDownloads } from './downloads.js';
 import { hideHeadlessUserAgent } from '../../runtime/page/userAgent.js';
 import { startConsoleCollection } from '../../telemetry/console.js';
 import { startDialogHandling } from '../../telemetry/dialogs.js';
@@ -94,6 +95,11 @@ export function createDefaultTelemetryPlugins() {
                 return startDialogHandling(cdp, (dialog) => store.recordDialog(dialog));
             },
         },
+        {
+            name: 'downloads',
+            runAlways: true,
+            start: startSessionDownloads,
+        },
         {
             name: 'page-identity',
             runAlways: true,