browser-commander 0.16.0 → 0.17.0

package/src/browser/browser-cookies.js

@@ -231,7 +231,8 @@ async function mapChromiumRows(rows, databaseVersion, context) {
     } catch (error) {
       if (!context.ignoreDecryptionErrors) {
         throw new Error(
-          `Could not decrypt cookie ${row.name} for ${row.host_key}: ${error.message}`
+          `Could not decrypt cookie ${row.name} for ${row.host_key}: ${error.message}`,
+          { cause: error }
         );
       }
     }
@@ -246,7 +247,10 @@ async function openCookieDatabase(cookiePath) {
       readOnly: true,
     });
   } catch (error) {
-    throw new Error(`Could not open browser cookie database: ${error.message}`);
+    throw new Error(
+      `Could not open browser cookie database: ${error.message}`,
+      { cause: error }
+    );
   }
 }
 

package/src/browser/browser-profiles.js

@@ -181,7 +181,7 @@ async function listFirefoxProfiles(root, platform) {
     return [];
   }
   const pathApi = platformPath(platform);
-  let sections = [];
+  let sections;
   try {
     sections = parseIni(
       await readFile(pathApi.join(root, 'profiles.ini'), 'utf8')

package/src/browser/launch-options.js

@@ -1,4 +1,8 @@
 import { CHROME_ARGS } from '../core/constants.js';
+import {
+  applyAutomationParityArgs,
+  parityIgnoredDefaultArgs,
+} from '../fingerprint/automation-parity.js';
 
 function stringArray(value, name) {
   if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
@@ -60,19 +64,28 @@ export function buildPlaywrightLaunchOptions({
   channel,
   executablePath,
   ignoreDefaultArgs = [],
+  automationParity = true,
 }) {
   const normalizedIgnoreDefaultArgs =
     ignoreDefaultArgs === false ? [] : ignoreDefaultArgs;
   const engineIgnoreDefaultArgs =
     normalizedIgnoreDefaultArgs === true
       ? true
-      : [...new Set(['--enable-automation', ...normalizedIgnoreDefaultArgs])];
+      : [
+          ...new Set([
+            '--enable-automation',
+            ...(automationParity
+              ? parityIgnoredDefaultArgs('playwright', { headless })
+              : []),
+            ...normalizedIgnoreDefaultArgs,
+          ]),
+        ];
   const options = {
     headless,
     slowMo,
     chromiumSandbox: true,
     viewport: null,
-    args: chromeArgs,
+    args: automationParity ? applyAutomationParityArgs(chromeArgs) : chromeArgs,
     ignoreDefaultArgs: engineIgnoreDefaultArgs,
   };
 
@@ -90,20 +103,30 @@ export function buildPuppeteerLaunchOptions({
   channel,
   executablePath,
   ignoreDefaultArgs = [],
+  automationParity = true,
 }) {
   const normalizedIgnoreDefaultArgs =
     ignoreDefaultArgs === false ? [] : ignoreDefaultArgs;
+  const baseArgs = ['--start-maximized', ...chromeArgs];
+  const engineIgnoreDefaultArgs =
+    normalizedIgnoreDefaultArgs === true
+      ? true
+      : [
+          ...new Set([
+            ...(automationParity
+              ? parityIgnoredDefaultArgs('puppeteer', { headless })
+              : []),
+            ...normalizedIgnoreDefaultArgs,
+          ]),
+        ];
   const options = {
     headless,
     defaultViewport: null,
-    args: ['--start-maximized', ...chromeArgs],
+    args: automationParity ? applyAutomationParityArgs(baseArgs) : baseArgs,
     userDataDir,
   };
-  if (
-    normalizedIgnoreDefaultArgs === true ||
-    normalizedIgnoreDefaultArgs.length > 0
-  ) {
-    options.ignoreDefaultArgs = normalizedIgnoreDefaultArgs;
+  if (engineIgnoreDefaultArgs === true || engineIgnoreDefaultArgs.length > 0) {
+    options.ignoreDefaultArgs = engineIgnoreDefaultArgs;
   }
   return setBrowserSelectionOptions(options, { channel, executablePath });
 }

package/src/browser/launcher.js

@@ -7,6 +7,7 @@ import {
   buildPuppeteerLaunchOptions,
   resolveChromeArgs,
 } from './launch-options.js';
+import { applyFingerprint } from '../fingerprint/apply.js';
 import {
   loadStorageState,
   restorePlaywrightStorageState,
@@ -28,6 +29,8 @@ import {
  * @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
  * @param {string|Object} [options.storageState] - Playwright-compatible storage state path or object
+ * @param {Object} [options.fingerprint] - Environment fields to present to pages, such as userAgent, timezone, locale, hardwareConcurrency or screen. Applied over CDP after launch; see src/fingerprint/profile.js for the full field list and presets.js for ready-made profiles.
+ * @param {boolean} [options.automationParity=true] - Keep the command line indistinguishable from a hand-started Chrome. Turning this off restores the pre-parity switches and makes navigator.webdriver true.
  * @returns {Promise<Object>} - Object with browser and page
  */
 export async function launchBrowser(options = {}) {
@@ -44,6 +47,8 @@ export async function launchBrowser(options = {}) {
     channel,
     executablePath,
     storageState,
+    fingerprint,
+    automationParity = true,
   } = options;
 
   const resolvedChromeArgs = resolveChromeArgs({
@@ -86,6 +91,7 @@ export async function launchBrowser(options = {}) {
       channel,
       executablePath,
       ignoreDefaultArgs: resolvedChromeArgs.ignoreDefaultArgs,
+      automationParity,
     });
     browser = await chromium.launchPersistentContext(
       userDataDir,
@@ -106,6 +112,7 @@ export async function launchBrowser(options = {}) {
         channel,
         executablePath,
         ignoreDefaultArgs: resolvedChromeArgs.ignoreDefaultArgs,
+        automationParity,
       })
     );
     const pages = await browser.pages();
@@ -134,6 +141,15 @@ export async function launchBrowser(options = {}) {
     }
   }
 
+  // The fingerprint is applied before the caller can navigate, so the first
+  // document a page loads already sees the configured environment.
+  if (fingerprint !== undefined) {
+    await applyFingerprint({ browser, page, engine, profile: fingerprint });
+    if (verbose) {
+      console.log('✅ Fingerprint profile applied');
+    }
+  }
+
   // Unfocus address bar automatically after browser launch
   // Using page.bringToFront() - confirmed working solution
   try {

package/src/exports.js

@@ -139,3 +139,37 @@ export {
   checkAndClearFlag,
   findToggleButton,
 } from './high-level/universal-logic.js';
+
+// Re-export the fingerprint subsystem: parity with a hand-started browser, and
+// full control over what a page reads about the environment.
+export {
+  AUTOMATION_CONTROLLED_OFF_ARG,
+  AUTOMATION_CONTROLLED_TRIGGERS,
+  ENGINE_PARITY_IGNORED_DEFAULT_ARGS,
+  PLAYWRIGHT_HEADLESS_POINTER_ARG,
+  PLAYWRIGHT_SOFTWARE_WEBGL_ARG,
+  applyAutomationParityArgs,
+  detectAutomationControlledTriggers,
+  disablesAutomationControlled,
+  parityIgnoredDefaultArgs,
+} from './fingerprint/automation-parity.js';
+export {
+  FINGERPRINT_FIELD_MECHANISMS,
+  resolveFingerprintProfile,
+} from './fingerprint/profile.js';
+export { deriveUserAgentData } from './fingerprint/derive.js';
+export { buildCdpEmulationCommands } from './fingerprint/cdp-overrides.js';
+export {
+  buildFingerprintInitScript,
+  buildInitScriptConfig,
+} from './fingerprint/init-script.js';
+export { applyFingerprint, createCdpSession } from './fingerprint/apply.js';
+export {
+  FINGERPRINT_PRESET_NAMES,
+  createFingerprintPreset,
+} from './fingerprint/presets.js';
+export {
+  FINGERPRINT_LIMITATIONS,
+  findFingerprintLimitation,
+  relevantFingerprintLimitations,
+} from './fingerprint/limitations.js';

package/src/fingerprint/apply.js

@@ -0,0 +1,116 @@
+/**
+ * Apply a fingerprint profile to a live page.
+ *
+ * Everything goes through CDP, including the init script, so the same code
+ * path works for Playwright and Puppeteer and behaves identically in both.
+ * The alternative -- `context.addInitScript` on one engine and
+ * `page.evaluateOnNewDocument` on the other -- would give the two engines
+ * subtly different injection timing, which is exactly the kind of difference
+ * this module exists to remove.
+ */
+import { buildCdpEmulationCommands } from './cdp-overrides.js';
+import { buildFingerprintInitScript } from './init-script.js';
+import { resolveFingerprintProfile } from './profile.js';
+
+/** Open a CDP session for a page, whichever engine owns it. */
+export function createCdpSession({ browser, page, engine }) {
+  if (engine === 'puppeteer') {
+    if (typeof page.createCDPSession === 'function') {
+      return page.createCDPSession();
+    }
+    return page.target().createCDPSession();
+  }
+  // Playwright exposes newCDPSession on the browser context; a persistent
+  // context is what `launchBrowser` hands back as `browser`.
+  const context =
+    typeof browser?.newCDPSession === 'function' ? browser : page.context();
+  return context.newCDPSession(page);
+}
+
+async function applyToPage({ browser, page, engine, commands, initScript }) {
+  const session = await createCdpSession({ browser, page, engine });
+  for (const { method, params } of commands) {
+    await session.send(method, params);
+  }
+  if (initScript) {
+    // Measured: without Page.enable on this session, Chrome accepts
+    // addScriptToEvaluateOnNewDocument and returns an identifier, but never
+    // runs the script on any subsequent document. Enabling the domain is what
+    // makes the instrumentation take effect.
+    await session.send('Page.enable');
+    await session.send('Page.addScriptToEvaluateOnNewDocument', {
+      source: initScript,
+    });
+    // A page that has already navigated will not replay the init script, so
+    // patch the current document too. The payload guards against running
+    // twice, which makes this safe on a brand new about:blank as well.
+    await session.send('Runtime.evaluate', {
+      expression: initScript,
+      returnByValue: true,
+    });
+  }
+  return session;
+}
+
+/**
+ * Apply a fingerprint profile to a page and, optionally, to pages opened later.
+ *
+ * @param {object} options
+ * @param {object} options.browser Playwright context or Puppeteer browser.
+ * @param {object} options.page Page to apply the profile to.
+ * @param {string} [options.engine] `'playwright'` or `'puppeteer'`.
+ * @param {object} options.profile Raw or already-normalized profile.
+ * @param {boolean} [options.patchWebdriver] Force `navigator.webdriver` to
+ *   `false` from JavaScript. Only needed when attaching to a browser that was
+ *   launched with automation switches that can no longer be changed; a browser
+ *   launched by this library does not need it, because
+ *   `--disable-blink-features=AutomationControlled` already covers it.
+ * @param {boolean} [options.applyToNewPages] Also apply to pages opened later.
+ * @returns {Promise<object>} The resolved profile, the commands that were sent
+ *   and the init script that was injected.
+ */
+export async function applyFingerprint({
+  browser,
+  page,
+  engine = 'playwright',
+  profile,
+  patchWebdriver = false,
+  applyToNewPages = true,
+}) {
+  if (!page) {
+    throw new TypeError('applyFingerprint requires a page');
+  }
+  const resolved = Object.isFrozen(profile)
+    ? profile
+    : resolveFingerprintProfile(profile);
+  const commands = buildCdpEmulationCommands(resolved);
+  const initScript = buildFingerprintInitScript(resolved, { patchWebdriver });
+
+  await applyToPage({ browser, page, engine, commands, initScript });
+
+  if (applyToNewPages && browser) {
+    const attach = (newPage) =>
+      applyToPage({
+        browser,
+        page: newPage,
+        engine,
+        commands,
+        initScript,
+      }).catch(() => {
+        // A page can close before the session is established; losing the
+        // overrides on a page that no longer exists is not an error.
+      });
+    if (engine === 'puppeteer' && typeof browser.on === 'function') {
+      browser.on('targetcreated', async (target) => {
+        const newPage = await target.page();
+        if (newPage) {
+          await attach(newPage);
+        }
+      });
+    } else if (typeof browser.on === 'function') {
+      browser.on('page', attach);
+    }
+  }
+
+  return { profile: resolved, commands, initScript };
+}

package/src/fingerprint/automation-parity.js

@@ -0,0 +1,224 @@
+/**
+ * Chrome tells a page that it is automated through exactly one Blink runtime
+ * feature: `AutomationControlled`. `navigator.webdriver` is that feature and
+ * nothing else, so closing the gap between a hand-started Chrome and a
+ * Browser Commander Chrome is a matter of knowing which switches turn it on.
+ *
+ * `content/child/runtime_features.cc` in Chromium maps switches onto the
+ * feature in `SetRuntimeFeaturesFromCommandLine`:
+ *
+ *     {wrf::EnableAutomationControlled, switches::kEnableAutomation, true},
+ *     {wrf::EnableAutomationControlled, switches::kHeadless, true},
+ *     {wrf::EnableAutomationControlled, switches::kRemoteDebuggingPipe, true},
+ *
+ * plus a special case directly below it: `--remote-debugging-port=0` also
+ * enables the feature, because an ephemeral port is how ChromeDriver launches
+ * the browser. A specific port number is left alone on purpose, since that is
+ * what a human attaching a debugger passes.
+ *
+ * https://chromium.googlesource.com/chromium/src/+/refs/heads/main/content/child/runtime_features.cc
+ */
+
+/** Switch that disables the Blink feature regardless of what turned it on. */
+export const AUTOMATION_CONTROLLED_OFF_ARG =
+  '--disable-blink-features=AutomationControlled';
+
+/** Chrome switches that enable the `AutomationControlled` Blink feature. */
+export const AUTOMATION_CONTROLLED_TRIGGERS = Object.freeze([
+  Object.freeze({
+    switch: '--enable-automation',
+    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:
+      'Mapped onto AutomationControlled in content/child/runtime_features.cc. Playwright always passes it, and Puppeteer passes it whenever pipe transport is selected.',
+  }),
+  Object.freeze({
+    switch: '--remote-debugging-port=0',
+    reason:
+      'An ephemeral debugging port is how ChromeDriver launches Chrome, so runtime_features.cc treats it as automation. A fixed non-zero port is deliberately not treated that way. Puppeteer defaults to port 0.',
+  }),
+]);
+
+function switchName(argument) {
+  const separator = argument.indexOf('=');
+  return separator === -1 ? argument : argument.slice(0, separator);
+}
+
+function isTrigger(argument, trigger) {
+  if (trigger.switch === '--remote-debugging-port=0') {
+    return (
+      switchName(argument) === '--remote-debugging-port' &&
+      Number(argument.slice('--remote-debugging-port='.length)) === 0
+    );
+  }
+  if (trigger.switch === '--headless') {
+    return switchName(argument) === '--headless';
+  }
+  return switchName(argument) === trigger.switch;
+}
+
+/**
+ * Report which of the supplied Chrome switches would make `navigator.webdriver`
+ * true, so callers can explain a parity failure instead of only observing it.
+ *
+ * @param {string[]} args Chrome command line switches.
+ * @returns {Array<{switch: string, argument: string, reason: string}>} Triggers found.
+ */
+export function detectAutomationControlledTriggers(args = []) {
+  if (!Array.isArray(args)) {
+    throw new TypeError('args must be an array of strings');
+  }
+  const found = [];
+  for (const argument of args) {
+    if (typeof argument !== 'string') {
+      throw new TypeError('args must be an array of strings');
+    }
+    for (const trigger of AUTOMATION_CONTROLLED_TRIGGERS) {
+      if (isTrigger(argument, trigger)) {
+        found.push({
+          switch: trigger.switch,
+          argument,
+          reason: trigger.reason,
+        });
+      }
+    }
+  }
+  return found;
+}
+
+/** True when the switch list already disables the AutomationControlled feature. */
+export function disablesAutomationControlled(args = []) {
+  return args.some((argument) => {
+    if (switchName(argument) !== '--disable-blink-features') {
+      return false;
+    }
+    return argument
+      .slice('--disable-blink-features='.length)
+      .split(',')
+      .some((feature) => feature.trim() === 'AutomationControlled');
+  });
+}
+
+/**
+ * Append the switch that keeps `navigator.webdriver` false.
+ *
+ * The feature is disabled rather than the triggering switches removed: an
+ * engine adds `--remote-debugging-pipe` or `--remote-debugging-port=0` after
+ * the caller's arguments and needs that transport to work at all, so the only
+ * reliable place to intervene is the feature itself.
+ *
+ * @param {string[]} args Chrome switches assembled so far.
+ * @returns {string[]} Switches with automation parity applied.
+ */
+export function applyAutomationParityArgs(args = []) {
+  if (!Array.isArray(args)) {
+    throw new TypeError('args must be an array of strings');
+  }
+  if (disablesAutomationControlled(args)) {
+    return [...args];
+  }
+  const existingIndex = args.findIndex(
+    (argument) => switchName(argument) === '--disable-blink-features'
+  );
+  if (existingIndex === -1) {
+    return [...args, AUTOMATION_CONTROLLED_OFF_ARG];
+  }
+  // Chrome keeps only the last --disable-blink-features occurrence, so the
+  // existing feature list has to be extended in place rather than duplicated.
+  const merged = [...args];
+  merged[existingIndex] = `${args[existingIndex]},AutomationControlled`;
+  return merged;
+}
+
+/**
+ * Playwright forces a mouse-like pointer in headless Chrome:
+ *
+ *     if (options.headless) {
+ *       chromeArguments.push("--headless");
+ *       chromeArguments.push(
+ *         "--hide-scrollbars",
+ *         "--mute-audio",
+ *         "--blink-settings=primaryHoverType=2,availableHoverTypes=2," +
+ *           "primaryPointerType=4,availablePointerTypes=4");
+ *     }
+ *
+ * -- packages/playwright-core/src/server/chromium/chromium.ts. Headless Chrome
+ * has no pointing device, so a real headless browser answers `hover: none` and
+ * `pointer: none`; with that switch the browser answers `hover: hover` and
+ * `pointer: fine`, which is a four-media-query giveaway that no page script can
+ * explain away. Measured in analysis-artifacts/parity-headless.json.
+ */
+export const PLAYWRIGHT_HEADLESS_POINTER_ARG =
+  '--blink-settings=primaryHoverType=2,availableHoverTypes=2,primaryPointerType=4,availablePointerTypes=4';
+
+/**
+ * Playwright turns on software WebGL for every launch:
+ *
+ *     const chromeArguments = [...chromiumSwitches()];
+ *     chromeArguments.push('--enable-unsafe-swiftshader');
+ *
+ * -- packages/playwright-core/src/server/chromium/chromium.ts. Until 1.62 the
+ * push was guarded by `os.platform() === 'darwin'`; it is now unconditional.
+ *
+ * The switch tells Chrome to fall back to the SwiftShader software renderer
+ * when no usable GPU is present, which a hand-started Chrome refuses to do. On
+ * a machine without a GPU -- a container, a VM, a CI runner -- the difference
+ * is total: `canvas.getContext('webgl')` answers `null` in a real browser and
+ * a full context under Playwright, complete with the ANGLE/SwiftShader vendor
+ * and renderer strings. Measured in
+ * analysis-artifacts/parity-webgl-swiftshader.json.
+ *
+ * It has to be suppressed in headless too. Headless Chrome enables SwiftShader
+ * on its own, so removing the switch changes nothing there -- but leaving it in
+ * the headless list only would mean a headful launch kept it.
+ */
+export const PLAYWRIGHT_SOFTWARE_WEBGL_ARG = '--enable-unsafe-swiftshader';
+
+/**
+ * Default switches an engine adds that a hand-started Chrome does not have.
+ *
+ * These cannot be countered after launch: they have to be kept out of the
+ * command line through the engine's own `ignoreDefaultArgs` option.
+ */
+export const ENGINE_PARITY_IGNORED_DEFAULT_ARGS = Object.freeze({
+  playwright: Object.freeze({
+    always: Object.freeze([
+      '--enable-automation',
+      PLAYWRIGHT_SOFTWARE_WEBGL_ARG,
+    ]),
+    headless: Object.freeze([PLAYWRIGHT_HEADLESS_POINTER_ARG]),
+  }),
+  puppeteer: Object.freeze({
+    always: Object.freeze(['--enable-automation']),
+    headless: Object.freeze([]),
+  }),
+});
+
+/**
+ * Default switches to suppress so the engine's command line matches a
+ * hand-started Chrome.
+ *
+ * @param {'playwright'|'puppeteer'} engine Automation engine in use.
+ * @param {object} [options]
+ * @param {boolean} [options.headless] Whether the browser runs headless.
+ * @returns {string[]} Switches to pass as `ignoreDefaultArgs`.
+ */
+export function parityIgnoredDefaultArgs(engine, { headless = false } = {}) {
+  const entry = ENGINE_PARITY_IGNORED_DEFAULT_ARGS[engine];
+  if (!entry) {
+    throw new TypeError(
+      `unknown engine "${engine}"; expected one of ${Object.keys(
+        ENGINE_PARITY_IGNORED_DEFAULT_ARGS
+      ).join(', ')}`
+    );
+  }
+  return [...entry.always, ...(headless ? entry.headless : [])];
+}