browser-commander 0.23.0 → 0.24.0

package/examples/react-test-app/package.json

@@ -9,11 +9,11 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0"
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
   },
   "devDependencies": {
-    "@vitejs/plugin-react": "^4.2.0",
-    "vite": "^5.0.0"
+    "@vitejs/plugin-react": "^6.1.2",
+    "vite": "^8.3.2"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "browser-commander",
-  "version": "0.23.0",
-  "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
+  "version": "0.24.0",
+  "description": "Universal browser automation library that supports Playwright, Puppeteer, and Selenium with a unified API",
   "main": "src/index.js",
   "bin": {
     "browser-commander": "bin/browser-commander.js"
@@ -61,12 +61,12 @@
   },
   "homepage": "https://github.com/link-foundation/browser-commander#readme",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "peerDependencies": {
-    "playwright": ">=1.40.0",
-    "puppeteer": ">=21.0.0",
-    "selenium-webdriver": ">=4.20.0"
+    "playwright": ">=1.63.0",
+    "puppeteer": ">=25.12.0",
+    "selenium-webdriver": ">=4.50.0"
   },
   "peerDependenciesMeta": {
     "playwright": {
@@ -81,24 +81,24 @@
   },
   "dependencies": {
     "better-sqlite3": "^13.0.3",
-    "command-stream": "^1.2.0",
-    "links-notation": "^0.20.0",
+    "command-stream": "^1.4.0",
+    "links-notation": "^0.22.0",
     "log-lazy": "^1.0.4",
     "test-anywhere": "^0.9.1"
   },
   "devDependencies": {
-    "@changesets/cli": "^3.0.2",
+    "@changesets/cli": "^3.0.3",
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.10.0",
+    "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.6",
-    "jscpd": "^5.1.2",
-    "jsdoc": "^4.0.4",
-    "playwright": "^1.62.1",
-    "prettier": "^3.9.6",
-    "puppeteer": "^25.10.0",
-    "selenium-webdriver": "^4.49.0",
-    "typescript": "^5.9.3",
+    "jscpd": "^5.4.0",
+    "jsdoc": "^4.0.5",
+    "playwright": "^1.63.0",
+    "prettier": "^3.9.9",
+    "puppeteer": "^25.12.0",
+    "selenium-webdriver": "^4.50.0",
+    "typescript": "^7.0.2",
     "yaml": "^2.9.1"
   },
   "allowScripts": {

package/src/browser/connector.js

@@ -1,8 +1,10 @@
 import { attachDownloads } from '../downloads/attach.js';
+import { connectWebDriver, launchWebDriver } from './webdriver.js';
 import {
   loadStorageState,
   restorePlaywrightStorageState,
   restorePuppeteerStorageState,
+  restoreWebDriverStorageState,
 } from './storage-state.js';
 
 /**
@@ -11,9 +13,9 @@ import {
  * @param {string} engine
  */
 export function assertSupportedEngine(engine) {
-  if (!['playwright', 'puppeteer'].includes(engine)) {
+  if (!['playwright', 'puppeteer', 'selenium'].includes(engine)) {
     throw new Error(
-      `Invalid engine: ${engine}. Expected 'playwright' or 'puppeteer'`
+      `Invalid engine: ${engine}. Expected 'playwright', 'puppeteer' or 'selenium'`
     );
   }
 }
@@ -28,6 +30,28 @@ function validateConnectionOptions({ engine, cdpEndpoint, wsEndpoint }) {
   }
 }
 
+async function connectSelenium(options, dependencies) {
+  if (Boolean(options.serverUrl) === Boolean(options.cdpEndpoint)) {
+    throw new Error(
+      'selenium requires exactly one of serverUrl or cdpEndpoint'
+    );
+  }
+  if (options.wsEndpoint) {
+    throw new Error('selenium requires an HTTP cdpEndpoint or serverUrl');
+  }
+  const connected = options.serverUrl
+    ? await (dependencies.connectWebDriver ?? connectWebDriver)(options)
+    : await (dependencies.launchWebDriver ?? launchWebDriver)({
+        ...options,
+        debuggerAddress: new URL(options.cdpEndpoint).host,
+      });
+  return {
+    ...connected,
+    browser: connected.driver,
+    disconnect: connected.close,
+  };
+}
+
 function addDefinedOptions(options, values) {
   for (const [key, value] of Object.entries(values)) {
     if (value !== undefined) {
@@ -135,10 +159,12 @@ async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
 }
 
 /**
- * Attach to an already-running Chromium-family browser over CDP.
+ * Attach over CDP or create a native session on a WebDriver server.
  *
  * @param {Object} options - Connection options
- * @param {'playwright'|'puppeteer'} [options.engine='playwright'] - Automation engine
+ * @param {'playwright'|'puppeteer'|'selenium'} [options.engine='playwright'] - Automation engine
+ * @param {string} [options.serverUrl] - Selenium Grid or WebDriver server URL
+ * @param {Object} [options.capabilities] - Native WebDriver capabilities
  * @param {string} [options.cdpEndpoint] - HTTP DevTools endpoint, such as http://127.0.0.1:9222
  * @param {string} [options.wsEndpoint] - DevTools browser WebSocket endpoint
  * @param {number} [options.slowMo] - Delay engine operations by this many milliseconds
@@ -171,6 +197,22 @@ export async function connectBrowserWithDependencies(
     verbose: false,
     ...options,
   };
+  if (normalizedOptions.engine === 'selenium') {
+    assertSupportedEngine(normalizedOptions.engine);
+    const storageState = await prepareStorageState(normalizedOptions);
+    const result = await connectSelenium(normalizedOptions, dependencies);
+    try {
+      await restoreWebDriverStorageState({ page: result.page, storageState });
+      const downloads = await attachDownloads({
+        ...normalizedOptions,
+        ...result,
+      });
+      return { ...result, downloads };
+    } catch (error) {
+      await result.close();
+      throw error;
+    }
+  }
   validateConnectionOptions(normalizedOptions);
 
   const storageState = await prepareStorageState(normalizedOptions);

package/src/browser/launcher.js

@@ -16,10 +16,12 @@ import { resolveRestrictions } from './restrictions.js';
 import { resolveSystemBrowserExecutable } from './system-browser.js';
 import { applyFingerprint } from '../fingerprint/apply.js';
 import { attachDownloads } from '../downloads/attach.js';
+import { launchWebDriver } from './webdriver.js';
 import {
   loadStorageState,
   restorePlaywrightStorageState,
   restorePuppeteerStorageState,
+  restoreWebDriverStorageState,
 } from './storage-state.js';
 
 /** How `launchBrowser` starts the browser (issue #103). */
@@ -131,6 +133,13 @@ async function launchReal(options, dependencies) {
 }
 
 async function launchWithEngine(options, dependencies) {
+  if (options.engine === 'selenium') {
+    const launched = await (dependencies.launchWebDriver ?? launchWebDriver)({
+      ...options,
+      args: [...options.args, ...options.extraArgs],
+    });
+    return { ...launched, browser: launched.driver };
+  }
   const {
     engine,
     userDataDir: requestedUserDataDir,
@@ -261,7 +270,7 @@ async function unfocusAddressBar(page, verbose, settleMs = 500) {
  * limitations.json (`engine-launch-switches`).
  *
  * @param {Object} options - Configuration options
- * @param {string} [options.engine='playwright'] - Browser automation engine: 'playwright' or 'puppeteer'
+ * @param {string} [options.engine='playwright'] - Browser automation engine: 'playwright', 'puppeteer' or 'selenium'
  * @param {'real'|'engine'} [options.launch='real'] - Who starts the browser: Browser Commander (a hand-started command line) or the automation engine
  * @param {string} [options.userDataDir] - Persistent profile directory. When omitted a fresh temporary profile is created and deleted on close.
  * @param {boolean} [options.headless=false] - Run in headless mode
@@ -309,6 +318,16 @@ export async function launchBrowserWithDependencies(
     ...rest
   } = options;
   validateLaunchMode({ engine, launch, attach: rest.attach });
+  if (engine === 'selenium') {
+    if (colorScheme !== undefined || fingerprint !== undefined || downloads) {
+      throw new Error(
+        'selenium does not support CDP emulation, fingerprint overrides or managed downloads (webdriver-no-cdp-emulation)'
+      );
+    }
+    if (launch === 'real' && rest.browser === 'firefox') {
+      throw new Error("selenium Firefox requires launch: 'engine'");
+    }
+  }
   // Validate arguments before anything is started or written to disk.
   resolveChromeArgs({ args, extraArgs, ignoreDefaultArgs, restrictions });
   const resolvedStorageState = await loadStorageState(storageState);
@@ -341,6 +360,12 @@ export async function launchBrowserWithDependencies(
   }
 
   try {
+    if (engine === 'selenium' && launch === 'engine') {
+      await restoreWebDriverStorageState({
+        page,
+        storageState: resolvedStorageState,
+      });
+    }
     // A Playwright-launched context applies colorScheme itself; an attached
     // browser and Puppeteer need page-level emulation.
     const emulateColorScheme =

package/src/browser/real-browser.js

@@ -259,6 +259,10 @@ async function waitForExit(browserProcess, timeout) {
 }
 
 async function requestBrowserClose({ engine, browser, originalClose }) {
+  if (engine === 'selenium') {
+    await originalClose();
+    return;
+  }
   if (engine === 'puppeteer') {
     // A connected Puppeteer Browser sends Browser.close and waits for it.
     await originalClose.call(browser);
@@ -278,8 +282,9 @@ function createCloser({
   userDataDir,
   temporaryProfile,
   closeTimeout,
+  closeConnection,
 }) {
-  const originalClose = browser?.close;
+  const originalClose = closeConnection ?? browser?.close;
   let closing;
   const close = () => {
     closing ??= (async () => {
@@ -298,7 +303,7 @@ function createCloser({
     })();
     return closing;
   };
-  if (browser && originalClose) {
+  if (browser && originalClose && engine !== 'selenium') {
     // `browser.close()` means "close the browser" for every caller, so it
     // shuts the spawned process down and deletes a temporary profile too.
     browser.close = close;
@@ -670,6 +675,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
       userDataDir,
       temporaryProfile,
       closeTimeout,
+      closeConnection: engine === 'selenium' ? connection.close : undefined,
     });
     return {
       ...connection,

package/src/browser/storage-state.js

@@ -30,6 +30,33 @@ function restoreOriginLocalStorage(origins) {
   }
 }
 
+/** Restore classic WebDriver cookies; origin preload scripts require BiDi. */
+export async function restoreWebDriverStorageState({ page, storageState }) {
+  if (!storageState) {
+    return;
+  }
+  const origins = storageState.origins ?? [];
+  if (origins.length) {
+    await page.evaluateOnNewDocument(restoreOriginLocalStorage, origins);
+    await page.evaluate(restoreOriginLocalStorage, origins);
+  }
+  const originalUrl = page.url();
+  const cookies = storageState.cookies ?? [];
+  try {
+    for (const cookie of cookies) {
+      const origin = cookie.url
+        ? new URL(cookie.url).origin
+        : `${cookie.secure ? 'https' : 'http'}://${cookie.domain.replace(/^\./u, '')}`;
+      await page.goto(origin);
+      await page.setCookie(cookie);
+    }
+  } finally {
+    if (cookies.length) {
+      await page.goto(originalUrl);
+    }
+  }
+}
+
 /**
  * Apply Playwright-compatible storage state to a Puppeteer page.
  * @param {Object} options - Restore options

package/src/browser/webdriver.js

@@ -302,11 +302,20 @@ export function buildBrowserOptions({
   args,
   automationParity,
   bidi,
+  debuggerAddress,
 }) {
   let options;
   let browserArgs;
   if (browser === 'chrome') {
     options = new selenium.chrome.Options();
+    if (debuggerAddress) {
+      options.debuggerAddress(debuggerAddress);
+      if (bidi) {
+        options.set('webSocketUrl', true);
+        options.set('unhandledPromptBehavior', 'ignore');
+      }
+      return { options, args: [] };
+    }
     browserArgs = buildRealBrowserArgs({
       userDataDir,
       remoteDebuggingPort,
@@ -450,8 +459,12 @@ export async function launchWebDriver(options = {}, dependencies = {}) {
     env,
     startupTimeout = 30_000,
     verbose = false,
+    debuggerAddress,
   } = options;
   assertBrowser(browser);
+  if (debuggerAddress && browser !== 'chrome') {
+    throw new Error('debuggerAddress is only supported by Chrome WebDriver');
+  }
   if (browser === 'firefox' && restrictions.length > 0) {
     throw new Error(
       'Launch restrictions are Chrome switches; not available for firefox'
@@ -476,8 +489,10 @@ export async function launchWebDriver(options = {}, dependencies = {}) {
     ...(dependencies.platform ? { platform: dependencies.platform } : {}),
   });
 
-  const temporaryProfile = !requestedUserDataDir;
-  const userDataDir = await resolveProfile(browser, requestedUserDataDir);
+  const temporaryProfile = !debuggerAddress && !requestedUserDataDir;
+  const userDataDir = debuggerAddress
+    ? undefined
+    : await resolveProfile(browser, requestedUserDataDir);
   const childEnv = driverEnvironment(restrictions, env);
 
   let driverProcess;
@@ -513,6 +528,7 @@ export async function launchWebDriver(options = {}, dependencies = {}) {
       args,
       automationParity,
       bidi,
+      debuggerAddress,
     });
     driver = await buildSession({
       selenium,

package/src/cli/args.js

@@ -31,12 +31,15 @@ const BROWSER_OPTIONS = Object.freeze({
   'local-state': STRINGS,
   'default-browser-check': FLAG,
   'first-run': FLAG,
+  'driver-path': STRING,
+  bidi: FLAG,
 });
 
 /** Options accepted by every page command. */
 const PAGE_OPTIONS = Object.freeze({
   ...BROWSER_OPTIONS,
   'cdp-endpoint': STRING,
+  'server-url': STRING,
   url: STRING,
 });
 
@@ -248,6 +251,8 @@ export function launchParams(options) {
     localState: settings(options.localState, '--local-state'),
     defaultBrowserCheck: options.defaultBrowserCheck,
     firstRun: options.firstRun,
+    driverPath: options.driverPath,
+    bidi: options.bidi,
   };
   return Object.fromEntries(
     Object.entries(params).filter(([, value]) => value !== undefined)

package/src/cli/commands.js

@@ -75,12 +75,16 @@ async function withPageSession(parsed, io, work, { skipUrl = false } = {}) {
   const { options } = parsed;
   const dispatcher = createDispatcher({ dependencies: io.dependencies });
   try {
-    const opened = options.cdpEndpoint
-      ? await dispatcher.dispatch('session.connect', {
-          cdpEndpoint: options.cdpEndpoint,
-          engine: options.engine,
-        })
-      : await dispatcher.dispatch('session.launch', launchParams(options));
+    const opened =
+      options.cdpEndpoint || options.serverUrl
+        ? await dispatcher.dispatch('session.connect', {
+            cdpEndpoint: options.cdpEndpoint,
+            engine: options.engine,
+            ...(options.serverUrl ? { serverUrl: options.serverUrl } : {}),
+            ...(options.driverPath ? { driverPath: options.driverPath } : {}),
+            ...(options.bidi !== undefined ? { bidi: options.bidi } : {}),
+          })
+        : await dispatcher.dispatch('session.launch', launchParams(options));
     if (options.url && !skipUrl) {
       await dispatcher.dispatch('page.goto', {
         session: opened.session,

package/src/cli/handle-methods.js

@@ -9,7 +9,7 @@
 import { decodeValue, describeObject, encodeValue } from './handles.js';
 import { invalidParams, requireString } from './rpc-error.js';
 
-const ENGINE_ROOTS = Object.freeze(['playwright', 'puppeteer']);
+const ENGINE_ROOTS = Object.freeze(['playwright', 'puppeteer', 'selenium']);
 
 function targetOf(state, params) {
   const handle = params.handle;
@@ -36,11 +36,14 @@ async function root(state, params) {
       browser: handleOrNull(state, session.browser),
       context: handleOrNull(state, session.context),
       page: handleOrNull(state, session.page),
+      ...(session.engine === 'selenium'
+        ? { driver: handleOrNull(state, session.driver) }
+        : {}),
     };
   }
   if (!ENGINE_ROOTS.includes(name)) {
     throw invalidParams(
-      `Unknown root "${name}"; expected playwright, puppeteer or session:<id>`
+      `Unknown root "${name}"; expected playwright, puppeteer, selenium or session:<id>`
     );
   }
   const module = await state.dependencies.loadEngine(name);
@@ -71,6 +74,19 @@ async function get(state, params) {
   );
 }
 
+/** Instantiate an engine constructor obtained through `handle.get`. */
+function construct(state, params) {
+  const target = targetOf(state, params);
+  const args = params.args ?? [];
+  if (typeof target !== 'function' || !Array.isArray(args)) {
+    throw invalidParams(
+      'handle.construct requires a constructor handle and an args array'
+    );
+  }
+  const result = Reflect.construct(target, decodeValue(args, state.handles));
+  return encodeValue(result, state.handles);
+}
+
 function dispose(state, params) {
   const id =
     typeof params.handle === 'object' && params.handle
@@ -129,6 +145,7 @@ export const HANDLE_METHODS = Object.freeze({
   'handle.root': root,
   'handle.call': call,
   'handle.get': get,
+  'handle.construct': construct,
   'handle.dispose': dispose,
   'handle.describe': describe,
   'events.subscribe': subscribe,

package/src/cli/high-level-methods.js

@@ -37,14 +37,27 @@ async function launchSession(state, params) {
 }
 
 async function connectSession(state, params) {
-  const cdpEndpoint = requireString(params, 'cdpEndpoint');
   const engine = resolveEngine(params.engine);
+  const endpoint =
+    engine === 'selenium' && params.serverUrl !== undefined
+      ? {
+          serverUrl: requireString(params, 'serverUrl'),
+          capabilities: params.capabilities,
+        }
+      : { cdpEndpoint: requireString(params, 'cdpEndpoint') };
   const connected = await state.dependencies.connectBrowser({
     engine,
-    cdpEndpoint,
+    ...endpoint,
+    ...(params.driverPath ? { driverPath: params.driverPath } : {}),
+    ...(params.bidi !== undefined ? { bidi: params.bidi } : {}),
   });
   const session = state.sessions.add(sessionFromConnect(engine, connected));
-  return { session, cdpEndpoint };
+  return {
+    session,
+    ...(endpoint.serverUrl
+      ? { serverUrl: endpoint.serverUrl }
+      : { cdpEndpoint: endpoint.cdpEndpoint }),
+  };
 }
 
 async function closeSession(state, params) {
@@ -70,6 +83,10 @@ async function fill(state, params) {
   const { engine, page } = sessionOf(state, params);
   if (engine === 'playwright') {
     await page.fill(selector, value);
+  } else if (engine === 'selenium') {
+    const element = await page.waitForSelector(selector, { visible: true });
+    await element.clear();
+    await element.sendKeys(value);
   } else {
     await page.locator(selector).fill(value);
   }

package/src/cli/modules.js

@@ -70,7 +70,11 @@ export const DEFAULT_DEPENDENCIES = Object.freeze({
     (await import('../browser/browser-profiles.js')).listBrowserProfiles(
       options
     ),
-  loadEngine: (name) => importOptional(name, `The ${name} engine`),
+  loadEngine: (name) =>
+    importOptional(
+      name === 'selenium' ? 'selenium-webdriver' : name,
+      `The ${name} engine`
+    ),
   openInUserBrowser: async (url) =>
     (
       await importOptional(

package/src/cli/sessions.js

@@ -14,7 +14,7 @@ export const BROWSER_CHANNELS = Object.freeze({
   chromium: 'chromium',
 });
 
-const ENGINES = Object.freeze(['playwright', 'puppeteer']);
+const ENGINES = Object.freeze(['playwright', 'puppeteer', 'selenium']);
 
 /**
  * Launch options that are forwarded to `launchBrowser()` as they are, so the
@@ -38,6 +38,8 @@ const LAUNCH_PASSTHROUGH = Object.freeze([
   'localState',
   'defaultBrowserCheck',
   'firstRun',
+  'driverPath',
+  'bidi',
 ]);
 
 /** Validate an engine name, defaulting to Playwright. */
@@ -85,13 +87,17 @@ export function buildLaunchOptions(params = {}) {
     engine: resolveEngine(params.engine),
     headless: params.headless === true,
   };
-  const channel = resolveChannel(params.browser);
+  const channel =
+    options.engine === 'selenium' ? undefined : resolveChannel(params.browser);
   const defined = {
     launch: params.launch,
     executablePath: params.executablePath,
     userDataDir: params.userDataDir,
     restrictions: params.restrictions,
     channel,
+    ...(options.engine === 'selenium' && params.browser !== undefined
+      ? { browser: params.browser }
+      : {}),
   };
   for (const name of LAUNCH_PASSTHROUGH) {
     defined[name] ??= params[name];
@@ -121,6 +127,7 @@ export function sessionFromLaunch(engine, launched) {
       : handle,
     context: playwright ? handle : (handle?.defaultBrowserContext?.() ?? null),
     page: launched.page,
+    driver: launched.driver ?? (engine === 'selenium' ? handle : null),
     args: launched.args ?? [],
     close: () => launched.close(),
     connected: false,
@@ -141,10 +148,15 @@ export function sessionFromConnect(engine, connected) {
       ? (page?.context?.() ?? null)
       : (browser?.defaultBrowserContext?.() ?? null),
     page,
+    driver: connected.driver ?? null,
     // Playwright's close() on a connectOverCDP browser disconnects;
     // Puppeteer's close() would quit the browser, disconnect() does not.
     close: async () => {
       await connected.downloads?.dispose?.();
+      if (engine === 'selenium') {
+        await connected.close();
+        return;
+      }
       await (playwright ? browser.close() : browser.disconnect());
     },
     connected: true,

package/src/tests/index.js

@@ -57,6 +57,7 @@ export {
 export const SUPPORTED_BROWSER_TEST_ENGINES = Object.freeze([
   'playwright',
   'puppeteer',
+  'selenium',
 ]);
 
 export const DEFAULT_TIMINGS_FILENAME = '.browser-commander-test-timings.json';