feat: add custom debugging port option (#4993)

docs/api.md

@@ -568,6 +568,7 @@ This methods attaches Puppeteer to an existing browser instance.
   - `args` <[Array]<[string]>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found [here](http://peter.sh/experiments/chromium-command-line-switches/).
   - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/user_data_dir.md).
   - `devtools` <[boolean]> Whether to auto-open a DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`.
+  - `debuggingPort` <[number]> Specify custom debugging port. Pass `0` to discover a random port. Defaults to `0`.
 - returns: <[Array]<[string]>>
 
 The default flags that Chromium will be launched with.
@@ -648,6 +649,7 @@ try {
   - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
   - `dumpio` <[boolean]> Whether to pipe the browser process stdout and stderr into `process.stdout` and `process.stderr`. Defaults to `false`.
   - `userDataDir` <[string]> Path to a [User Data Directory](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/user_data_dir.md).
+  - `debuggingPort` <[number]> Specify custom debugging port. Pass `0` to discover a random port. Defaults to `0`.
   - `env` <[Object]> Specify environment variables that will be visible to the browser. Defaults to `process.env`.
   - `devtools` <[boolean]> Whether to auto-open a DevTools panel for each tab. If this option is `true`, the `headless` option will be set `false`.
   - `pipe` <[boolean]> Connects to the browser over a pipe instead of a WebSocket. Defaults to `false`.

src/node/LaunchOptions.ts

@@ -40,6 +40,10 @@ export interface BrowserLaunchArgumentOptions {
    * @defaultValue `false`
    */
   devtools?: boolean;
+  /**
+   *
+   */
+  debuggingPort?: number;
   /**
    * Additional command line arguments to pass to the browser instance.
    */

src/node/Launcher.ts

@@ -82,6 +82,7 @@ class ChromeLauncher implements ProductLauncher {
       slowMo = 0,
       timeout = 30000,
       waitForInitialPage = true,
+      debuggingPort = null,
     } = options;
 
     const profilePath = path.join(tmpDir(), 'puppeteer_dev_chrome_profile-');
@@ -101,10 +102,17 @@ class ChromeLauncher implements ProductLauncher {
       !chromeArguments.some((argument) =>
         argument.startsWith('--remote-debugging-')
       )
-    )
-      chromeArguments.push(
-        pipe ? '--remote-debugging-pipe' : '--remote-debugging-port=0'
-      );
+    ) {
+      if (pipe) {
+        assert(
+          debuggingPort === null,
+          'Browser should be launched with either pipe or debugging port - not both.'
+        );
+        chromeArguments.push('--remote-debugging-pipe');
+      } else {
+        chromeArguments.push(`--remote-debugging-port=${debuggingPort || 0}`);
+      }
+    }
     if (!chromeArguments.some((arg) => arg.startsWith('--user-data-dir'))) {
       temporaryUserDataDir = await mkdtempAsync(profilePath);
       chromeArguments.push(`--user-data-dir=${temporaryUserDataDir}`);
@@ -267,6 +275,7 @@ class FirefoxLauncher implements ProductLauncher {
       timeout = 30000,
       extraPrefsFirefox = {},
       waitForInitialPage = true,
+      debuggingPort = null,
     } = options;
 
     const firefoxArguments = [];
@@ -283,8 +292,15 @@ class FirefoxLauncher implements ProductLauncher {
       !firefoxArguments.some((argument) =>
         argument.startsWith('--remote-debugging-')
       )
-    )
-      firefoxArguments.push('--remote-debugging-port=0');
+    ) {
+      if (pipe) {
+        assert(
+          debuggingPort === null,
+          'Browser should be launched with either pipe or debugging port - not both.'
+        );
+      }
+      firefoxArguments.push(`--remote-debugging-port=${debuggingPort || 0}`);
+    }
 
     let temporaryUserDataDir = null;
 

test/launcher.spec.ts

@@ -440,6 +440,31 @@ describe('Launcher specs', function () {
         expect(screenshot).toBeInstanceOf(Buffer);
         await browser.close();
       });
+      it('should set the debugging port', async () => {
+        const { puppeteer, defaultBrowserOptions } = getTestState();
+
+        const options = Object.assign({}, defaultBrowserOptions, {
+          defaultViewport: null,
+          debuggingPort: 9999,
+        });
+        const browser = await puppeteer.launch(options);
+        const url = new URL(browser.wsEndpoint());
+        await browser.close();
+        expect(url.port).toBe('9999');
+      });
+      it('should not allow setting debuggingPort and pipe', async () => {
+        const { puppeteer, defaultBrowserOptions } = getTestState();
+
+        const options = Object.assign({}, defaultBrowserOptions, {
+          defaultViewport: null,
+          debuggingPort: 9999,
+          pipe: true,
+        });
+
+        let error = null;
+        await puppeteer.launch(options).catch((error_) => (error = error_));
+        expect(error.message).toContain('either pipe or debugging port');
+      });
       itChromeOnly(
         'should launch Chrome properly with --no-startup-window and waitForInitialPage=false',
         async () => {