browser-commander 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.10.0
+
+### Minor Changes
+
+- fe688ac: Add `channel` and `executablePath` launch options for reusing an installed Chrome-family browser.
+
 ## 0.9.1
 
 ### Patch Changes

package/README.md

@@ -87,6 +87,19 @@ await commander.destroy();
 await browser.close();
 ```
 
+To reuse an installed Chrome-family browser instead of downloading the
+engine's bundled Chromium, select a browser channel or provide its executable
+path. Both options are passed directly to Playwright or Puppeteer:
+
+```javascript
+const { browser, page } = await launchBrowser({
+  engine: 'playwright',
+  channel: 'chrome',
+  // Or: executablePath: '/usr/bin/google-chrome',
+  headless: true,
+});
+```
+
 ## Browser Commander Tests
 
 `browser-commander/tests` adds browser fixtures and scheduling helpers on top of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",

package/src/browser/launch-options.js

@@ -0,0 +1,51 @@
+function setBrowserSelectionOptions(options, { channel, executablePath }) {
+  if (channel !== undefined) {
+    options.channel = channel;
+  }
+  if (executablePath !== undefined) {
+    options.executablePath = executablePath;
+  }
+  return options;
+}
+
+export function buildPlaywrightLaunchOptions({
+  headless,
+  slowMo,
+  chromeArgs,
+  colorScheme,
+  channel,
+  executablePath,
+}) {
+  const options = {
+    headless,
+    slowMo,
+    chromiumSandbox: true,
+    viewport: null,
+    args: chromeArgs,
+    ignoreDefaultArgs: ['--enable-automation'],
+  };
+
+  if (colorScheme !== undefined) {
+    options.colorScheme = colorScheme;
+  }
+
+  return setBrowserSelectionOptions(options, { channel, executablePath });
+}
+
+export function buildPuppeteerLaunchOptions({
+  headless,
+  chromeArgs,
+  userDataDir,
+  channel,
+  executablePath,
+}) {
+  return setBrowserSelectionOptions(
+    {
+      headless,
+      defaultViewport: null,
+      args: ['--start-maximized', ...chromeArgs],
+      userDataDir,
+    },
+    { channel, executablePath }
+  );
+}

package/src/browser/launcher.js

@@ -3,6 +3,10 @@ import os from 'os';
 import { CHROME_ARGS } from '../core/constants.js';
 import { disableTranslateInPreferences } from '../core/preferences.js';
 import { emulateMedia } from './media.js';
+import {
+  buildPlaywrightLaunchOptions,
+  buildPuppeteerLaunchOptions,
+} from './launch-options.js';
 
 /**
  * Launch browser with default configuration
@@ -14,6 +18,8 @@ import { emulateMedia } from './media.js';
  * @param {boolean} options.verbose - Enable verbose logging (default: false)
  * @param {string[]} options.args - Custom Chrome arguments to append to the default CHROME_ARGS
  * @param {string|null} [options.colorScheme] - Emulate color scheme: 'light', 'dark', 'no-preference', or null to reset
+ * @param {string} [options.channel] - Installed browser channel, such as 'chrome', 'chrome-beta', or 'msedge'
+ * @param {string} [options.executablePath] - Explicit path to a Chrome or Chromium executable
  * @returns {Promise<Object>} - Object with browser and page
  */
 export async function launchBrowser(options = {}) {
@@ -25,6 +31,8 @@ export async function launchBrowser(options = {}) {
     verbose = false,
     args = [],
     colorScheme,
+    channel,
+    executablePath,
   } = options;
 
   // Combine default CHROME_ARGS with custom args
@@ -53,18 +61,14 @@ export async function launchBrowser(options = {}) {
 
   if (engine === 'playwright') {
     const { chromium } = await import('playwright');
-    const contextOptions = {
+    const contextOptions = buildPlaywrightLaunchOptions({
       headless,
       slowMo,
-      chromiumSandbox: true,
-      viewport: null,
-      args: chromeArgs,
-      ignoreDefaultArgs: ['--enable-automation'],
-    };
-    // Playwright supports colorScheme as a context-level launch option
-    if (colorScheme !== undefined) {
-      contextOptions.colorScheme = colorScheme;
-    }
+      chromeArgs,
+      colorScheme,
+      channel,
+      executablePath,
+    });
     browser = await chromium.launchPersistentContext(
       userDataDir,
       contextOptions
@@ -72,12 +76,15 @@ export async function launchBrowser(options = {}) {
     page = browser.pages()[0];
   } else {
     const puppeteer = await import('puppeteer');
-    browser = await puppeteer.default.launch({
-      headless,
-      defaultViewport: null,
-      args: ['--start-maximized', ...chromeArgs],
-      userDataDir,
-    });
+    browser = await puppeteer.default.launch(
+      buildPuppeteerLaunchOptions({
+        headless,
+        chromeArgs,
+        userDataDir,
+        channel,
+        executablePath,
+      })
+    );
     const pages = await browser.pages();
     page = pages[0];
   }

package/tests/unit/browser/launch-options.test.js

@@ -0,0 +1,53 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import {
+  buildPlaywrightLaunchOptions,
+  buildPuppeteerLaunchOptions,
+} from '../../../src/browser/launch-options.js';
+
+describe('browser launch options', () => {
+  it('forwards channel and executablePath to Playwright', () => {
+    const options = buildPlaywrightLaunchOptions({
+      headless: true,
+      slowMo: 25,
+      chromeArgs: ['--custom'],
+      channel: 'chrome-beta',
+      executablePath: '/opt/google/chrome-beta',
+    });
+
+    assert.equal(options.channel, 'chrome-beta');
+    assert.equal(options.executablePath, '/opt/google/chrome-beta');
+  });
+
+  it('forwards channel and executablePath to Puppeteer', () => {
+    const options = buildPuppeteerLaunchOptions({
+      headless: true,
+      chromeArgs: ['--custom'],
+      userDataDir: '/tmp/browser-commander-test',
+      channel: 'chrome',
+      executablePath: '/usr/bin/google-chrome',
+    });
+
+    assert.equal(options.channel, 'chrome');
+    assert.equal(options.executablePath, '/usr/bin/google-chrome');
+  });
+
+  it('omits browser selection options by default', () => {
+    const playwright = buildPlaywrightLaunchOptions({
+      headless: false,
+      slowMo: 150,
+      chromeArgs: [],
+    });
+    const puppeteer = buildPuppeteerLaunchOptions({
+      headless: false,
+      chromeArgs: [],
+      userDataDir: '/tmp/browser-commander-test',
+    });
+
+    assert.equal('channel' in playwright, false);
+    assert.equal('executablePath' in playwright, false);
+    assert.equal('channel' in puppeteer, false);
+    assert.equal('executablePath' in puppeteer, false);
+  });
+});