browser-commander 0.16.1 → 0.17.0

package/tests/e2e/fingerprint-parity.e2e.test.js

@@ -0,0 +1,212 @@
+/**
+ * E2E parity tests: a page must not be able to tell that Browser Commander is
+ * driving the browser.
+ *
+ * The reference capture never speaks CDP. Chrome is started as a plain child
+ * process pointed at a local page; the page runs the environment probe and
+ * POSTs the report back over HTTP. Every automated capture is delivered the
+ * same way, so a difference in the diff is a difference in the browser rather
+ * than a difference in how the probe was invoked.
+ *
+ * Parity is asserted twice, because "the same as a real browser" means a
+ * different thing in each mode: a headful capture is compared against a
+ * hand-started headful Chrome, and a headless capture against a hand-started
+ * headless Chrome. The two references genuinely differ -- see the
+ * `headless-is-distinguishable` entry in `src/fingerprint/limitations.js` --
+ * so neither comparison can stand in for the other.
+ *
+ * Prerequisites:
+ *   RUN_E2E=true, a Chrome binary, and, for the headful half, a display:
+ *
+ *     RUN_E2E=true xvfb-run -a --server-args="-screen 0 1920x1080x24" \
+ *       npm run test:e2e:parity
+ */
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import {
+  captureReferenceReport,
+  diffReports,
+  readProbeSource,
+  startProbeServer,
+} from '../../../experiments/fingerprint-parity/harness.mjs';
+import { launchBrowser } from '../../src/index.js';
+import { createFingerprintPreset } from '../../src/fingerprint/presets.js';
+
+const CHROME = process.env.CHROME_PATH || '/usr/bin/google-chrome';
+const TEST_TIMEOUT = 180000;
+
+/** Why the suite cannot run here, or `false` when it can. */
+function skipReason({ headless }) {
+  if (!process.env.RUN_E2E) {
+    return 'set RUN_E2E=true to run the parity tests';
+  }
+  if (!existsSync(CHROME)) {
+    return `no Chrome binary at ${CHROME}; set CHROME_PATH`;
+  }
+  if (!headless && process.platform === 'linux' && !process.env.DISPLAY) {
+    return 'headful parity needs a display; run under xvfb-run';
+  }
+  return false;
+}
+
+function defineParitySuite({ headless }) {
+  const mode = headless ? 'headless' : 'headful';
+
+  describe(
+    `E2E Tests - Fingerprint Parity (${mode})`,
+    { skip: skipReason({ headless }) },
+    () => {
+      let server;
+      let reference;
+      const userDataDirs = [];
+
+      const nextUserDataDir = async () => {
+        const directory = await mkdtemp(path.join(tmpdir(), 'bc-parity-e2e-'));
+        userDataDirs.push(directory);
+        return directory;
+      };
+
+      /** Drive one capture through the shipped launcher. */
+      const captureWithLibrary = async (options) => {
+        const token = randomUUID();
+        const { browser, page } = await launchBrowser({
+          headless,
+          slowMo: 0,
+          executablePath: CHROME,
+          userDataDir: await nextUserDataDir(),
+          ...options,
+        });
+        try {
+          await page.goto(server.url(token), { waitUntil: 'load' });
+          return { report: await server.waitForReport(token), token };
+        } finally {
+          await browser.close();
+        }
+      };
+
+      before(async () => {
+        server = await startProbeServer(await readProbeSource());
+        reference = await captureReferenceReport({
+          executablePath: CHROME,
+          server,
+          token: randomUUID(),
+          headless,
+        });
+        assert.ok(
+          reference && !reference.fatal,
+          `reference capture failed: ${reference && reference.fatal}`
+        );
+      });
+
+      after(async () => {
+        if (server) {
+          await server.close();
+        }
+        await Promise.all(
+          userDataDirs.map((directory) =>
+            rm(directory, { recursive: true, force: true, maxRetries: 10 })
+          )
+        );
+      });
+
+      for (const engine of ['playwright', 'puppeteer']) {
+        it(
+          `${engine} is indistinguishable from a hand-started Chrome`,
+          { timeout: TEST_TIMEOUT },
+          async () => {
+            const { report } = await captureWithLibrary({ engine });
+            const differences = diffReports(reference, report);
+
+            assert.deepEqual(
+              differences,
+              [],
+              `${engine} differs from a real ${mode} browser in: ${differences
+                .map((entry) => entry.path)
+                .join(', ')}`
+            );
+          }
+        );
+
+        it(
+          `${engine} leaks navigator.webdriver once parity is turned off`,
+          { timeout: TEST_TIMEOUT },
+          async () => {
+            // Negative control: without this the parity assertion above could
+            // pass for the wrong reason, for example because the probe stopped
+            // reporting the field.
+            const { report } = await captureWithLibrary({
+              engine,
+              automationParity: false,
+            });
+            const paths = diffReports(reference, report).map(
+              (entry) => entry.path
+            );
+
+            assert.ok(
+              paths.includes('navigator.webdriver'),
+              `expected navigator.webdriver to leak, saw: ${paths.join(', ')}`
+            );
+          }
+        );
+
+        it(
+          `${engine} presents the fingerprint profile it was launched with`,
+          { timeout: TEST_TIMEOUT },
+          async () => {
+            const profile = createFingerprintPreset('macos-chrome', {
+              overrides: {
+                timezoneId: 'Australia/Sydney',
+                languages: ['pt-BR', 'pt', 'en'],
+                hardwareConcurrency: 6,
+              },
+            });
+            const { report, token } = await captureWithLibrary({
+              engine,
+              fingerprint: profile,
+            });
+
+            assert.equal(report.navigator.userAgent, profile.userAgent);
+            assert.equal(report.navigator.platform, profile.platform);
+            assert.equal(report.navigator.hardwareConcurrency, 6);
+            assert.equal(report.navigator.deviceMemory, profile.deviceMemory);
+            assert.deepEqual(report.navigator.languages, ['pt-BR', 'pt', 'en']);
+            assert.equal(report.intl.dateTimeTimeZone, 'Australia/Sydney');
+            assert.equal(report.screen.width, profile.screen.width);
+            assert.equal(report.screen.availHeight, profile.screen.availHeight);
+            assert.equal(report.screen.colorDepth, profile.screen.colorDepth);
+            // A machine with no GPU stack reports no WebGL context at all, and
+            // there is then nothing for the renderer patch to replace.
+            if (report.webgl.webgl1) {
+              assert.equal(
+                report.webgl.webgl1.unmaskedVendor,
+                profile.webgl.unmaskedVendor
+              );
+              assert.equal(report.webgl.webgl1.vendor, profile.webgl.vendor);
+            }
+            // The overrides Chrome enforces itself reach the network stack
+            // too, which a JavaScript property patch never would. Chrome
+            // builds the quality ladder from the plain list, exactly as it
+            // does for a real browser configured with these languages.
+            assert.equal(
+              server.headersFor(token)['accept-language'],
+              'pt-BR,pt;q=0.9,en;q=0.8'
+            );
+            assert.equal(
+              server.headersFor(token)['user-agent'],
+              profile.userAgent
+            );
+          }
+        );
+      }
+    }
+  );
+}
+
+defineParitySuite({ headless: false });
+defineParitySuite({ headless: true });

package/tests/helpers/mocks.js

@@ -530,7 +530,8 @@ export const assert = {
     } catch (error) {
       if (expectedError && !error.message.includes(expectedError)) {
         throw new Error(
-          `${message}: Expected error message to include "${expectedError}", got "${error.message}"`
+          `${message}: Expected error message to include "${expectedError}", got "${error.message}"`,
+          { cause: error }
         );
       }
     }
@@ -540,7 +541,8 @@ export const assert = {
       await fn();
     } catch (error) {
       throw new Error(
-        `${message}: Expected function not to throw, but got: ${error.message}`
+        `${message}: Expected function not to throw, but got: ${error.message}`,
+        { cause: error }
       );
     }
   },

package/tests/helpers/repo.js

@@ -0,0 +1,74 @@
+/**
+ * Where the repository is, and how to run one of its shell scripts.
+ *
+ * Several checks this repository ships are bash scripts that a workflow calls
+ * directly (`scripts/check-pipeline-status.sh`,
+ * `scripts/run-with-budget-warning.sh`). Testing one means resolving the
+ * repository root from the test file, spawning bash with a controlled
+ * environment, and reading stdout and stderr together - CI interleaves them,
+ * and a `::error::` annotation is only useful if the assertion sees it in the
+ * same stream the runner does.
+ *
+ * Every test that needs those three things imports them from here, so the
+ * duplication gate (`npm run check:duplication`) stays quiet and a change to
+ * the spawning contract happens in one place.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const REPO_ROOT = path.resolve(
+  fileURLToPath(new URL('.', import.meta.url)),
+  '../../..'
+);
+
+/** Absolute path to a file, named the way the repository names it. */
+export function repoPath(...segments) {
+  return path.join(REPO_ROOT, ...segments);
+}
+
+/**
+ * Newlines as the assertions expect them.
+ *
+ * A Windows runner checks the repository out with CRLF endings, so text read
+ * straight off disk there does not contain the `\n` a matcher written on Linux
+ * looks for. Normalizing at the read is the difference between a test that
+ * checks the repository and a test that checks the operating system.
+ */
+export function normalizeNewlines(text) {
+  return text.replaceAll('\r\n', '\n');
+}
+
+/** Read a repository file as text, with newlines normalized. */
+export function readRepoText(...segments) {
+  return normalizeNewlines(readFileSync(repoPath(...segments), 'utf8'));
+}
+
+/**
+ * False on a runner without bash (a plain Windows image), where a test of a
+ * bash script has nothing to say. Suites use it as `{ skip: !BASH_AVAILABLE }`
+ * rather than asserting on an absent interpreter.
+ */
+export const BASH_AVAILABLE =
+  spawnSync('bash', ['-c', 'exit 0'], { encoding: 'utf8' }).status === 0;
+
+/**
+ * Run a bash script and return its exit status with stdout and stderr joined.
+ *
+ * `env` is merged over the caller's environment rather than replacing it: the
+ * scripts under test call `node` and `git`, which need PATH.
+ */
+export function runBashScript(scriptPath, args = [], options = {}) {
+  const result = spawnSync('bash', [scriptPath, ...args], {
+    cwd: options.cwd ?? REPO_ROOT,
+    encoding: 'utf8',
+    env: { ...process.env, ...options.env },
+  });
+
+  return {
+    status: result.status,
+    output: `${result.stdout ?? ''}${result.stderr ?? ''}`,
+  };
+}

package/tests/unit/browser/launch-options.test.js

@@ -56,10 +56,18 @@ describe('browser launch options', () => {
     });
 
     assert.deepEqual(playwright.ignoreDefaultArgs, [
+      '--enable-automation',
+      // Playwright also forces software WebGL on, which a hand-started Chrome
+      // without a usable GPU refuses to do.
+      '--enable-unsafe-swiftshader',
+      '--no-first-run',
+    ]);
+    // Puppeteer passes --enable-automation by default, so automation parity
+    // has to suppress it there too.
+    assert.deepEqual(puppeteer.ignoreDefaultArgs, [
       '--enable-automation',
       '--no-first-run',
     ]);
-    assert.deepEqual(puppeteer.ignoreDefaultArgs, ['--no-first-run']);
   });
 
   it('forwards channel and executablePath to Playwright', () => {

package/tests/unit/experiments/fingerprint-parity-harness.test.js

@@ -0,0 +1,97 @@
+/**
+ * The projection the parity runners compare on.
+ *
+ * Three runners used to read the probe report through long
+ * `report?.a?.b ?? null` chains - flat tables of twenty-odd fields that ESLint
+ * counted as functions with a cyclomatic complexity of 40, 50 and 53. The
+ * chains are now paths through readReportPath(), so these tests pin the two
+ * properties the runners depended on: a missing level yields the fallback
+ * rather than throwing, and a value that is present is returned unchanged even
+ * when it is falsy.
+ */
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import {
+  projectReport,
+  readReportPath,
+} from '../../../../experiments/fingerprint-parity/harness.mjs';
+
+describe('readReportPath', () => {
+  it('reads a nested value', () => {
+    assert.equal(
+      readReportPath({ webgl: { webgl1: { unmaskedVendor: 'Intel' } } }, [
+        'webgl',
+        'webgl1',
+        'unmaskedVendor',
+      ]),
+      'Intel'
+    );
+  });
+
+  it('returns the fallback for a level the report never sent', () => {
+    // A browser that failed half the probe still POSTs what it collected, so
+    // every level of the path can be absent.
+    assert.equal(
+      readReportPath({}, ['webgl', 'webgl1', 'unmaskedVendor']),
+      undefined
+    );
+    assert.equal(
+      readReportPath(undefined, ['navigator', 'webdriver'], null),
+      null
+    );
+    assert.equal(
+      readReportPath({ intl: null }, ['intl', 'dateTimeLocale'], null),
+      null
+    );
+  });
+
+  it('keeps a falsy value that the report actually reported', () => {
+    // `navigator.webdriver: false` is the single most important reading in the
+    // whole suite; a fallback applied to it would report a pass as a miss.
+    assert.equal(
+      readReportPath(
+        { navigator: { webdriver: false } },
+        ['navigator', 'webdriver'],
+        null
+      ),
+      false
+    );
+    assert.equal(
+      readReportPath({ plugins: [] }, ['plugins', 'length'], null),
+      0
+    );
+  });
+
+  it('reads a key that is not an identifier', () => {
+    assert.equal(
+      readReportPath({ mediaQueries: { '(pointer: coarse)': true } }, [
+        'mediaQueries',
+        '(pointer: coarse)',
+      ]),
+      true
+    );
+  });
+});
+
+describe('projectReport', () => {
+  it('names every field it was asked for, present or not', () => {
+    const projected = projectReport(
+      { navigator: { webdriver: false } },
+      {
+        webdriver: ['navigator', 'webdriver'],
+        userAgent: ['navigator', 'userAgent'],
+      },
+      null
+    );
+
+    assert.deepEqual(projected, { webdriver: false, userAgent: null });
+  });
+
+  it('leaves an absent field undefined when no fallback is given', () => {
+    assert.deepEqual(projectReport({}, { screen: ['screen'] }), {
+      screen: undefined,
+    });
+  });
+});

package/tests/unit/fingerprint/apply.test.js

@@ -0,0 +1,271 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import {
+  applyFingerprint,
+  createCdpSession,
+} from '../../../src/fingerprint/apply.js';
+import { createFingerprintPreset } from '../../../src/fingerprint/presets.js';
+
+/** A CDP session that records what was sent instead of talking to Chrome. */
+function createRecordingSession() {
+  const sent = [];
+  return {
+    sent,
+    methods: () => sent.map((entry) => entry.method),
+    send(method, params) {
+      sent.push({ method, params });
+      return Promise.resolve({});
+    },
+  };
+}
+
+/** Minimal stand-ins for the two engines' object graphs. */
+function createPlaywrightDouble() {
+  const session = createRecordingSession();
+  const listeners = new Map();
+  const page = {};
+  const browser = {
+    newCDPSession(target) {
+      browser.cdpTargets.push(target);
+      return Promise.resolve(session);
+    },
+    cdpTargets: [],
+    on(event, handler) {
+      listeners.set(event, handler);
+    },
+    emit: (event, argument) => listeners.get(event)?.(argument),
+    listeners,
+  };
+  return { browser, page, session };
+}
+
+function createPuppeteerDouble() {
+  const session = createRecordingSession();
+  const listeners = new Map();
+  const page = {
+    createCDPSession: () => Promise.resolve(session),
+  };
+  const browser = {
+    on(event, handler) {
+      listeners.set(event, handler);
+    },
+    emit: (event, argument) => listeners.get(event)?.(argument),
+    listeners,
+  };
+  return { browser, page, session };
+}
+
+describe('opening a CDP session', () => {
+  it('uses the Playwright context that launchBrowser hands back', async () => {
+    const { browser, page, session } = createPlaywrightDouble();
+
+    assert.equal(
+      await createCdpSession({ browser, page, engine: 'playwright' }),
+      session
+    );
+    assert.deepEqual(browser.cdpTargets, [page]);
+  });
+
+  it('falls back to the page context when the browser has no newCDPSession', async () => {
+    const session = createRecordingSession();
+    const context = { newCDPSession: () => Promise.resolve(session) };
+    const page = { context: () => context };
+
+    assert.equal(
+      await createCdpSession({ browser: {}, page, engine: 'playwright' }),
+      session
+    );
+  });
+
+  it('uses page.createCDPSession on Puppeteer', async () => {
+    const { page, session } = createPuppeteerDouble();
+
+    assert.equal(
+      await createCdpSession({ browser: {}, page, engine: 'puppeteer' }),
+      session
+    );
+  });
+
+  it('falls back to the target on older Puppeteer pages', async () => {
+    const session = createRecordingSession();
+    const page = {
+      target: () => ({ createCDPSession: () => Promise.resolve(session) }),
+    };
+
+    assert.equal(
+      await createCdpSession({ browser: {}, page, engine: 'puppeteer' }),
+      session
+    );
+  });
+});
+
+describe('applying a fingerprint', () => {
+  const profile = createFingerprintPreset('windows-chrome');
+
+  it('requires a page', async () => {
+    await assert.rejects(
+      () => applyFingerprint({ profile }),
+      /requires a page/u
+    );
+  });
+
+  it('sends the emulation commands before installing the init script', async () => {
+    const { browser, page, session } = createPlaywrightDouble();
+
+    await applyFingerprint({ browser, page, engine: 'playwright', profile });
+
+    const methods = session.methods();
+    const firstScriptIndex = methods.indexOf('Page.enable');
+    assert.ok(firstScriptIndex > 0);
+    assert.ok(
+      methods
+        .slice(0, firstScriptIndex)
+        .every((method) => method.startsWith('Emulation.'))
+    );
+  });
+
+  it('enables the Page domain before adding the script, then patches the open document', async () => {
+    const { browser, page, session } = createPlaywrightDouble();
+
+    await applyFingerprint({ browser, page, engine: 'playwright', profile });
+
+    // Measured: without Page.enable, Chrome accepts
+    // addScriptToEvaluateOnNewDocument and never runs the script.
+    assert.deepEqual(
+      session.methods().filter((method) => !method.startsWith('Emulation.')),
+      [
+        'Page.enable',
+        'Page.addScriptToEvaluateOnNewDocument',
+        'Runtime.evaluate',
+      ]
+    );
+    const [, added, evaluated] = session.sent.slice(-3);
+    assert.equal(added.params.source, evaluated.params.expression);
+    assert.equal(evaluated.params.returnByValue, true);
+  });
+
+  it('normalizes a raw profile and reports what it sent', async () => {
+    const { browser, page, session } = createPlaywrightDouble();
+
+    const result = await applyFingerprint({
+      browser,
+      page,
+      engine: 'playwright',
+      profile: { timezoneId: 'Europe/Berlin', deviceMemory: 8 },
+    });
+
+    assert.ok(Object.isFrozen(result.profile));
+    assert.deepEqual(result.commands, [
+      {
+        method: 'Emulation.setTimezoneOverride',
+        params: { timezoneId: 'Europe/Berlin' },
+      },
+    ]);
+    assert.match(result.initScript, /deviceMemory/u);
+    assert.equal(session.methods()[0], 'Emulation.setTimezoneOverride');
+  });
+
+  it('rejects a raw profile with an unknown field', async () => {
+    const { browser, page } = createPlaywrightDouble();
+
+    await assert.rejects(
+      () => applyFingerprint({ browser, page, profile: { cpuModel: 'M3' } }),
+      /cpuModel/u
+    );
+  });
+
+  it('skips the script commands when the browser overrides cover everything', async () => {
+    const { browser, page, session } = createPlaywrightDouble();
+
+    const result = await applyFingerprint({
+      browser,
+      page,
+      engine: 'playwright',
+      profile: { timezoneId: 'UTC' },
+    });
+
+    assert.equal(result.initScript, null);
+    assert.deepEqual(session.methods(), ['Emulation.setTimezoneOverride']);
+  });
+
+  it('applies the same profile to a page opened later on Playwright', async () => {
+    const { browser, page, session } = createPlaywrightDouble();
+
+    await applyFingerprint({ browser, page, engine: 'playwright', profile });
+    const before = session.sent.length;
+    const laterPage = {};
+    await browser.emit('page', laterPage);
+
+    assert.equal(session.sent.length, before * 2);
+    assert.deepEqual(browser.cdpTargets, [page, laterPage]);
+  });
+
+  it('applies the same profile to a target opened later on Puppeteer', async () => {
+    const { browser, page, session } = createPuppeteerDouble();
+
+    await applyFingerprint({ browser, page, engine: 'puppeteer', profile });
+    const before = session.sent.length;
+    await browser.emit('targetcreated', {
+      page: () =>
+        Promise.resolve({ createCDPSession: () => Promise.resolve(session) }),
+    });
+
+    assert.equal(session.sent.length, before * 2);
+  });
+
+  it('ignores a new target that is not a page', async () => {
+    const { browser, page, session } = createPuppeteerDouble();
+
+    await applyFingerprint({ browser, page, engine: 'puppeteer', profile });
+    const before = session.sent.length;
+    await browser.emit('targetcreated', { page: () => Promise.resolve(null) });
+
+    assert.equal(session.sent.length, before);
+  });
+
+  it('survives a page that closes before its session is ready', async () => {
+    const { browser, page } = createPlaywrightDouble();
+
+    await applyFingerprint({ browser, page, engine: 'playwright', profile });
+    browser.newCDPSession = () => Promise.reject(new Error('Target closed'));
+
+    await assert.doesNotReject(() => browser.emit('page', {}));
+  });
+
+  it('does not hook new pages when asked not to', async () => {
+    const { browser, page } = createPlaywrightDouble();
+
+    await applyFingerprint({
+      browser,
+      page,
+      engine: 'playwright',
+      profile,
+      applyToNewPages: false,
+    });
+
+    assert.equal(browser.listeners.size, 0);
+  });
+
+  it('adds the webdriver patch only when asked', async () => {
+    const { browser, page } = createPlaywrightDouble();
+
+    const plain = await applyFingerprint({
+      browser,
+      page,
+      engine: 'playwright',
+      profile: { timezoneId: 'UTC' },
+    });
+    assert.equal(plain.initScript, null);
+
+    const patched = await applyFingerprint({
+      browser,
+      page,
+      engine: 'playwright',
+      profile: { timezoneId: 'UTC' },
+      patchWebdriver: true,
+      applyToNewPages: false,
+    });
+    assert.match(patched.initScript, /"webdriver":false/u);
+  });
+});