browser-commander 0.16.1 → 0.17.0

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

package/tests/unit/fingerprint/cdp-overrides.test.js

@@ -0,0 +1,227 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import { buildCdpEmulationCommands } from '../../../src/fingerprint/cdp-overrides.js';
+import { resolveFingerprintProfile } from '../../../src/fingerprint/profile.js';
+
+function methodsOf(profile) {
+  return buildCdpEmulationCommands(resolveFingerprintProfile(profile)).map(
+    (command) => command.method
+  );
+}
+
+function paramsOf(profile, method) {
+  const command = buildCdpEmulationCommands(
+    resolveFingerprintProfile(profile)
+  ).find((entry) => entry.method === method);
+  return command?.params;
+}
+
+describe('CDP emulation commands', () => {
+  it('rejects anything that is not a profile object', () => {
+    assert.throws(
+      () => buildCdpEmulationCommands(null),
+      /must be a normalized fingerprint profile/u
+    );
+    assert.throws(
+      () => buildCdpEmulationCommands('windows'),
+      /must be a normalized fingerprint profile/u
+    );
+  });
+
+  it('emits nothing for an empty profile', () => {
+    assert.deepEqual(
+      buildCdpEmulationCommands(resolveFingerprintProfile({})),
+      []
+    );
+  });
+
+  it('sends only the commands the profile asks for', () => {
+    assert.deepEqual(methodsOf({ timezoneId: 'Europe/Berlin' }), [
+      'Emulation.setTimezoneOverride',
+    ]);
+    assert.deepEqual(methodsOf({ hardwareConcurrency: 4 }), [
+      'Emulation.setHardwareConcurrencyOverride',
+    ]);
+  });
+
+  it('keeps a stable command order for a full profile', () => {
+    assert.deepEqual(
+      methodsOf({
+        userAgent:
+          'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+          '(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36',
+        timezoneId: 'Europe/Berlin',
+        locale: 'de-DE',
+        hardwareConcurrency: 12,
+        screen: { width: 2560, height: 1440 },
+        viewport: { width: 1280, height: 720 },
+        maxTouchPoints: 0,
+        colorScheme: 'dark',
+        geolocation: { latitude: 52.52, longitude: 13.405, accuracy: 20 },
+      }),
+      [
+        'Emulation.setUserAgentOverride',
+        'Emulation.setTimezoneOverride',
+        'Emulation.setLocaleOverride',
+        'Emulation.setHardwareConcurrencyOverride',
+        'Emulation.setDeviceMetricsOverride',
+        'Emulation.setTouchEmulationEnabled',
+        'Emulation.setEmulatedMedia',
+        'Emulation.setGeolocationOverride',
+      ]
+    );
+  });
+
+  it('supplies the required empty user agent when only the language changes', () => {
+    const params = paramsOf(
+      { languages: ['fr-FR', 'fr'] },
+      'Emulation.setUserAgentOverride'
+    );
+    // userAgent is a required protocol parameter; an empty string means
+    // "leave it alone" while acceptLanguage still takes effect.
+    assert.equal(params.userAgent, '');
+    assert.equal(params.acceptLanguage, 'fr-FR,fr');
+  });
+
+  it('carries the client hints, including the deprecated full version', () => {
+    const params = paramsOf(
+      {
+        userAgent:
+          'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+          '(KHTML, like Gecko) Chrome/140.0.7000.55 Safari/537.36',
+        platform: 'Win32',
+      },
+      'Emulation.setUserAgentOverride'
+    );
+
+    assert.equal(params.platform, 'Win32');
+    assert.equal(params.userAgentMetadata.platform, 'Windows');
+    // fullVersionList does not cover the uaFullVersion hint, so the deprecated
+    // fullVersion field has to travel with it.
+    assert.equal(params.userAgentMetadata.fullVersion, '140.0.7000.55');
+    assert.equal(params.userAgentMetadata.bitness, '64');
+    assert.equal(params.userAgentMetadata.wow64, false);
+    assert.deepEqual(params.userAgentMetadata.formFactors, ['Desktop']);
+  });
+
+  it('always fills the protocol-required metadata fields', () => {
+    const params = paramsOf(
+      {
+        userAgent: 'custom agent',
+        userAgentData: { brands: [{ brand: 'Custom', version: '1' }] },
+      },
+      'Emulation.setUserAgentOverride'
+    );
+
+    // Chrome rejects setUserAgentOverride when any of these is missing.
+    for (const field of [
+      'platform',
+      'platformVersion',
+      'architecture',
+      'model',
+      'mobile',
+    ]) {
+      assert.ok(field in params.userAgentMetadata, `${field} must be present`);
+    }
+    assert.equal(params.userAgentMetadata.mobile, false);
+    assert.ok(!('bitness' in params.userAgentMetadata));
+  });
+
+  it('copies the brand entries instead of sharing them with the profile', () => {
+    const profile = resolveFingerprintProfile({
+      userAgent:
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+        '(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36',
+    });
+    const [{ params }] = buildCdpEmulationCommands(profile);
+
+    assert.notEqual(
+      params.userAgentMetadata.brands,
+      profile.userAgentData.brands
+    );
+    assert.notEqual(
+      params.userAgentMetadata.brands[0],
+      profile.userAgentData.brands[0]
+    );
+  });
+
+  it('leaves the window size alone when only the screen is described', () => {
+    const params = paramsOf(
+      { screen: { width: 2560, height: 1440 } },
+      'Emulation.setDeviceMetricsOverride'
+    );
+
+    // Zeroes mean "no override" for the viewport, so a screen-only profile
+    // does not resize the window it was applied to.
+    assert.deepEqual(params, {
+      width: 0,
+      height: 0,
+      deviceScaleFactor: 0,
+      mobile: false,
+      screenWidth: 2560,
+      screenHeight: 1440,
+    });
+  });
+
+  it('sends the viewport without screen dimensions when no screen is set', () => {
+    assert.deepEqual(
+      paramsOf(
+        {
+          viewport: {
+            width: 1280,
+            height: 720,
+            deviceScaleFactor: 2,
+            mobile: true,
+          },
+        },
+        'Emulation.setDeviceMetricsOverride'
+      ),
+      { width: 1280, height: 720, deviceScaleFactor: 2, mobile: true }
+    );
+  });
+
+  it('disables touch emulation for a desktop profile that names zero touch points', () => {
+    // maxTouchPoints must stay at least 1 because the protocol rejects 0, so
+    // "no touch" is expressed through enabled instead.
+    assert.deepEqual(
+      paramsOf({ maxTouchPoints: 0 }, 'Emulation.setTouchEmulationEnabled'),
+      { enabled: false, maxTouchPoints: 1 }
+    );
+    assert.deepEqual(
+      paramsOf({ maxTouchPoints: 5 }, 'Emulation.setTouchEmulationEnabled'),
+      { enabled: true, maxTouchPoints: 5 }
+    );
+  });
+
+  it('collects every media preference into a single command', () => {
+    assert.deepEqual(
+      paramsOf(
+        {
+          colorScheme: 'dark',
+          reducedMotion: 'reduce',
+          forcedColors: 'active',
+        },
+        'Emulation.setEmulatedMedia'
+      ),
+      {
+        features: [
+          { name: 'prefers-reduced-motion', value: 'reduce' },
+          { name: 'forced-colors', value: 'active' },
+          { name: 'prefers-color-scheme', value: 'dark' },
+        ],
+      }
+    );
+  });
+
+  it('passes geolocation through as its own copy', () => {
+    const geolocation = { latitude: 48.85, longitude: 2.35, accuracy: 10 };
+    const params = paramsOf(
+      { geolocation },
+      'Emulation.setGeolocationOverride'
+    );
+
+    assert.deepEqual(params, geolocation);
+    assert.notEqual(params, geolocation);
+  });
+});

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

@@ -0,0 +1,105 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import { deriveUserAgentData } from '../../../src/fingerprint/derive.js';
+
+describe('client hints derived from a user agent', () => {
+  it('returns null when the string names no Chrome version', () => {
+    assert.equal(
+      deriveUserAgentData(
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ' +
+          'AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15'
+      ),
+      null
+    );
+  });
+
+  it('rejects a non-string user agent', () => {
+    assert.throws(() => deriveUserAgentData(undefined), /must be a string/u);
+  });
+
+  it('maps a Windows user agent onto the Windows platform hints', () => {
+    const data = deriveUserAgentData(
+      'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+        '(KHTML, like Gecko) Chrome/140.0.7000.55 Safari/537.36'
+    );
+
+    assert.equal(data.platform, 'Windows');
+    assert.equal(data.architecture, 'x86');
+    assert.equal(data.bitness, '64');
+    assert.equal(data.mobile, false);
+    assert.deepEqual(data.formFactors, ['Desktop']);
+    // Chrome froze the user agent at "Windows NT 10.0" and reports the real
+    // version only through platformVersion, where 13 and up mean Windows 11.
+    assert.equal(data.platformVersion, '15.0.0');
+    assert.equal(data.fullVersion, '140.0.7000.55');
+  });
+
+  it('pads a major-only Chrome version into a four part full version', () => {
+    const data = deriveUserAgentData(
+      'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+        '(KHTML, like Gecko) Chrome/141 Safari/537.36'
+    );
+
+    assert.equal(data.fullVersion, '141.0.0.0');
+    assert.deepEqual(
+      data.brands.map((entry) => entry.version),
+      ['141', '141', '24']
+    );
+  });
+
+  it('parses the macOS version out of the user agent', () => {
+    const data = deriveUserAgentData(
+      'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ' +
+        '(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36'
+    );
+
+    assert.equal(data.platform, 'macOS');
+    assert.equal(data.platformVersion, '10.15.7');
+  });
+
+  it('reports an Android phone as mobile and recovers the model', () => {
+    const data = deriveUserAgentData(
+      'Mozilla/5.0 (Linux; Android 14; Pixel 8 Build/UQ1A.240105.004) ' +
+        'AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Mobile Safari/537.36'
+    );
+
+    assert.equal(data.platform, 'Android');
+    assert.equal(data.platformVersion, '14');
+    assert.equal(data.mobile, true);
+    assert.equal(data.model, 'Pixel 8');
+    assert.deepEqual(data.formFactors, ['Mobile']);
+  });
+
+  it('recognises Linux and Chrome OS', () => {
+    assert.equal(
+      deriveUserAgentData(
+        'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 ' +
+          '(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36'
+      ).platform,
+      'Linux'
+    );
+    assert.equal(
+      deriveUserAgentData(
+        'Mozilla/5.0 (X11; CrOS x86_64 14541.0.0) AppleWebKit/537.36 ' +
+          '(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36'
+      ).platform,
+      'Chrome OS'
+    );
+  });
+
+  it('includes the GREASE brand so the brand list has a real browser shape', () => {
+    const data = deriveUserAgentData(
+      'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+        '(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36'
+    );
+
+    assert.equal(data.brands.length, 3);
+    assert.ok(data.brands.some((entry) => entry.brand === 'Not=A?Brand'));
+    assert.ok(
+      data.fullVersionList.every(
+        (entry) => entry.version.split('.').length === 4
+      )
+    );
+  });
+});