browser-debugger-cli 0.9.0 → 0.10.0

package/dist/daemon/session/Session.js

@@ -21,6 +21,7 @@ import { getSessionPort } from '../../session/port.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { formatChromeNotice } from '../../ui/messages/chrome.js';
 import { delay } from '../../utils/async.js';
+import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { filterDefined } from '../../utils/objects.js';
 import { isProcessAlive } from '../../utils/process.js';
@@ -55,7 +56,10 @@ export class Session {
     config;
     onEnded;
     store = new TelemetryStore();
-    registry = createCommandRegistry(this.store);
+    registry = createCommandRegistry(this.store, {
+        get: () => filterDefined({ viewport: this.config.viewport, colorScheme: this.config.colorScheme }),
+        set: (emulation) => this.setEmulation(emulation),
+    });
     notify = (notice) => log.info(formatChromeNotice(notice));
     chrome = null;
     cdp = null;
@@ -174,6 +178,24 @@ export class Session {
             }),
         };
     }
+    /**
+     * Record a page emulation changed mid-session, so screenshots restore it
+     * and `bdg status` reports it.
+     *
+     * @param emulation - Viewport and color scheme now emulated
+     */
+    setEmulation(emulation) {
+        const { viewport: _viewport, colorScheme: _colorScheme, ...rest } = this.config;
+        this.config = { ...rest, ...emulation };
+        if (!this.started)
+            return;
+        try {
+            writeSessionMetadata(this.metadata());
+        }
+        catch (error) {
+            log.debug(`Session metadata not updated: ${getErrorMessage(error)}`);
+        }
+    }
     /**
      * Whether stop() has been called.
      *

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

@@ -1,10 +1,23 @@
 import type { TelemetryStore } from './TelemetryStore.js';
 import type { CDPConnection } from '../../connection/cdp.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']>;
 export type CommandRegistry = {
     [K in CommandName]: Handler<K>;
 };
-export declare function createCommandRegistry(store: TelemetryStore): CommandRegistry;
+/** The session's page emulation, which `page emulate` reads and changes */
+export interface EmulationState {
+    get: () => SessionEmulation;
+    set: (emulation: SessionEmulation) => void;
+}
+/**
+ * The handlers of the session commands.
+ *
+ * @param store - Telemetry of the session
+ * @param emulation - The session's page emulation
+ * @returns Command registry
+ */
+export declare function createCommandRegistry(store: TelemetryStore, emulation: EmulationState): CommandRegistry;
 export {};
 //# sourceMappingURL=commandRegistry.d.ts.map

package/dist/daemon/session/commandRegistry.js

@@ -1,9 +1,9 @@
-import { CDPConnectionError } from '../../connection/errors.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 { formDiscoveryFailedError } from '../../errors/messages.js';
+import { cdpCallError, formDiscoveryFailedError } from '../../errors/messages.js';
 import { evaluateScript, withBusyPageRecovery } from '../../runtime/dom/evalHelpers.js';
 import { inspectEventListeners } from '../../runtime/dom/eventListeners.js';
 import { FORM_DISCOVERY_SCRIPT, isRawFormData } from '../../runtime/dom/formDiscovery.js';
@@ -11,10 +11,11 @@ import { fillElement, clickElement, pressKeyElement, scrollPage, withActionStabi
 import { exceptionSummary } from '../../runtime/dom/formFillHelpers/shared.js';
 import { submitForm } from '../../runtime/dom/formSubmitHelpers.js';
 import { evaluateInFrame, listFrames } from '../../runtime/dom/frames.js';
+import { inspectElement } from '../../runtime/dom/inspect.js';
 import { inspectLayout } from '../../runtime/dom/layout.js';
 import { onScriptTarget } from '../../runtime/dom/targetNode.js';
 import { waitForCondition } from '../../runtime/dom/wait.js';
-import { pageAppearance } from '../../runtime/page/emulation.js';
+import { emulatePage, pageAppearance } from '../../runtime/page/emulation.js';
 import { readDocumentReadyState } from '../../runtime/page/loadingState.js';
 import { navigatePage } from '../../runtime/page/navigation.js';
 import { skippedBodyReason } from '../../telemetry/network.js';
@@ -62,6 +63,8 @@ function mapNetworkRequestToPreview(req, withHeaders = false) {
     return filterDefined({
         requestId: req.requestId,
         timestamp: req.timestamp,
+        sentTime: req.sentTime,
+        navigationId: req.navigationId,
         method: req.method,
         url: req.url,
         status: req.status,
@@ -260,9 +263,45 @@ function pageWebSocketUrl(store) {
         throw new CDPConnectionError('No page target');
     return url;
 }
-export function createCommandRegistry(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;
+/**
+ * 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.
+ *
+ * @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) {
+    if (!(error instanceof CDPProtocolError))
+        return undefined;
+    const err = cdpCallError(method, error.message);
+    if (error.isRequestError()) {
+        return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    if (error.code === CDP_SERVER_ERROR && err.notFound) {
+        return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+    }
+    if (error.code === CDP_SERVER_ERROR &&
+        /must be specified|invalid|expected|missing/i.test(error.message)) {
+        return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    return undefined;
+}
+/**
+ * The handlers of the session commands.
+ *
+ * @param store - Telemetry of the session
+ * @param emulation - The session's page emulation
+ * @returns Command registry
+ */
+export function createCommandRegistry(store, emulation) {
     const patternDetector = new PatternDetector();
     const interact = createInteractionRunner(store);
+    /** Frame id behind each index of the last `dom frames` listing */
+    let listedFrameIds;
     return {
         session_peek: async (_cdp, params) => {
             const lastN = calculateLastN(params.lastN);
@@ -360,7 +399,9 @@ export function createCommandRegistry(store) {
             });
         },
         cdp_call: async (cdp, params) => {
-            const result = await withBusyPageRecovery(cdp, cdp.send(params.method, params.params ?? {}));
+            const result = await withBusyPageRecovery(cdp, cdp.send(params.method, params.params ?? {}).catch((error) => {
+                throw callerError(params.method, error) ?? error;
+            }));
             const detectionResult = patternDetector.trackCommand(params.method);
             let hint;
             if (detectionResult.shouldShow && detectionResult.pattern) {
@@ -376,11 +417,21 @@ export function createCommandRegistry(store) {
         },
         dom_eval: async (cdp, params) => params.frame === undefined
             ? evaluateScript(cdp, params.script)
-            : evaluateInFrame(cdp, pageWebSocketUrl(store), params.script, params.frame),
-        dom_frames: async (cdp) => ({ frames: await listFrames(cdp, pageWebSocketUrl(store)) }),
+            : evaluateInFrame(cdp, pageWebSocketUrl(store), params.script, params.frame, listedFrameIds),
+        dom_frames: async (cdp) => {
+            const { frames, frameIds } = await listFrames(cdp, pageWebSocketUrl(store));
+            listedFrameIds = frameIds;
+            return { frames };
+        },
         dom_fill: async (cdp, params) => interact(cdp, async () => onScriptTarget(cdp, params, (target) => withActionStability(cdp, () => fillElement(target.cdp, target.selector, params.value, filterDefined({ index: target.index, blur: params.blur, cwd: params.cwd })), params.wait !== false))),
-        dom_click: async (cdp, params) => interact(cdp, async () => onScriptTarget(cdp, params, (target) => withActionStability(cdp, () => clickElement(target.cdp, target.selector, filterDefined({ index: target.index, action: params.action })), params.wait !== false)), {
+        dom_click: async (cdp, params) => interact(cdp, async () => onScriptTarget(cdp, params, (target) => withActionStability(cdp, () => clickElement(target.cdp, target.selector, filterDefined({
+            index: target.index,
+            action: params.action,
+            strict: params.strict,
+        })), params.wait !== false)), {
             detectNoEffect: params.wait !== false && params.action !== 'hover' && params.action !== 'right',
+            reportShown: params.action === 'hover',
+            detectUnsettled: params.wait !== false && params.action !== 'hover',
         }),
         dom_submit: async (cdp, params) => withTriggeredRequestCount(await interact(cdp, async () => onScriptTarget(cdp, params, (target) => submitForm(target.cdp, target.selector, {
             ...filterDefined({
@@ -395,7 +446,7 @@ export function createCommandRegistry(store) {
             index: target.index,
             times: params.times,
             modifiers: params.modifiers,
-        })), params.wait !== false))),
+        })), params.wait !== false)), { reportShown: true, detectUnsettled: params.wait !== false }),
         dom_scroll: async (cdp, params) => interact(cdp, async () => onScriptTarget(cdp, params, (target) => withActionStability(cdp, () => scrollPage(target.cdp, target.selector || undefined, filterDefined({
             index: target.index,
             down: params.down,
@@ -407,11 +458,16 @@ export function createCommandRegistry(store) {
         })), params.wait !== false))),
         dom_listeners: async (cdp, params) => withBusyPageRecovery(cdp, inspectEventListeners(cdp, params)),
         dom_layout: async (cdp, params) => withBusyPageRecovery(cdp, inspectLayout(cdp, params)),
+        dom_inspect: async (cdp, params) => withBusyPageRecovery(cdp, inspectElement(cdp, params)),
         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 }),
             pendingRequests: () => store.pendingNetworkRequests.values(),
         }), { reportRequests: false, reportEffects: false }),
+        page_emulate: async (cdp, params) => {
+            const emulated = await emulatePage(cdp, emulation.get(), params, emulation.set);
+            return { emulated, ...(await pageAppearance(cdp)) };
+        },
         dom_form_discover: async (cdp) => {
             const response = await withBusyPageRecovery(cdp, cdp.send('Runtime.evaluate', {
                 expression: FORM_DISCOVERY_SCRIPT,

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

@@ -1,6 +1,7 @@
 /**
  * Running page interactions (fill, click, submit, pressKey, scroll) one at a
- * time, reporting the dialogs, network requests and page changes they caused.
+ * time, reporting the dialogs, network requests and page changes they caused,
+ * and whether the page was still changing when they returned.
  */
 import type { TelemetryStore } from './TelemetryStore.js';
 import type { CDPConnection } from '../../connection/cdp.js';
@@ -28,6 +29,17 @@ export interface InteractionOptions {
      * whose effect shows in the DOM (click, submit) and that waited for it
      */
     detectNoEffect?: boolean;
+    /**
+     * List the elements it showed (`shown`): for hover and key presses, whose
+     * effect is often a menu, tooltip or new item rather than a message
+     */
+    reportShown?: boolean;
+    /**
+     * Say when the page was still changing as it returned (`settled: false`
+     * with `pending`): for actions that start app transitions (click, key
+     * press) and waited for the network
+     */
+    detectUnsettled?: boolean;
 }
 /** Runs one interaction after the previous one finished */
 export type InteractionRunner = <T extends object>(cdp: CDPConnection, action: () => Promise<T>, options?: InteractionOptions) => Promise<T & InteractionReport>;
@@ -40,10 +52,11 @@ 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}) 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.
+ * triggered (see {@link watchTriggeredRequests}) 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
+ * whichever interaction is running then.
  *
  * @param store - Session store recording accepted dialogs and network requests
  * @returns Interaction runner

package/dist/daemon/session/interactions.js

@@ -1,8 +1,9 @@
 /**
  * Running page interactions (fill, click, submit, pressKey, scroll) one at a
- * time, reporting the dialogs, network requests and page changes they caused.
+ * time, reporting the dialogs, network requests and page changes they caused,
+ * and whether the page was still changing when they returned.
  */
-import { watchActionEffects } from '../../runtime/dom/actionEffects.js';
+import { pendingChanges, 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';
@@ -26,10 +27,11 @@ function succeeded(result) {
  * 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}) 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.
+ * triggered (see {@link watchTriggeredRequests}) 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
+ * whichever interaction is running then.
  *
  * @param store - Session store recording accepted dialogs and network requests
  * @returns Interaction runner
@@ -44,17 +46,25 @@ export function createInteractionRunner(store) {
             try {
                 const result = await action();
                 const dialogs = store.dialogs.slice(firstDialog);
-                const changes = succeeded(result)
-                    ? await effects?.collect({
-                        dialogs: dialogs.length,
-                        detectNoEffect: options.detectNoEffect === true,
-                    })
+                if (!succeeded(result))
+                    return { ...result, ...(dialogs.length > 0 && { dialogs }) };
+                const collected = await effects?.collect({
+                    dialogs: dialogs.length,
+                    detectNoEffect: options.detectNoEffect === true,
+                    reportShown: options.reportShown === true,
+                    detectUnsettled: options.detectUnsettled === true,
+                });
+                const { work, ...changes } = collected ?? {};
+                const requests = collectRequests?.();
+                const pending = options.detectUnsettled && work
+                    ? pendingChanges(work, requests?.triggeredRequests)
                     : undefined;
                 return {
                     ...result,
                     ...(dialogs.length > 0 && { dialogs }),
                     ...changes,
-                    ...(succeeded(result) && collectRequests?.()),
+                    ...(pending && { settled: false, pending }),
+                    ...requests,
                 };
             }
             finally {