feat: add experimental browser.debugInfo (#11748)

docs/api/index.md

@@ -91,6 +91,7 @@ sidebar_label: API
 | [Credentials](./puppeteer.credentials.md)                                   |                                                                                                                                                                                     |
 | [CSSCoverageOptions](./puppeteer.csscoverageoptions.md)                     | Set of configurable options for CSS coverage.                                                                                                                                       |
 | [CustomQueryHandler](./puppeteer.customqueryhandler.md)                     |                                                                                                                                                                                     |
+| [DebugInfo](./puppeteer.debuginfo.md)                                       |                                                                                                                                                                                     |
 | [Device](./puppeteer.device.md)                                             |                                                                                                                                                                                     |
 | [ElementScreenshotOptions](./puppeteer.elementscreenshotoptions.md)         |                                                                                                                                                                                     |
 | [FrameAddScriptTagOptions](./puppeteer.frameaddscripttagoptions.md)         |                                                                                                                                                                                     |

docs/api/puppeteer.browser.md

@@ -56,9 +56,10 @@ await browser2.close();
 
 ## Properties
 
-| Property  | Modifiers             | Type    | Description                                                               |
-| --------- | --------------------- | ------- | ------------------------------------------------------------------------- |
-| connected | <code>readonly</code> | boolean | Whether Puppeteer is connected to this [browser](./puppeteer.browser.md). |
+| Property  | Modifiers             | Type                                  | Description                                                               |
+| --------- | --------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
+| connected | <code>readonly</code> | boolean                               | Whether Puppeteer is connected to this [browser](./puppeteer.browser.md). |
+| debugInfo | <code>readonly</code> | [DebugInfo](./puppeteer.debuginfo.md) | Get debug information from Puppeteer.                                     |
 
 ## Methods
 

docs/api/puppeteer.debuginfo.md

@@ -0,0 +1,17 @@
+---
+sidebar_label: DebugInfo
+---
+
+# DebugInfo interface
+
+#### Signature:
+
+```typescript
+export interface DebugInfo
+```
+
+## Properties
+
+| Property              | Modifiers | Type      | Description | Default |
+| --------------------- | --------- | --------- | ----------- | ------- |
+| pendingProtocolErrors |           | Error\[\] |             |         |

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 protocol 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"],
@@ -3366,7 +3372,7 @@
     "testIdPattern": "[target.spec] Target Browser.waitForTarget should wait for a target",
     "platforms": ["darwin", "linux", "win32"],
     "parameters": ["chrome", "webDriverBiDi"],
-    "expectations": ["PASS"]
+    "expectations": ["FAIL", "PASS"]
   },
   {
     "testIdPattern": "[target.spec] Target Browser.waitForTarget should wait for a target",

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('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);
+    });
+  });
+});