feat: allow port option when run with target chromium

src/cmd/run.js

@@ -48,6 +48,7 @@ export default async function run(
     firefoxApkComponent,
     // Chromium CLI options.
     chromiumBinary,
+    chromiumPort,
     chromiumProfile,
   },
   {
@@ -186,6 +187,7 @@ export default async function run(
     const chromiumRunnerParams = {
       ...commonRunnerParams,
       chromiumBinary,
+      chromiumPort,
       chromiumProfile,
     };
 

src/errors.js

@@ -54,6 +54,22 @@ export class MultiExtensionsReloadError extends WebExtError {
   }
 }
 
+export class UnusablePortError extends WebExtError {
+  constructor(message) {
+    super(message);
+  }
+}
+export class PortInUseError extends UnusablePortError {
+  constructor(message = 'The requested port is in use by another process') {
+    super(message);
+  }
+}
+export class PortInvalidError extends UnusablePortError {
+  constructor(message = 'The requested port cannot be used.') {
+    super(message);
+  }
+}
+
 /*
  * Sugar-y way to catch only instances of a certain error.
  *

src/extension-runners/chromium.js

@@ -17,6 +17,8 @@ import { createLogger } from '../util/logger.js';
 import { TempDir } from '../util/temp-dir.js';
 import isDirectory from '../util/is-directory.js';
 import fileExists from '../util/file-exists.js';
+import { validatePort } from '../util/verify-chromium-port.js';
+import { PortInUseError, PortInvalidError } from '../errors.js';
 
 const log = createLogger(import.meta.url);
 
@@ -151,6 +153,18 @@ export class ChromiumExtensionRunner {
       chromeFlags.push(...this.params.args);
     }
 
+    const { chromiumPort } = this.params;
+    if (chromiumPort) {
+      log.debug('(port: %d)', chromiumPort);
+      const isPortUsable = await validatePort(chromiumPort).catch((error) => {
+        throw new PortInvalidError(error.message);
+      });
+
+      if (!isPortUsable) {
+        throw new PortInUseError();
+      }
+    }
+
     // eslint-disable-next-line prefer-const
     let { userDataDir, profileDirName } =
       await ChromiumExtensionRunner.getProfilePaths(
@@ -210,8 +224,8 @@ export class ChromiumExtensionRunner {
       userDataDir,
       // Ignore default flags to keep the extension enabled.
       ignoreDefaultFlags: true,
+      port: chromiumPort,
     });
-
     this.chromiumInstance.process.once('close', () => {
       this.chromiumInstance = null;
 

src/util/verify-chromium-port.js

@@ -0,0 +1,52 @@
+import { createServer } from 'node:http';
+
+import { UnusablePortError } from '../errors.js';
+
+/**
+ * Determine if a port is available
+ * @param {number} port Port to test
+ * */
+async function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.once('error', () => resolve(false));
+    server.listen(port);
+  });
+}
+
+/**
+ * Validate that requested port is a valid port
+ * @param {number} port Debugging port
+ * @returns {boolean}
+ */
+function isPortValid(port) {
+  if (!port) {
+    return false;
+  }
+  if (Number.isNaN(port) || !Number.isInteger(port)) {
+    throw new UnusablePortError(`Port provided is not an integer (${port})`);
+  }
+  if (port < 0 || port > 65535) {
+    throw new UnusablePortError(`Invalid port number: ${port}`);
+  }
+
+  return true;
+}
+
+/**
+ * Validate user-supplied port to ensure it is suitable for use
+ * @param {number} port User-supplied port request
+ * @param {string} chromiumBinary Chromium binary being requested for launch
+ * @param {string[]} chromeFlags Array of flags requested for launch
+ * @returns {boolean} Whether requested port is usable
+ */
+export async function validatePort(port) {
+  if (!isPortValid(port)) {
+    return false;
+  }
+
+  return isPortAvailable(port);
+}

tests/unit/helpers.js

@@ -193,6 +193,15 @@ export class StubChildProcess extends EventEmitter {
   stderr = new EventEmitter();
   stdout = new EventEmitter();
   kill = sinon.spy(() => {});
+
+  constructor(params = {}) {
+    super();
+
+    // mimic chrome-launch and set a port property, defaulting to a random port
+    this.port = params.chromiumPort
+      ? params.chromiumPort
+      : getRandomInt(1024, 65536);
+  }
 }
 
 export function createFakeProcess() {
@@ -336,3 +345,9 @@ export function mockModule({
 export function resetMockModules() {
   td.reset();
 }
+
+export function getRandomInt(min, max) {
+  const _min = Math.ceil(min);
+  const _max = Math.floor(max);
+  return Math.floor(Math.random() * (_max - _min) + _min);
+}

tests/unit/test-extension-runners/test.chromium.js

@@ -23,7 +23,7 @@ import isDirectory from '../../../src/util/is-directory.js';
 
 function prepareExtensionRunnerParams({ params } = {}) {
   const fakeChromeInstance = {
-    process: new StubChildProcess(),
+    process: new StubChildProcess(params),
     kill: sinon.spy(async () => {}),
   };
   const runnerParams = {
@@ -615,6 +615,36 @@ describe('util/extension-runners/chromium', async () => {
       }),
   );
 
+  it('does pass port to chrome', async () => {
+    const port = 9222;
+    const { params } = prepareExtensionRunnerParams({
+      params: { chromiumPort: port },
+    });
+
+    const runnerInstance = new ChromiumExtensionRunner(params);
+    await runnerInstance.run();
+
+    sinon.assert.calledOnce(params.chromiumLaunch);
+    sinon.assert.calledWithMatch(params.chromiumLaunch, {
+      port,
+    });
+    assert.isDefined(
+      runnerInstance.chromiumInstance,
+      'returned process instance',
+    );
+    assert.isDefined(
+      runnerInstance.chromiumInstance.process.port,
+      'process instance has port value',
+    );
+    assert.equal(
+      runnerInstance.chromiumInstance.process.port,
+      port,
+      'process instance configured with correct port',
+    );
+
+    await runnerInstance.exit();
+  });
+
   describe('reloadAllExtensions', () => {
     let runnerInstance;
     let wsClient;