feat: add browser.debugInfo

This is an experimental method that would provide
debugging information to help debug issues with Puppeteer.
Currently, it only provides the stacktraces for pending protocol
calls.

packages/puppeteer-core/src/api/Browser.ts

@@ -186,6 +186,14 @@ export interface BrowserEvents extends Record<EventType, unknown> {
   [BrowserEvent.TargetDiscovered]: Protocol.Target.TargetInfo;
 }
 
+/**
+ * @public
+ * @experimental
+ */
+export interface DebugInfo {
+  pendingProtocolErrors: Error[];
+}
+
 /**
  * {@link Browser} represents a browser instance that is either:
  *
@@ -431,4 +439,16 @@ export abstract class Browser extends EventEmitter<BrowserEvents> {
    * @internal
    */
   abstract get protocol(): ProtocolType;
+
+  /**
+   * Get debug information from Puppeteer.
+   *
+   * @remarks
+   *
+   * Currently, includes pending CDP calls. In the future, we might add more info.
+   *
+   * @public
+   * @experimental
+   */
+  abstract get debugInfo(): DebugInfo;
 }

packages/puppeteer-core/src/bidi/Browser.ts

@@ -13,6 +13,7 @@ import {
   BrowserEvent,
   type BrowserCloseCallback,
   type BrowserContextOptions,
+  type DebugInfo,
 } from '../api/Browser.js';
 import {BrowserContextEvent} from '../api/BrowserContext.js';
 import type {Page} from '../api/Page.js';
@@ -307,4 +308,10 @@ export class BidiBrowser extends Browser {
       this.connection.dispose();
     }
   }
+
+  override get debugInfo(): DebugInfo {
+    return {
+      pendingProtocolErrors: this.connection.getPendingProtocolErrors(),
+    };
+  }
 }

packages/puppeteer-core/src/bidi/Connection.ts

@@ -234,6 +234,10 @@ export class BidiConnection
     this.unbind();
     this.#transport.close();
   }
+
+  getPendingProtocolErrors(): Error[] {
+    return this.#callbacks.getPendingProtocolErrors();
+  }
 }
 
 /**

packages/puppeteer-core/src/cdp/Browser.ts

@@ -8,6 +8,7 @@ import type {ChildProcess} from 'child_process';
 
 import type {Protocol} from 'devtools-protocol';
 
+import type {DebugInfo} from '../api/Browser.js';
 import {
   Browser as BrowserBase,
   BrowserEvent,
@@ -417,6 +418,12 @@ export class CdpBrowser extends BrowserBase {
   #getVersion(): Promise<Protocol.Browser.GetVersionResponse> {
     return this.#connection.send('Browser.getVersion');
   }
+
+  override get debugInfo(): DebugInfo {
+    return {
+      pendingProtocolErrors: this.#connection.getPendingProtocolErrors(),
+    };
+  }
 }
 
 /**

packages/puppeteer-core/src/cdp/CDPSession.ts

@@ -157,4 +157,11 @@ export class CdpCDPSession extends CDPSession {
   override id(): string {
     return this.#sessionId;
   }
+
+  /**
+   * @internal
+   */
+  getPendingProtocolErrors(): Error[] {
+    return this.#callbacks.getPendingProtocolErrors();
+  }
 }

packages/puppeteer-core/src/cdp/Connection.ts

@@ -251,6 +251,18 @@ export class Connection extends EventEmitter<CDPSessionEvents> {
   ): Promise<CDPSession> {
     return await this._createSession(targetInfo, false);
   }
+
+  /**
+   * @internal
+   */
+  getPendingProtocolErrors(): Error[] {
+    const result: Error[] = [];
+    result.push(...this.#callbacks.getPendingProtocolErrors());
+    for (const session of this.#sessions.values()) {
+      result.push(...session.getPendingProtocolErrors());
+    }
+    return result;
+  }
 }
 
 /**

packages/puppeteer-core/src/common/CallbackRegistry.ts

@@ -94,6 +94,19 @@ export class CallbackRegistry {
     }
     this.#callbacks.clear();
   }
+
+  /**
+   * @internal
+   */
+  getPendingProtocolErrors(): Error[] {
+    const result: Error[] = [];
+    for (const callback of this.#callbacks.values()) {
+      result.push(
+        new Error(`${callback.label} timed out. Trace: ${callback.error.stack}`)
+      );
+    }
+    return result;
+  }
 }
 /**
  * @internal

test/TestExpectations.json

@@ -41,6 +41,12 @@
     "parameters": ["webDriverBiDi"],
     "expectations": ["PASS"]
   },
+  {
+    "testIdPattern": "[debugInfo.spec] *",
+    "platforms": ["darwin", "linux", "win32"],
+    "parameters": ["webDriverBiDi"],
+    "expectations": ["PASS"]
+  },
   {
     "testIdPattern": "[device-request-prompt.spec] *",
     "platforms": ["darwin", "linux", "win32"],

test/src/debugInfo.spec.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2024 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import expect from 'expect';
+
+import {getTestState, setupTestBrowserHooks} from './mocha-utils.js';
+
+describe('DebugInfo', function () {
+  setupTestBrowserHooks();
+
+  describe('Browser.debugInfo', function () {
+    it.only('should work', async () => {
+      const {page, browser} = await getTestState();
+
+      const promise = page.evaluate(() => {
+        return new Promise(resolve => {
+          // @ts-expect-error another context
+          window.resolve = resolve;
+        });
+      });
+      try {
+        expect(browser.debugInfo.pendingProtocolErrors).toHaveLength(1);
+      } finally {
+        await page.evaluate(() => {
+          // @ts-expect-error another context
+          window.resolve();
+        });
+      }
+      await promise;
+      expect(browser.debugInfo.pendingProtocolErrors).toHaveLength(0);
+    });
+  });
+});