browser-debugger-cli 0.14.0 → 0.16.0

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,
             };
@@ -452,8 +486,8 @@ export function createCommandRegistry(store, emulation) {
             return { result, ...(hint !== undefined && { hint }) };
         },
         dom_eval: async (cdp, params) => params.frame === undefined
-            ? evaluateScript(cdp, params.script)
-            : evaluateInFrame(cdp, pageWebSocketUrl(store), params.script, params.frame, listedFrameIds),
+            ? evaluateScript(cdp, params.script, { full: params.full ?? false })
+            : evaluateInFrame(cdp, pageWebSocketUrl(store), params.script, params.frame, listedFrameIds, params.full ?? false),
         dom_frames: async (cdp) => {
             const { frames, frameIds } = await listFrames(cdp, pageWebSocketUrl(store));
             listedFrameIds = frameIds;
@@ -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,