browser-commander 0.19.0 → 0.21.0

package/extension/relay-handler.js

@@ -0,0 +1,353 @@
+/**
+ * The companion extension's side of the Browser Commander relay (issue #102,
+ * addendum, mode 2).
+ *
+ * The extension lets Browser Commander drive tabs of the user's running,
+ * already signed-in browser without any debugging switch: its service worker
+ * connects to a relay server on loopback and forwards requests to the
+ * `chrome.tabs` and `chrome.debugger` APIs. Chrome shows its "started
+ * debugging this browser" infobar while a tab is attached, and the user can
+ * end the session from there.
+ *
+ * Protocol (JSON text frames on `ws://127.0.0.1:<port>/browser-commander`):
+ *
+ * - extension -> server, on open:
+ *   `{"type":"hello","extensionVersion":"...","userAgent":"..."}`
+ * - server -> extension: `{"id":n,"method":M,"params":{...}}` with M one of
+ *   `tabs.list` -> `[{tabId,url,title,active}]`, `tabs.create` {url} ->
+ *   `{tabId}`, `debugger.attach` {tabId} -> `{attached:true}`,
+ *   `debugger.detach` {tabId} -> `{detached:true}` and `cdp.send`
+ *   {tabId,method,params} -> the CDP result
+ * - extension -> server: `{"id":n,"result":...}` or
+ *   `{"id":n,"error":{"message":"..."}}`
+ * - extension -> server, unsolicited:
+ *   `{"type":"event","tabId":n,"method":"...","params":{...}}` for CDP events
+ *   of attached tabs, `{"type":"detached","tabId":n,"reason":"..."}` when a
+ *   debugger session ends, and `{"type":"keepalive"}` every 20 seconds, which
+ *   keeps the MV3 service worker alive (Chrome 116+) and is ignored by the
+ *   server.
+ *
+ * This module has no Node or browser imports: `chrome`, `WebSocket` and the
+ * timers are passed in, so the tests run it against fakes.
+ */
+
+/** Relay port when `chrome.storage.local` has no `port`. */
+export const DEFAULT_PORT = 9333;
+
+/** Path of the relay's WebSocket endpoint. */
+export const RELAY_PATH = '/browser-commander';
+
+/** chrome.alarms name that wakes the service worker to reconnect. */
+export const KEEPALIVE_ALARM = 'browser-commander-relay';
+
+/** chrome.debugger protocol version. */
+export const DEBUGGER_PROTOCOL_VERSION = '1.3';
+
+/**
+ * The relay URL for a port.
+ *
+ * @param {number} [port=DEFAULT_PORT]
+ * @returns {string}
+ */
+export function relayUrl(port = DEFAULT_PORT) {
+  return `ws://127.0.0.1:${port}${RELAY_PATH}`;
+}
+
+function requireTabId(params) {
+  if (!Number.isInteger(params.tabId)) {
+    throw new Error('params.tabId must be an integer tab id');
+  }
+  return params.tabId;
+}
+
+function describeTab(tab) {
+  return {
+    tabId: tab.id,
+    url: tab.url ?? tab.pendingUrl ?? '',
+    title: tab.title ?? '',
+    active: Boolean(tab.active),
+  };
+}
+
+/**
+ * Run one relay request against the extension APIs.
+ *
+ * @param {Object} chrome - The `chrome` namespace (or a fake)
+ * @param {{method: string, params: (Object|undefined)}} request
+ * @param {Set<number>} attachedTabs - Tabs this extension has attached the debugger to; updated in place
+ * @returns {Promise<*>} The `result` of the response
+ */
+export async function handleRelayRequest(
+  chrome,
+  { method, params = {} },
+  attachedTabs
+) {
+  switch (method) {
+    case 'tabs.list': {
+      const tabs = await chrome.tabs.query({});
+      return tabs.filter((tab) => Number.isInteger(tab.id)).map(describeTab);
+    }
+    case 'tabs.create': {
+      if (params.url !== undefined && typeof params.url !== 'string') {
+        throw new Error('params.url must be a string');
+      }
+      const tab = await chrome.tabs.create(
+        params.url === undefined ? {} : { url: params.url }
+      );
+      return { tabId: tab.id };
+    }
+    case 'debugger.attach': {
+      const tabId = requireTabId(params);
+      if (!attachedTabs.has(tabId)) {
+        await chrome.debugger.attach({ tabId }, DEBUGGER_PROTOCOL_VERSION);
+        attachedTabs.add(tabId);
+      }
+      return { attached: true };
+    }
+    case 'debugger.detach': {
+      const tabId = requireTabId(params);
+      if (attachedTabs.has(tabId)) {
+        attachedTabs.delete(tabId);
+        await chrome.debugger.detach({ tabId });
+      }
+      return { detached: true };
+    }
+    case 'cdp.send': {
+      const tabId = requireTabId(params);
+      if (typeof params.method !== 'string') {
+        throw new Error('params.method must be a CDP method name');
+      }
+      const result = await chrome.debugger.sendCommand(
+        { tabId },
+        params.method,
+        params.params ?? {}
+      );
+      return result ?? {};
+    }
+    default:
+      throw new Error(`Unknown relay method: ${method}`);
+  }
+}
+
+async function readPort(chrome) {
+  try {
+    const { port } = await chrome.storage.local.get('port');
+    const number = Number(port);
+    return Number.isInteger(number) && number > 0 && number < 65536
+      ? number
+      : DEFAULT_PORT;
+  } catch {
+    return DEFAULT_PORT;
+  }
+}
+
+/**
+ * The service worker's connection to the relay: connects, retries every
+ * `retryMs` while the server is down, answers requests, forwards debugger
+ * events, and detaches every tab it attached when the connection ends.
+ *
+ * @param {Object} options
+ * @param {Object} options.chrome - The `chrome` namespace
+ * @param {Function} options.WebSocket - WebSocket constructor
+ * @param {string} [options.userAgent='']
+ * @param {number} [options.retryMs=3000]
+ * @param {number} [options.keepaliveMs=20000]
+ * @param {Function} [options.setTimeout]
+ * @param {Function} [options.clearTimeout]
+ * @param {Function} [options.setInterval]
+ * @param {Function} [options.clearInterval]
+ * @returns {{start: function(): void, connect: function(): Promise<void>, stop: function(): void, connected: function(): boolean, attachedTabs: Set<number>}}
+ */
+export function createRelayClient({
+  chrome,
+  WebSocket,
+  userAgent = '',
+  retryMs = 3_000,
+  keepaliveMs = 20_000,
+  setTimeout: schedule = globalThis.setTimeout,
+  clearTimeout: cancel = globalThis.clearTimeout,
+  setInterval: repeat = globalThis.setInterval,
+  clearInterval: cancelRepeat = globalThis.clearInterval,
+}) {
+  const attachedTabs = new Set();
+  let socket = null;
+  let connecting = false;
+  let stopped = false;
+  let retryTimer = null;
+  let keepaliveTimer = null;
+
+  const isOpen = () => socket !== null && socket.readyState === WebSocket.OPEN;
+
+  function post(message) {
+    if (isOpen()) {
+      socket.send(JSON.stringify(message));
+    }
+  }
+
+  function scheduleRetry() {
+    if (!stopped && retryTimer === null) {
+      retryTimer = schedule(() => {
+        retryTimer = null;
+        connect();
+      }, retryMs);
+    }
+  }
+
+  function detachAll() {
+    for (const tabId of [...attachedTabs]) {
+      attachedTabs.delete(tabId);
+      Promise.resolve()
+        .then(() => chrome.debugger.detach({ tabId }))
+        .catch(() => {});
+    }
+  }
+
+  async function respond(message) {
+    try {
+      const result = await handleRelayRequest(chrome, message, attachedTabs);
+      post({ id: message.id, result: result ?? {} });
+    } catch (error) {
+      post({
+        id: message.id,
+        error: { message: error?.message ?? String(error) },
+      });
+    }
+  }
+
+  function onMessage(event) {
+    let message;
+    try {
+      message = JSON.parse(event.data);
+    } catch {
+      return;
+    }
+    if (message && Number.isInteger(message.id) && message.method) {
+      respond(message);
+    }
+  }
+
+  function onOpen(opened) {
+    if (socket !== opened) {
+      return;
+    }
+    post({
+      type: 'hello',
+      extensionVersion: chrome.runtime.getManifest().version,
+      userAgent,
+    });
+    keepaliveTimer = repeat(() => post({ type: 'keepalive' }), keepaliveMs);
+  }
+
+  function onClose(closed) {
+    if (socket !== closed) {
+      return;
+    }
+    socket = null;
+    if (keepaliveTimer !== null) {
+      cancelRepeat(keepaliveTimer);
+      keepaliveTimer = null;
+    }
+    detachAll();
+    scheduleRetry();
+  }
+
+  /** Connect unless a connection is open or being opened. */
+  async function connect() {
+    if (stopped || connecting || socket !== null) {
+      return;
+    }
+    connecting = true;
+    try {
+      if (retryTimer !== null) {
+        cancel(retryTimer);
+        retryTimer = null;
+      }
+      const port = await readPort(chrome);
+      if (stopped) {
+        return;
+      }
+      let opened;
+      try {
+        opened = new WebSocket(relayUrl(port));
+      } catch {
+        scheduleRetry();
+        return;
+      }
+      socket = opened;
+      opened.onopen = () => onOpen(opened);
+      opened.onmessage = onMessage;
+      opened.onclose = () => onClose(opened);
+      // An error is always followed by close, which schedules the retry.
+      opened.onerror = () => {};
+    } finally {
+      connecting = false;
+    }
+  }
+
+  function reconnect() {
+    const current = socket;
+    if (current) {
+      current.close();
+      onClose(current);
+    }
+    connect();
+  }
+
+  /**
+   * Register the listeners and connect. MV3 requires listeners to be added
+   * synchronously when the service worker starts, so call this at top level.
+   */
+  function start() {
+    chrome.debugger.onEvent.addListener((source, method, params) => {
+      if (attachedTabs.has(source.tabId)) {
+        post({ type: 'event', tabId: source.tabId, method, params });
+      }
+    });
+    chrome.debugger.onDetach.addListener((source, reason) => {
+      if (attachedTabs.delete(source.tabId)) {
+        post({ type: 'detached', tabId: source.tabId, reason });
+      }
+    });
+    chrome.alarms.onAlarm.addListener((alarm) => {
+      if (alarm.name === KEEPALIVE_ALARM) {
+        connect();
+      }
+    });
+    chrome.storage.onChanged.addListener((changes, area) => {
+      if (area === 'local' && changes.port) {
+        reconnect();
+      }
+    });
+    chrome.runtime.onStartup.addListener(() => connect());
+    chrome.runtime.onInstalled.addListener(() => connect());
+    // Wakes a suspended service worker to reconnect; 30 seconds is the
+    // shortest period Chrome allows.
+    Promise.resolve()
+      .then(() =>
+        chrome.alarms.create(KEEPALIVE_ALARM, { periodInMinutes: 0.5 })
+      )
+      .catch(() => {});
+    connect();
+  }
+
+  function stop() {
+    stopped = true;
+    if (retryTimer !== null) {
+      cancel(retryTimer);
+      retryTimer = null;
+    }
+    const current = socket;
+    if (current) {
+      current.close();
+      onClose(current);
+    }
+  }
+
+  return {
+    start,
+    connect,
+    stop,
+    connected: isOpen,
+    attachedTabs,
+  };
+}

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "browser-commander",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
+  "bin": {
+    "browser-commander": "bin/browser-commander.js"
+  },
   "type": "module",
   "exports": {
     ".": "./src/index.js",
@@ -15,10 +18,14 @@
     "test:e2e": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e",
     "test:e2e:playwright": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/playwright.e2e.test.js",
     "test:e2e:puppeteer": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/puppeteer.e2e.test.js",
-    "test:e2e:parity": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/fingerprint-parity.e2e.test.js",
+    "test:e2e:webdriver": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/webdriver.e2e.test.js",
+    "test:e2e:parity": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/fingerprint-parity.e2e.test.js tests/e2e/measure-parity.e2e.test.js",
     "test:e2e:click-readiness": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/click-readiness.e2e.test.js",
     "test:e2e:downloads": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/downloads.e2e.test.js",
     "test:e2e:traces": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/traces.e2e.test.js",
+    "test:e2e:cli": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/cli.e2e.test.js",
+    "test:e2e:api-coverage": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/api-coverage.e2e.test.js",
+    "test:e2e:google-probe": "node scripts/run-tests.mjs --env RUN_E2E=true --env RUN_GOOGLE_PROBE=true tests/e2e/google-signin-probe.e2e.test.js",
     "test:all": "npm run test:unit && npm run test:e2e",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -42,6 +49,8 @@
     "automation",
     "playwright",
     "puppeteer",
+    "selenium",
+    "webdriver",
     "testing",
     "e2e"
   ],
@@ -52,11 +61,12 @@
   },
   "homepage": "https://github.com/link-foundation/browser-commander#readme",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "peerDependencies": {
     "playwright": ">=1.40.0",
-    "puppeteer": ">=21.0.0"
+    "puppeteer": ">=21.0.0",
+    "selenium-webdriver": ">=4.20.0"
   },
   "peerDependenciesMeta": {
     "playwright": {
@@ -64,10 +74,14 @@
     },
     "puppeteer": {
       "optional": true
+    },
+    "selenium-webdriver": {
+      "optional": true
     }
   },
   "dependencies": {
-    "better-sqlite3": "^12.11.1",
+    "better-sqlite3": "^13.0.3",
+    "command-stream": "^1.2.0",
     "links-notation": "^0.20.0",
     "log-lazy": "^1.0.4",
     "test-anywhere": "^0.9.1"
@@ -82,6 +96,11 @@
     "jsdoc": "^4.0.4",
     "playwright": "^1.62.1",
     "prettier": "^3.9.6",
-    "puppeteer": "^25.10.0"
+    "puppeteer": "^25.10.0",
+    "selenium-webdriver": "^4.49.0"
+  },
+  "allowScripts": {
+    "better-sqlite3@13.0.3": true,
+    "puppeteer": false
   }
 }

package/scripts/run-tests.mjs

@@ -147,13 +147,15 @@ export function buildNodeTestArgs(
   testFiles,
   nodeVersion = process.versions.node
 ) {
-  const args = ['--test'];
+  // A resource leak that is a warning today becomes a runtime failure in a
+  // later Node release. Make deprecations fail at the point that creates them.
+  const args = ['--test', '--throw-deprecation'];
 
   // Node's default process isolation serializes each test file's results over
   // a child-process channel. Node 24 on macOS can intermittently corrupt that
   // stream (ERR_TEST_FAILURE: "Unable to deserialize cloned data"). Running
   // supported runtimes in-process removes that transport while keeping the
-  // Node 20-compatible fallback for consumers on the minimum engine version.
+  // Node 22-compatible fallback for consumers on the minimum engine version.
   if (supportsTestIsolation(nodeVersion)) {
     args.push('--test-isolation=none');
   }

package/src/browser/attach/differences.js

@@ -0,0 +1,131 @@
+/**
+ * What each way of reaching "the user's real browser" differs in from that
+ * browser (issue #102, addendum).
+ *
+ * Chrome 136 and later ignore the remote debugging switches for the default
+ * user data directory, so no mode can drive the real profile in place. Each
+ * mode trades something else away, and consumers pick knowingly from these
+ * lists:
+ *
+ * - `clean`: the default `launchRealBrowser()` - a fresh dedicated profile.
+ * - `snapshot`: `launchRealBrowser({ attach: { mode: 'snapshot' } })` - a
+ *   read-only copy of the real profile in a temporary user data directory.
+ * - `extension`: `attachUserBrowser({ mode: 'extension' })` - the running real
+ *   browser, driven through the companion extension's `chrome.debugger` API.
+ * - `open`: `openInUserBrowser(url)` - the user's own browser with no
+ *   automation at all, so there is nothing that differs.
+ *
+ * Every entry is `{ aspect, description }`; `aspect` is a stable identifier
+ * shared by the JS, Python and Rust implementations. The lists are static:
+ * what a page can actually observe is measured by `measureParity()` (issue
+ * #103), which the `fingerprint` entry points to.
+ */
+
+/** The modes {@link describeAttachDifferences} knows. */
+export const ATTACH_MODES = Object.freeze([
+  'clean',
+  'snapshot',
+  'extension',
+  'open',
+]);
+
+const REMOTE_DEBUGGING = {
+  aspect: 'remote-debugging',
+  description:
+    'A fixed loopback --remote-debugging-port is on the command line; issue #101 measured that a page cannot observe it and that navigator.webdriver stays false.',
+};
+
+const FINGERPRINT = {
+  aspect: 'fingerprint',
+  description:
+    'measureParity({ session }) measures the command line and everything a page can read against the same browser started by hand.',
+};
+
+const DIFFERENCES = {
+  clean: [
+    {
+      aspect: 'user-data-dir',
+      description:
+        'A fresh dedicated profile: no cookies, sign-in, history, bookmarks, passwords or extensions of the real profile. Signing in with Google works (#101) and Chrome sync restores the rest.',
+    },
+    {
+      aspect: 'first-run',
+      description:
+        "The profile gets Chrome's own First Run sentinel and a Local State that skips the What's New and Edge first-run tabs, instead of --no-first-run.",
+    },
+    REMOTE_DEBUGGING,
+    FINGERPRINT,
+  ],
+  snapshot: [
+    {
+      aspect: 'user-data-dir',
+      description:
+        'The browser runs on a read-only copy of the real profile in a temporary user data directory. Changes are not written back, and the copy is deleted on close.',
+    },
+    {
+      aspect: 'profile-directory',
+      description:
+        'A profile other than Default is selected with --profile-directory=<name>, as a profile shortcut does.',
+    },
+    {
+      aspect: 'not-copied',
+      description:
+        'Caches (HTTP, code, GPU and shader caches, Service Worker CacheStorage), crash reports, lock files and the open-tabs session files are not copied, so first loads are cold and the tabs of the running browser are not restored.',
+    },
+    {
+      aspect: 'encrypted-data',
+      description:
+        'Cookies and saved passwords stay encrypted with the OS keystore key and decrypt only for the same browser, and only when neither the mock-keychain nor the basic-password-store restriction is used.',
+    },
+    {
+      aspect: 'dbsc',
+      description:
+        'Device-bound Google sessions (DBSC) cannot be used from a copy because their key never leaves the original profile; Google needs a fresh sign-in. Other sites keep their sessions.',
+    },
+    {
+      aspect: 'extensions-mac',
+      description:
+        'Extension settings are protected by a machine-bound MAC in Secure Preferences. The copy is made on the same machine, so they stay valid; a snapshot moved to another machine has its extensions reset by Chrome.',
+    },
+    REMOTE_DEBUGGING,
+    FINGERPRINT,
+  ],
+  extension: [
+    {
+      aspect: 'debugger-infobar',
+      description:
+        'While a tab is attached, Chrome shows its "started debugging this browser" infobar; the user can end the session with its Cancel button.',
+    },
+    {
+      aspect: 'extension-install',
+      description:
+        'The companion extension (js/extension) has to be installed once with the user\'s consent through chrome://extensions "Load unpacked".',
+    },
+    {
+      aspect: 'cdp-scope',
+      description:
+        'CDP is limited to what chrome.debugger allows: per-tab sessions only, no Browser.* or Target.* domain commands. New tabs are opened through the extension (tabs.create).',
+    },
+    {
+      aspect: 'data',
+      description:
+        "None: the profile, cookies, sign-in, extensions and open tabs are the user's own; nothing is copied and there is no debugging switch on the command line.",
+    },
+  ],
+  open: [],
+};
+
+/**
+ * The documented differences from the real browser for one mode.
+ *
+ * @param {'clean'|'snapshot'|'extension'|'open'} mode
+ * @returns {Array<{aspect: string, description: string}>} A fresh copy
+ */
+export function describeAttachDifferences(mode) {
+  if (!Object.hasOwn(DIFFERENCES, mode)) {
+    throw new TypeError(
+      `Unknown attach mode "${mode}"; expected one of ${ATTACH_MODES.join(', ')}`
+    );
+  }
+  return DIFFERENCES[mode].map((difference) => ({ ...difference }));
+}