browser-commander 0.16.0 → 0.17.0

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);
+  });
+});

package/tests/unit/fingerprint/automation-parity.test.js

@@ -0,0 +1,212 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import {
+  applyAutomationParityArgs,
+  AUTOMATION_CONTROLLED_OFF_ARG,
+  AUTOMATION_CONTROLLED_TRIGGERS,
+  detectAutomationControlledTriggers,
+  disablesAutomationControlled,
+  ENGINE_PARITY_IGNORED_DEFAULT_ARGS,
+  parityIgnoredDefaultArgs,
+  PLAYWRIGHT_HEADLESS_POINTER_ARG,
+  PLAYWRIGHT_SOFTWARE_WEBGL_ARG,
+} from '../../../src/fingerprint/automation-parity.js';
+
+describe('AutomationControlled triggers', () => {
+  it('documents a reason for every trigger', () => {
+    assert.ok(AUTOMATION_CONTROLLED_TRIGGERS.length > 0);
+    for (const trigger of AUTOMATION_CONTROLLED_TRIGGERS) {
+      assert.equal(typeof trigger.switch, 'string');
+      assert.ok(trigger.reason.length > 0, `${trigger.switch} needs a reason`);
+    }
+  });
+
+  it('finds each switch Chromium maps onto the feature', () => {
+    const found = detectAutomationControlledTriggers([
+      '--enable-automation',
+      '--headless=new',
+      '--remote-debugging-pipe',
+      '--remote-debugging-port=0',
+    ]).map((entry) => entry.switch);
+
+    assert.deepEqual(found, [
+      '--enable-automation',
+      '--headless',
+      '--remote-debugging-pipe',
+      '--remote-debugging-port=0',
+    ]);
+  });
+
+  it('reports the argument as written next to the switch it matched', () => {
+    assert.deepEqual(
+      detectAutomationControlledTriggers(['--headless=new'])[0].argument,
+      '--headless=new'
+    );
+  });
+
+  it('leaves a fixed debugging port alone', () => {
+    // runtime_features.cc treats only an ephemeral port as automation, because
+    // a specific port is what a human attaching a debugger passes.
+    assert.deepEqual(
+      detectAutomationControlledTriggers(['--remote-debugging-port=9222']),
+      []
+    );
+  });
+
+  it('finds nothing in an ordinary command line', () => {
+    assert.deepEqual(
+      detectAutomationControlledTriggers([
+        '--no-first-run',
+        '--window-size=1280,720',
+      ]),
+      []
+    );
+  });
+
+  it('rejects a non-array or a non-string argument', () => {
+    assert.throws(
+      () => detectAutomationControlledTriggers('--headless'),
+      /must be an array of strings/u
+    );
+    assert.throws(
+      () => detectAutomationControlledTriggers([1]),
+      /must be an array of strings/u
+    );
+  });
+});
+
+describe('applying automation parity to a command line', () => {
+  it('appends the switch that turns the feature back off', () => {
+    assert.deepEqual(applyAutomationParityArgs(['--no-first-run']), [
+      '--no-first-run',
+      AUTOMATION_CONTROLLED_OFF_ARG,
+    ]);
+  });
+
+  it('works on an empty command line and on no command line at all', () => {
+    assert.deepEqual(applyAutomationParityArgs([]), [
+      AUTOMATION_CONTROLLED_OFF_ARG,
+    ]);
+    assert.deepEqual(applyAutomationParityArgs(), [
+      AUTOMATION_CONTROLLED_OFF_ARG,
+    ]);
+  });
+
+  it('is idempotent', () => {
+    const once = applyAutomationParityArgs(['--no-first-run']);
+    assert.deepEqual(applyAutomationParityArgs(once), once);
+  });
+
+  it('extends an existing feature list instead of duplicating the switch', () => {
+    // Chrome keeps only the last --disable-blink-features occurrence, so a
+    // second one would silently drop the caller's features.
+    assert.deepEqual(
+      applyAutomationParityArgs(['--disable-blink-features=AcceptCHFrame']),
+      ['--disable-blink-features=AcceptCHFrame,AutomationControlled']
+    );
+  });
+
+  it('does not copy the input array back to the caller', () => {
+    const args = ['--no-first-run'];
+    assert.notEqual(applyAutomationParityArgs(args), args);
+    assert.deepEqual(args, ['--no-first-run']);
+  });
+
+  it('rejects a non-array', () => {
+    assert.throws(
+      () => applyAutomationParityArgs('--no-first-run'),
+      /must be an array of strings/u
+    );
+  });
+
+  it('recognises the feature inside a longer list', () => {
+    assert.equal(
+      disablesAutomationControlled([
+        '--disable-blink-features=AcceptCHFrame, AutomationControlled',
+      ]),
+      true
+    );
+    assert.equal(
+      disablesAutomationControlled(['--disable-blink-features=AcceptCHFrame']),
+      false
+    );
+    assert.equal(disablesAutomationControlled([]), false);
+    // Enabling is not disabling.
+    assert.equal(
+      disablesAutomationControlled([
+        '--enable-blink-features=AutomationControlled',
+      ]),
+      false
+    );
+  });
+});
+
+describe('engine default switches to suppress', () => {
+  it('suppresses --enable-automation on both engines', () => {
+    for (const engine of ['playwright', 'puppeteer']) {
+      assert.ok(
+        parityIgnoredDefaultArgs(engine).includes('--enable-automation'),
+        `${engine} must suppress --enable-automation`
+      );
+    }
+  });
+
+  it('suppresses the Playwright headless pointer switch only when headless', () => {
+    // Playwright forces hover:hover and pointer:fine in headless Chrome, which
+    // a real headless browser never reports; see parity-headless.json.
+    assert.ok(
+      !parityIgnoredDefaultArgs('playwright').includes(
+        PLAYWRIGHT_HEADLESS_POINTER_ARG
+      )
+    );
+    assert.ok(
+      parityIgnoredDefaultArgs('playwright', { headless: true }).includes(
+        PLAYWRIGHT_HEADLESS_POINTER_ARG
+      )
+    );
+  });
+
+  it('suppresses the Playwright software-WebGL switch in both modes', () => {
+    // Playwright 1.62 pushes --enable-unsafe-swiftshader on every platform, so
+    // a machine with no usable GPU answers getContext('webgl') with a
+    // SwiftShader context where a hand-started Chrome answers null. Measured in
+    // analysis-artifacts/parity-webgl-swiftshader.json; the switch has to go in
+    // both modes, because headless Chrome turns SwiftShader on by itself.
+    for (const headless of [false, true]) {
+      assert.ok(
+        parityIgnoredDefaultArgs('playwright', { headless }).includes(
+          PLAYWRIGHT_SOFTWARE_WEBGL_ARG
+        ),
+        `playwright must suppress ${PLAYWRIGHT_SOFTWARE_WEBGL_ARG} when headless=${headless}`
+      );
+    }
+  });
+
+  it('has nothing extra to suppress for headless Puppeteer', () => {
+    assert.deepEqual(
+      parityIgnoredDefaultArgs('puppeteer', { headless: true }),
+      ['--enable-automation']
+    );
+  });
+
+  it('rejects an unknown engine by name', () => {
+    assert.throws(
+      () => parityIgnoredDefaultArgs('selenium'),
+      /unknown engine "selenium"/u
+    );
+  });
+
+  it('does not let a caller mutate the shared table', () => {
+    assert.ok(Object.isFrozen(ENGINE_PARITY_IGNORED_DEFAULT_ARGS));
+    assert.ok(
+      Object.isFrozen(ENGINE_PARITY_IGNORED_DEFAULT_ARGS.playwright.always)
+    );
+    const result = parityIgnoredDefaultArgs('playwright');
+    result.push('--mutated');
+    assert.deepEqual(parityIgnoredDefaultArgs('playwright'), [
+      '--enable-automation',
+      PLAYWRIGHT_SOFTWARE_WEBGL_ARG,
+    ]);
+  });
+});