browser-commander 0.22.0 → 0.24.0

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';

package/tests/e2e/engine-matrix.e2e.test.js

@@ -0,0 +1,107 @@
+/** Native common launch and commander contracts for every JS engine (#124). */
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { describe, it } from 'node:test';
+import { launchBrowser } from '../../src/browser/launcher.js';
+import { makeBrowserCommander } from '../../src/factory.js';
+import {
+  CHROME_LAUNCH_OPTIONS,
+  PARITY_CHROME,
+} from '../helpers/e2e-browser.js';
+
+// feature-parity: engines.webdriver@native-typed engines.cli-matrix@native-typed
+describe('Common native engine API', { skip: !process.env.RUN_E2E }, () => {
+  it(
+    'selenium restores portable cookies and BiDi origin state',
+    { timeout: 60000 },
+    async () => {
+      const server = createServer((_request, response) => {
+        response.end('<title>Portable state</title>');
+      });
+      await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+      const origin = `http://127.0.0.1:${server.address().port}`;
+      let session;
+      try {
+        session = await launchBrowser({
+          engine: 'selenium',
+          launch: 'engine',
+          bidi: true,
+          headless: true,
+          executablePath: PARITY_CHROME,
+          ...CHROME_LAUNCH_OPTIONS,
+          storageState: {
+            cookies: [{ name: 'session', value: 'restored', url: origin }],
+            origins: [
+              { origin, localStorage: [{ name: 'theme', value: 'dark' }] },
+            ],
+          },
+        });
+        await session.page.goto(origin);
+        assert.equal(
+          await session.page.evaluate(() =>
+            globalThis.localStorage.getItem('theme')
+          ),
+          'dark'
+        );
+        assert.match(
+          await session.page.evaluate(() => document.cookie),
+          /session=restored/u
+        );
+      } finally {
+        await session?.close();
+        await new Promise((resolve) => server.close(resolve));
+      }
+    }
+  );
+  for (const engine of ['playwright', 'puppeteer', 'selenium']) {
+    for (const launch of ['real', 'engine']) {
+      it(
+        `${engine}/${launch}: input, click, native handles, PDF, cleanup`,
+        { timeout: 120000 },
+        async () => {
+          const session = await launchBrowser({
+            engine,
+            launch,
+            headless: true,
+            executablePath: PARITY_CHROME,
+            ...CHROME_LAUNCH_OPTIONS,
+          });
+          const commander = makeBrowserCommander({
+            page: session.page,
+            enableNetworkTracking: false,
+            enableNavigationManager: false,
+          });
+          const profile = session.userDataDir;
+          try {
+            assert.equal(commander.engine, engine);
+            await commander.goto({
+              url: `data:text/html,${encodeURIComponent('<input id="name"><button id="go" onclick="document.title=document.querySelector(\'#name\').value">Go</button>')}`,
+            });
+            await commander.fill({ selector: '#name', text: 'Ada' });
+            assert.equal(
+              await commander.inputValue({ selector: '#name' }),
+              'Ada'
+            );
+            await commander.click({ selector: '#go' });
+            assert.equal(await session.page.title(), 'Ada');
+            assert.ok(
+              Buffer.from(await session.page.pdf({ format: 'A4' }))
+                .subarray(0, 5)
+                .equals(Buffer.from('%PDF-'))
+            );
+            if (engine === 'selenium') {
+              assert.equal(await session.driver.getTitle(), 'Ada');
+            }
+          } finally {
+            await commander.destroy();
+            await session.close();
+          }
+          if (session.temporaryProfile) {
+            assert.equal(existsSync(profile), false);
+          }
+        }
+      );
+    }
+  }
+});

package/tests/e2e/playwright.e2e.test.js

@@ -9,6 +9,7 @@
 
 import { describe, it, before, after } from 'node:test';
 import assert from 'node:assert';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
 
 // Dynamic import for playwright since it may not be installed
 let playwright;
@@ -25,23 +26,16 @@ describe(
     const BASE_URL = process.env.TEST_URL || 'http://localhost:3000';
 
     before(async () => {
-      try {
-        playwright = await import('playwright');
-        const module = await import('../../src/index.js');
-        createCommander = module.createCommander;
-
-        browser = await playwright.chromium.launch({
-          headless: process.env.HEADLESS !== 'false',
-        });
-        const context = await browser.newContext();
-        page = await context.newPage();
-        commander = createCommander({ page, verbose: true });
-      } catch (error) {
-        console.log(
-          'Skipping E2E tests - playwright not available or test app not running'
-        );
-        console.log('Error:', error.message);
-      }
+      playwright = await import('playwright');
+      const module = await import('../../src/index.js');
+      createCommander = module.createCommander;
+      browser = await playwright.chromium.launch({
+        headless: process.env.HEADLESS !== 'false',
+        ...CHROME_LAUNCH_OPTIONS,
+      });
+      const context = await browser.newContext();
+      page = await context.newPage();
+      commander = createCommander({ page, verbose: true });
     });
 
     after(async () => {

package/tests/e2e/puppeteer.e2e.test.js

@@ -9,6 +9,7 @@
 
 import { describe, it, before, after } from 'node:test';
 import assert from 'node:assert';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
 
 // Dynamic import for puppeteer since it may not be installed
 let puppeteer;
@@ -22,22 +23,15 @@ describe('E2E Tests - Puppeteer Engine', { skip: !process.env.RUN_E2E }, () => {
   const BASE_URL = process.env.TEST_URL || 'http://localhost:3000';
 
   before(async () => {
-    try {
-      puppeteer = await import('puppeteer');
-      const module = await import('../../src/index.js');
-      createCommander = module.createCommander;
-
-      browser = await puppeteer.default.launch({
-        headless: process.env.HEADLESS !== 'false' ? 'new' : false,
-      });
-      page = await browser.newPage();
-      commander = createCommander({ page, verbose: true });
-    } catch (error) {
-      console.log(
-        'Skipping E2E tests - puppeteer not available or test app not running'
-      );
-      console.log('Error:', error.message);
-    }
+    puppeteer = await import('puppeteer');
+    const module = await import('../../src/index.js');
+    createCommander = module.createCommander;
+    browser = await puppeteer.default.launch({
+      headless: process.env.HEADLESS !== 'false',
+      ...CHROME_LAUNCH_OPTIONS,
+    });
+    page = await browser.newPage();
+    commander = createCommander({ page, verbose: true });
   });
 
   after(async () => {
@@ -352,7 +346,9 @@ describe('E2E Tests - Puppeteer Engine', { skip: !process.env.RUN_E2E }, () => {
       }
 
       // Scroll to specific item
-      await commander.scroll({ selector: '[data-testid="scroll-item-15"]' });
+      await commander.scrollIntoView({
+        locatorOrElement: await page.$('[data-testid="scroll-item-15"]'),
+      });
       await commander.wait({ ms: 500 });
 
       // Target should be visible