browser-commander 0.19.0 → 0.21.0

package/src/downloads/attach.js

@@ -47,6 +47,12 @@ export function attachDownloads({ engine, browser, page, downloads, log }) {
   if (!managerOptions) {
     return null;
   }
+  if (engine === 'selenium') {
+    throw new Error(
+      'Managed downloads are not available with the selenium engine: they ' +
+        'are driven by CDP download events (see the webdriver-no-cdp-emulation limitation)'
+    );
+  }
 
   return createDownloadManager({
     engine,

package/src/downloads/manager.js

@@ -22,6 +22,7 @@ import {
 import {
   attachCdpSource,
   attachPlaywrightSource,
+  browserContextIdForPage,
   classifyFailure,
   DOWNLOAD_FAILURE,
   openBrowserCdpSession,
@@ -308,17 +309,25 @@ export async function createDownloadManager(options = {}) {
   try {
     cdpSession = await openBrowserCdpSession({ engine, browser, page });
     if (cdpSession) {
+      const browserContextId = await browserContextIdForPage({
+        engine,
+        browser,
+        page,
+        browserSession: cdpSession,
+      });
       attached.push(
         await attachCdpSource({
           session: cdpSession,
           root,
           sink,
+          browserContextId,
           stagingTimeout,
           stagingPollInterval,
         })
       );
     }
   } catch (error) {
+    await cdpSession?.detach?.().catch?.(() => {});
     cdpSession = undefined;
     log?.warn?.(`manual downloads are not observable: ${error.message}`);
   }

package/src/downloads/sources.js

@@ -92,6 +92,7 @@ export function attachPlaywrightSource({ context, sink }) {
  * @param {Object} options.session - CDP session with Browser domain access
  * @param {string} options.root - Managed download directory
  * @param {Object} options.sink - `{started, finished, failed, track}` callbacks
+ * @param {string} [options.browserContextId] - Chromium context to configure
  * @param {number} [options.stagingTimeout] - Budget for the bytes to land on disk
  * @param {number} [options.stagingPollInterval] - Milliseconds between readings
  * @returns {Promise<Object>} Handle with `detach()` and `stagingDirectory`
@@ -100,6 +101,7 @@ export async function attachCdpSource({
   session,
   root,
   sink,
+  browserContextId,
   stagingTimeout,
   stagingPollInterval,
 }) {
@@ -116,6 +118,7 @@ export async function attachCdpSource({
     behavior: 'allowAndName',
     downloadPath: stagingDirectory,
     eventsEnabled: true,
+    ...(browserContextId ? { browserContextId } : {}),
   });
 
   const byGuid = new Map();
@@ -200,6 +203,74 @@ export async function attachCdpSource({
   };
 }
 
+/**
+ * Read the Chromium browser-context id that owns a page.
+ *
+ * `Browser.setDownloadBehavior` is sent over a browser-wide session so its
+ * events cover the whole browser, but omitting `browserContextId` configures
+ * only Chromium's default context. Playwright's `browser.newPage()` convenience
+ * API creates a non-default context, whose id is exposed by its target.
+ *
+ * @param {Object} options - Browser handles
+ * @param {string} options.engine - Engine name
+ * @param {Object} [options.browser] - Browser or persistent context
+ * @param {Object} [options.page] - Page whose context downloads belong to
+ * @param {Object} [options.browserSession] - Browser-wide CDP session
+ * @returns {Promise<string|undefined>} Chromium context id, when non-default
+ */
+export async function browserContextIdForPage({
+  engine,
+  browser,
+  page,
+  browserSession,
+}) {
+  if (engine !== 'playwright' || !page) {
+    return undefined;
+  }
+
+  const context = page.context?.() ?? browser;
+  // Playwright exposes a persistent context as the browser's default context:
+  // unlike browser.newContext(), its `browser()` is null. Keeping the id
+  // absent preserves default-context behavior, including downloads from tabs
+  // opened outside the automation.
+  if (typeof context?.browser === 'function' && !context.browser()) {
+    return undefined;
+  }
+  const pageSession = await context?.newCDPSession?.(page);
+  if (!pageSession) {
+    return undefined;
+  }
+
+  let browserContextId;
+  try {
+    const { targetInfo } = await pageSession.send('Target.getTargetInfo');
+    browserContextId = targetInfo?.browserContextId || undefined;
+  } finally {
+    // This session exists only for target metadata. A failure to detach it
+    // must not discard the id that lets the long-lived source work correctly.
+    await pageSession.detach?.().catch?.(() => {});
+  }
+  if (!browserContextId || !browserSession) {
+    return browserContextId;
+  }
+
+  try {
+    // TargetInfo also reports an opaque id for a persistent/default context in
+    // current Chromium. Only ids returned here are true non-default contexts
+    // accepted by Browser.setDownloadBehavior's browserContextId parameter.
+    const { browserContextIds = [] } = await browserSession.send(
+      'Target.getBrowserContexts'
+    );
+    return browserContextIds.includes(browserContextId)
+      ? browserContextId
+      : undefined;
+  } catch {
+    // Older/page-scoped CDP bridges may not expose getBrowserContexts. The
+    // persistent-context guard above handles their known default-context case.
+    return browserContextId;
+  }
+}
+
 /**
  * Open a CDP session that can drive the Browser domain.
  *

package/src/downloads/staging.js

@@ -26,6 +26,9 @@ export const DEFAULT_STAGING_TIMEOUT = 10000;
 /** How often the staged file is looked at while waiting. */
 export const DEFAULT_STAGING_POLL_INTERVAL = 25;
 
+/** How long an unchanged size must remain observable before it is complete. */
+export const DEFAULT_STAGING_STABILITY = 100;
+
 /** Suffixes Chromium uses for a file it is still writing. */
 export const STAGING_IN_PROGRESS_SUFFIXES = Object.freeze([
   '.crdownload',
@@ -77,14 +80,15 @@ async function observeStagedFile(filePath, suffixes) {
 /**
  * Wait until a staged download is readable and has stopped growing.
  *
- * Stability is decided by two consecutive readings of the same size, the same
- * evidence the Selenium directory watcher uses: a file that merely exists is
- * not evidence that its last byte was written.
+ * Stability is decided by an unchanged-size quiet period. Two equal readings
+ * only prove that no write landed between those particular polls; a stalled
+ * writer can pause for longer than one interval and resume afterwards.
  *
  * @param {Object} options - Wait options
  * @param {string} options.path - Path the engine staged the download under
  * @param {number} [options.timeout] - Total budget in milliseconds
  * @param {number} [options.interval] - Milliseconds between readings
+ * @param {number} [options.stability] - Required unchanged-size quiet period
  * @param {string[]} [options.inProgressSuffixes] - Suffixes of a partial file
  * @returns {Promise<{ready: boolean, bytes: number|null, reason: string|null, waitedMs: number}>} Outcome
  */
@@ -93,11 +97,13 @@ export async function waitForStagedFile(options = {}) {
     path: filePath,
     timeout = DEFAULT_STAGING_TIMEOUT,
     interval = DEFAULT_STAGING_POLL_INTERVAL,
+    stability = DEFAULT_STAGING_STABILITY,
     inProgressSuffixes = STAGING_IN_PROGRESS_SUFFIXES,
   } = options;
 
   const deadline = createDeadline({ timeout });
   let previousSize;
+  let stableSince;
   // Always set by the reading below before the deadline can be checked.
   let reason;
 
@@ -107,15 +113,21 @@ export async function waitForStagedFile(options = {}) {
       reason = seen.reason;
       // A file that vanished has to prove itself stable again from scratch.
       previousSize = undefined;
+      stableSince = undefined;
     } else if (seen.size === previousSize) {
-      return {
-        ready: true,
-        bytes: seen.size,
-        reason: null,
-        waitedMs: deadline.elapsedMs(),
-      };
+      const stableMs = deadline.elapsedMs() - stableSince;
+      if (stableMs >= stability) {
+        return {
+          ready: true,
+          bytes: seen.size,
+          reason: null,
+          waitedMs: deadline.elapsedMs(),
+        };
+      }
+      reason = `the file had been unchanged for only ${stableMs}ms`;
     } else {
       previousSize = seen.size;
+      stableSince = deadline.elapsedMs();
       reason = `the file was still growing at ${seen.size} bytes`;
     }
 

package/src/elements/selectors.js

@@ -302,9 +302,10 @@ export function withTextSelectorSupport(fn, engine, page) {
   return async (options = {}) => {
     let { selector } = options;
 
-    // Normalize Puppeteer text selectors (object format)
+    // Normalize Puppeteer-style text selectors (object format; Puppeteer and
+    // selenium)
     if (
-      engine === 'puppeteer' &&
+      engine !== 'playwright' &&
       typeof selector === 'object' &&
       selector._isPuppeteerTextSelector
     ) {

package/src/elements/visibility.js

@@ -149,6 +149,10 @@ export async function count(options = {}) {
       );
       return result;
     }
+    if (engine === 'selenium' && selector?._isPuppeteerTextSelector) {
+      // The WebDriverPage facade evaluates like a Puppeteer page (issue #104).
+      return await count({ ...options, engine: 'puppeteer' });
+    }
 
     if (engine === 'playwright') {
       return await page.locator(selector).count();

package/src/exports.js

@@ -27,9 +27,24 @@ export {
   EngineAdapter,
   PlaywrightAdapter,
   PuppeteerAdapter,
+  SeleniumAdapter,
   createEngineAdapter,
 } from './core/engine-adapter.js';
 
+// Selenium / WebDriver engine (issue #104)
+export {
+  WebDriverPage,
+  WebDriverTimeoutError,
+  createWebDriverPage,
+  isWebDriver,
+} from './core/webdriver-page.js';
+export {
+  launchWebDriver,
+  connectWebDriver,
+  resolveWebDriverExecutable,
+  CHROMEDRIVER_DEFAULT_SWITCHES,
+} from './browser/webdriver.js';
+
 // Page trigger system
 export {
   createPageTriggerManager,
@@ -51,7 +66,49 @@ export {
   launchAndConnectRealBrowser,
   launchRealBrowser,
 } from './browser/real-browser.js';
-export { launchBrowser } from './browser/launcher.js';
+export {
+  classifyDifferences,
+  compareCommandLines,
+  measureParity,
+  parseSwitches,
+  readBrowserVersionPage,
+} from './browser/parity.js';
+export {
+  openInUserBrowser,
+  buildOpenCommand,
+  validateOpenUrl,
+} from './browser/open-in-user-browser.js';
+export { migrateProfile, ALL_DATA_CLASSES } from './browser/migration/index.js';
+export {
+  attachUserBrowser,
+  attachViaExtension,
+  ATTACH_MODES,
+  DEFAULT_RELAY_PORT,
+  describeAttachDifferences,
+  EXTENSION_DIRECTORY,
+  RELAY_PATH,
+  snapshotUserDataDir,
+} from './browser/attach/index.js';
+export {
+  launchBrowser,
+  LAUNCH_MODES,
+  resolveLaunchExecutable,
+} from './browser/launcher.js';
+export {
+  LAUNCH_RESTRICTIONS,
+  LAUNCH_RESTRICTION_PRESETS,
+  resolveRestrictions,
+  mergeFeatureSwitches,
+} from './browser/restrictions.js';
+export {
+  createTemporaryUserDataDir,
+  prepareUserDataDir,
+  removeUserDataDir,
+} from './browser/profile-directory.js';
+export {
+  PortRaceError,
+  reserveLoopbackPort,
+} from './browser/debugging-port.js';
 export { saveStorageState } from './browser/storage-state.js';
 export { emulateMedia } from './browser/media.js';
 export {
@@ -187,7 +244,9 @@ export {
   buildFingerprintInitScript,
   buildInitScriptConfig,
 } from './fingerprint/init-script.js';
-export { applyFingerprint, createCdpSession } from './fingerprint/apply.js';
+export { applyFingerprint } from './fingerprint/apply.js';
+// Raw CDP with one surface for both engines (issue #104).
+export { createCdpSession, wrapCdpSession } from './browser/cdp-session.js';
 export {
   FINGERPRINT_PRESET_NAMES,
   createFingerprintPreset,

package/src/factory.js

@@ -6,6 +6,7 @@
 
 import { createLogger } from './core/logger.js';
 import { detectEngine } from './core/engine-detection.js';
+import { WebDriverPage } from './core/webdriver-page.js';
 import { createNetworkTracker } from './core/network-tracker.js';
 import { createNavigationManager } from './core/navigation-manager.js';
 import { createPageSessionFactory } from './core/page-session.js';
@@ -22,11 +23,12 @@ import {
 import { createBoundFunctions } from './bindings.js';
 import { attachDownloads } from './downloads/attach.js';
 import { startTrace } from './traces/recorder.js';
+import { createCdpSession } from './browser/cdp-session.js';
 
 /**
  * Create a browser commander instance for a specific page
  * @param {Object} options - Configuration options
- * @param {Object} options.page - Playwright or Puppeteer page object
+ * @param {Object} options.page - Playwright or Puppeteer page object, or a selenium-webdriver WebDriver (or the WebDriverPage launchWebDriver() returns)
  * @param {boolean} options.verbose - Enable verbose logging
  * @param {boolean} options.enableNetworkTracking - Enable network request tracking (default: true)
  * @param {boolean} options.enableNavigationManager - Enable navigation manager (default: true)
@@ -35,7 +37,7 @@ import { startTrace } from './traces/recorder.js';
  */
 export function makeBrowserCommander(options = {}) {
   const {
-    page,
+    page: providedPage,
     verbose = false,
     enableNetworkTracking = true,
     enableNavigationManager = true,
@@ -43,11 +45,17 @@ export function makeBrowserCommander(options = {}) {
     downloads = null,
   } = options;
 
-  if (!page) {
+  if (!providedPage) {
     throw new Error('page is required in options');
   }
 
-  const engine = detectEngine(page);
+  const engine = detectEngine(providedPage);
+  // A bare selenium-webdriver WebDriver is wrapped in the page facade the
+  // helpers speak to (issue #104); launchWebDriver() already returns one.
+  const page =
+    engine === 'selenium' && !providedPage.isWebDriverPage
+      ? new WebDriverPage(providedPage)
+      : providedPage;
   const log = createLogger({ verbose });
 
   // Create NetworkTracker if enabled
@@ -177,6 +185,13 @@ export function makeBrowserCommander(options = {}) {
       return commander.downloads;
     },
 
+    /**
+     * Open a raw CDP session for this commander's page (issue #104).
+     *
+     * @returns {Promise<Object>} {send, on, once, off, detach, session, engine}
+     */
+    createCdpSession: () => createCdpSession(page, { engine }),
+
     /**
      * Start recording a privacy-aware trace of this session (issue #87).
      *

package/src/fingerprint/apply.js

@@ -14,6 +14,12 @@ import { resolveFingerprintProfile } from './profile.js';
 
 /** Open a CDP session for a page, whichever engine owns it. */
 export function createCdpSession({ browser, page, engine }) {
+  if (engine === 'selenium') {
+    throw new Error(
+      'Fingerprint profiles need a CDP session, which the selenium engine does ' +
+        'not have (see the webdriver-no-cdp-emulation limitation)'
+    );
+  }
   if (engine === 'puppeteer') {
     if (typeof page.createCDPSession === 'function') {
       return page.createCDPSession();

package/src/fingerprint/automation-parity.js

@@ -16,6 +16,13 @@
  * the browser. A specific port number is left alone on purpose, since that is
  * what a human attaching a debugger passes.
  *
+ * `kHeadless` is in that table but is not a trigger in practice: the renderer
+ * never sees the switch in today's headless mode. A hand-started Chrome 153
+ * with `--headless`, `--headless=new` or `--headless=old` and nothing else
+ * reports `navigator.webdriver === false`
+ * (experiments/issue-103/headless-webdriver.mjs), so a headless launch needs
+ * no off switch to match it, and adding one would be a difference of its own.
+ *
  * https://chromium.googlesource.com/chromium/src/+/refs/heads/main/content/child/runtime_features.cc
  */
 
@@ -30,11 +37,6 @@ export const AUTOMATION_CONTROLLED_TRIGGERS = Object.freeze([
     reason:
       'Mapped onto AutomationControlled in content/child/runtime_features.cc; also shows the "controlled by automated test software" infobar.',
   }),
-  Object.freeze({
-    switch: '--headless',
-    reason:
-      'Mapped onto AutomationControlled in content/child/runtime_features.cc; covers --headless and --headless=new alike.',
-  }),
   Object.freeze({
     switch: '--remote-debugging-pipe',
     reason:
@@ -59,9 +61,6 @@ function isTrigger(argument, trigger) {
       Number(argument.slice('--remote-debugging-port='.length)) === 0
     );
   }
-  if (trigger.switch === '--headless') {
-    return switchName(argument) === '--headless';
-  }
   return switchName(argument) === trigger.switch;
 }
 

package/src/fingerprint/limitations.js

@@ -8,7 +8,7 @@
  * `docs/case-studies/issue-79/analysis-artifacts/`.
  *
  * The catalogue itself lives in `limitations.json`, because Python and Rust
- * publish the same eleven entries and a hand-copied paragraph of prose drifts
+ * publish the same sixteen entries and a hand-copied paragraph of prose drifts
  * as easily as a hand-copied patch. This module owns the JSON; the copies are
  * checked byte for byte by `scripts/check-shared-fingerprint-assets.sh`.
  *

package/src/fingerprint/limitations.json

@@ -4,10 +4,19 @@
     "surface": "navigator.webdriver",
     "severity": "high",
     "evidence": "measured",
-    "detail": "navigator.webdriver is the AutomationControlled Blink runtime feature. Chrome enables it for --enable-automation, --headless, --remote-debugging-pipe and an ephemeral --remote-debugging-port=0, and the only way to turn it back off is the launch switch --disable-blink-features=AutomationControlled. Emulation.setAutomationOverride({enabled:false}) is accepted over CDP but leaves navigator.webdriver true, in the same document and after navigation, so a browser somebody else already launched cannot be corrected from the protocol side.",
-    "workaround": "Launch the browser through this library, which passes the switch. When attaching to a browser somebody else started, apply the profile with the webdriver patch option, which installs a JavaScript getter instead: that is weaker, because it does not reach workers or a renderer that starts before the patch is installed.",
+    "detail": "navigator.webdriver is the AutomationControlled Blink runtime feature. Chrome enables it for --enable-automation, --remote-debugging-pipe and an ephemeral --remote-debugging-port=0, and the only way to turn it back off is the launch switch --disable-blink-features=AutomationControlled. A fixed non-zero --remote-debugging-port does not enable it, and neither does --headless in any of its forms (measured with Chrome 153, experiments/issue-103/headless-webdriver.mjs). Emulation.setAutomationOverride({enabled:false}) is accepted over CDP but leaves navigator.webdriver true, in the same document and after navigation, so a browser somebody else already launched cannot be corrected from the protocol side.",
+    "workaround": "Launch the browser through this library: the default real launch starts it on a fixed port, so the feature is never enabled, and launch: 'engine' passes the off switch. When attaching to a browser somebody else started, apply the profile with the webdriver patch option, which installs a JavaScript getter instead: that is weaker, because it does not reach workers or a renderer that starts before the patch is installed.",
     "reference": "content/child/runtime_features.cc; analysis-artifacts/remote-debugging-isolation.json"
   },
+  {
+    "id": "engine-launch-switches",
+    "surface": "Browser UI and chrome://version command line",
+    "severity": "medium",
+    "evidence": "measured",
+    "detail": "With launch: 'engine' the browser is started by Playwright or Puppeteer, which add their own switches (--enable-automation, --remote-debugging-pipe or port 0, --disable-extensions, --disable-sync and more; see chrome://version). Browser Commander removes --enable-automation and adds --disable-blink-features=AutomationControlled so navigator.webdriver stays false, but Chrome answers that switch with the \"You are using an unsupported command-line flag\" infobar, and the remaining engine switches change which browser features exist.",
+    "workaround": "Use the default launch: 'real', which starts the browser with only --user-data-dir and a fixed --remote-debugging-port, and opt into individual restrictions by name when they are wanted.",
+    "reference": "js/tests/e2e/fingerprint-parity.e2e.test.js; experiments/issue-105/"
+  },
   {
     "id": "no-cdp-device-memory-override",
     "surface": "navigator.deviceMemory",
@@ -92,5 +101,39 @@
     "detail": "A worker has its own Navigator, and overrides set on the page session only partly reach it. Measured in a dedicated worker: userAgent, timezone and locale follow the profile, but platform, language, languages, hardwareConcurrency and deviceMemory all report the real host values, and no JavaScript patch is present because Page.addScriptToEvaluateOnNewDocument runs in documents only. Full worker parity is reachable over raw CDP -- replaying the Emulation commands on the worker session fixes languages and hardwareConcurrency, and evaluating the init script during the waitForDebuggerOnStart pause fixes the rest -- but that needs a sessionId, which neither engine accepts: Playwright newCDPSession takes only Page or Frame, and Puppeteer worker sessions are internal to its TargetManager.",
     "workaround": "Avoid workloads that read the fingerprint from a worker, or drive Chrome over a raw CDP connection and replay the commands the CDP override builder returns on each attached worker session.",
     "reference": "analysis-artifacts/worker-visibility.json"
+  },
+  {
+    "id": "webdriver-driver-launch-switches",
+    "surface": "navigator.webdriver and the browser command line under chromedriver",
+    "severity": "medium",
+    "evidence": "measured",
+    "detail": "chromedriver starts Chrome with twenty switches of its own. Two of them turn navigator.webdriver on by themselves: --enable-automation, and --remote-debugging-port=0 (any debugging port chosen by the browser). With chromedriver's defaults navigator.webdriver is true; excluding --enable-automation alone still leaves it true; excluding every default switch and giving Chrome a fixed debugging port makes it false, headful and headless, with and without BiDi. launchWebDriver() does exactly that, so its command line is the same as a real-browser launch. A driver started by someone else -- a Selenium Grid node, a cloud provider, connectWebDriver() -- keeps whatever switches it was given, and --disable-blink-features=AutomationControlled, the usual workaround, shows an unsupported-flag infobar.",
+    "workaround": "Launch the driver with launchWebDriver(), or pass the same excludeSwitches and a fixed --remote-debugging-port in the capabilities given to connectWebDriver().",
+    "reference": "experiments/issue-104/webdriver-automation-flags.mjs"
+  },
+  {
+    "id": "webdriver-no-cdp-emulation",
+    "surface": "Fingerprint profiles, media emulation and managed downloads on the selenium engine",
+    "severity": "medium",
+    "evidence": "documented",
+    "detail": "Fingerprint profiles, emulateMedia and managed downloads are built on Chrome DevTools Protocol commands and events (Emulation.*, Page.addScriptToEvaluateOnNewDocument with a CDP session, Browser.setDownloadBehavior). A WebDriver session exposes no CDP session through the W3C protocol, and WebDriver BiDi has no equivalent of most Emulation commands yet, so on the selenium engine these operations throw instead of silently doing nothing.",
+    "workaround": "Use the playwright or puppeteer engine for fingerprint profiles, media emulation and managed downloads, or set the equivalent browser preferences in the capabilities."
+  },
+  {
+    "id": "webdriver-classic-has-no-events",
+    "surface": "Console, page error, dialog, request and navigation events on the selenium engine",
+    "severity": "low",
+    "evidence": "documented",
+    "detail": "Classic WebDriver is request/response only: a session cannot be told about console messages, uncaught errors, dialogs, network requests or navigations it did not start. Those events, preload scripts and full-page or clipped screenshots come from WebDriver BiDi, which a session has only when it was created with the webSocketUrl capability. Without it the operations that need events throw an error naming the missing capability.",
+    "workaround": "Launch with bidi: true, or add webSocketUrl: true to the capabilities given to connectWebDriver()."
+  },
+  {
+    "id": "webdriver-print-options",
+    "surface": "pdf() options on the selenium engine",
+    "severity": "low",
+    "evidence": "documented",
+    "detail": "WebDriver Print Page takes orientation, scale, background, page size, margins, shrink-to-fit and page ranges only. Header and footer templates, preferCSSPageSize, tagged and outlined PDFs and omitBackground have no WebDriver equivalent; pdf() rejects them rather than producing a different document than the one asked for. Page and margin sizes are converted to centimetres.",
+    "workaround": "Leave the unsupported options out, or produce the PDF with the playwright or puppeteer engine.",
+    "reference": "https://w3c.github.io/webdriver/#print-page"
   }
 ]