browser-commander 0.20.0 → 0.21.0

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

@@ -23,10 +23,6 @@
  */
 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 {
@@ -34,25 +30,26 @@ import {
   diffReports,
   readProbeSource,
   startProbeServer,
-} from '../../../experiments/fingerprint-parity/harness.mjs';
-import { launchBrowser } from '../../src/index.js';
+} from '../../src/parity/harness.js';
+import { launchBrowser, launchRealBrowser } from '../../src/index.js';
 import { createFingerprintPreset } from '../../src/fingerprint/presets.js';
+import {
+  PARITY_CHROME as CHROME,
+  paritySkipReason as skipReason,
+} from '../helpers/e2e-browser.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;
+/** Fail with every differing path when `report` is not `reference`. */
+function assertIndistinguishable(reference, report, label) {
+  const differences = diffReports(reference, report);
+  assert.deepEqual(
+    differences,
+    [],
+    `${label} differs from a hand-started browser in: ${differences
+      .map((entry) => entry.path)
+      .join(', ')}`
+  );
 }
 
 function defineParitySuite({ headless }) {
@@ -64,29 +61,48 @@ function defineParitySuite({ 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. With no `launch`
+       * option that is the default real launch: a fresh temporary profile and
+       * a clean command line (issue #103).
+       */
+      const captureWithLibrary = async (options) => {
+        const token = randomUUID();
+        const launched = await launchBrowser({
+          headless,
+          executablePath: CHROME,
+          ...options,
+        });
+        try {
+          await launched.page.goto(server.url(token), { waitUntil: 'load' });
+          return {
+            report: await server.waitForReport(token),
+            token,
+            launched,
+          };
+        } finally {
+          await launched.browser.close();
+        }
       };
 
-      /** Drive one capture through the shipped launcher. */
-      const captureWithLibrary = async (options) => {
+      /**
+       * Drive one capture through the real-browser launcher: Chrome is spawned
+       * with `--user-data-dir` and a reserved `--remote-debugging-port` only,
+       * and the engine attaches over CDP afterwards (issue #101).
+       */
+      const captureWithRealBrowser = async (options) => {
         const token = randomUUID();
-        const { browser, page } = await launchBrowser({
+        const session = await launchRealBrowser({
           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 };
+          await session.page.goto(server.url(token), { waitUntil: 'load' });
+          return { report: await server.waitForReport(token), session };
         } finally {
-          await browser.close();
+          await session.close();
         }
       };
 
@@ -108,27 +124,49 @@ function defineParitySuite({ headless }) {
         if (server) {
           await server.close();
         }
-        await Promise.all(
-          userDataDirs.map((directory) =>
-            rm(directory, { recursive: true, force: true, maxRetries: 10 })
-          )
-        );
       });
 
+      // Nothing but the profile, the fixed port, --headless=new when headless
+      // and the about:blank start page, so there is no switch that could show
+      // the unsupported-flag infobar.
+      const assertPersonCommandLine = (args) => {
+        assert.deepEqual(
+          args.map((argument) => argument.split('=')[0]),
+          [
+            '--user-data-dir',
+            '--remote-debugging-port',
+            ...(headless ? ['--headless'] : []),
+            'about:blank',
+          ],
+          args.join(' ')
+        );
+      };
+
       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(', ')}`
+            const { report, launched } = await captureWithLibrary({ engine });
+            assert.equal(launched.launch, 'real');
+            assert.equal(launched.temporaryProfile, true);
+            assertPersonCommandLine(launched.args);
+            assertIndistinguishable(reference, report, `${engine} (${mode})`);
+          }
+        );
+
+        it(
+          `${engine} with launch: 'engine' is indistinguishable from a hand-started Chrome`,
+          { timeout: TEST_TIMEOUT },
+          async () => {
+            const { report } = await captureWithLibrary({
+              engine,
+              launch: 'engine',
+            });
+            assertIndistinguishable(
+              reference,
+              report,
+              `engine-launched ${engine} (${mode})`
             );
           }
         );
@@ -140,8 +178,11 @@ function defineParitySuite({ headless }) {
             // Negative control: without this the parity assertion above could
             // pass for the wrong reason, for example because the probe stopped
             // reporting the field.
+            // An engine launch passes switches that turn AutomationControlled
+            // on; the default real launch has none to undo.
             const { report } = await captureWithLibrary({
               engine,
+              launch: 'engine',
               automationParity: false,
             });
             const paths = diffReports(reference, report).map(
@@ -155,6 +196,23 @@ function defineParitySuite({ headless }) {
           }
         );
 
+        it(
+          `launchRealBrowser with ${engine} is indistinguishable from a hand-started Chrome`,
+          { timeout: TEST_TIMEOUT },
+          async () => {
+            const { report, session } = await captureWithRealBrowser({
+              engine,
+            });
+            assertPersonCommandLine(session.args);
+            assert.equal(report.navigator.webdriver, false);
+            assertIndistinguishable(
+              reference,
+              report,
+              `real ${engine} session (${mode})`
+            );
+          }
+        );
+
         it(
           `${engine} presents the fingerprint profile it was launched with`,
           { timeout: TEST_TIMEOUT },

package/tests/e2e/google-signin-probe.e2e.test.js

@@ -0,0 +1,112 @@
+/**
+ * E2E acceptance probe for issue #102: a clean default real-browser launch must
+ * let a person sign in with a Google account.
+ *
+ * The tell-tale is what Google says after an address is submitted. A browser
+ * Google trusts answers "Couldn't find your Google Account" for an address that
+ * does not exist; a browser it flags as automated answers "This browser or app
+ * may not be secure" and never reaches the account lookup. The default launch
+ * carries no automation switches (issue #101/#103), so `navigator.webdriver` is
+ * false and this probe should see the former, not the latter.
+ *
+ * This talks to the live accounts.google.com, so it is off by default and never
+ * runs in CI. It is headful (Google's checks differ under headless), so on Linux
+ * it needs a display:
+ *
+ *   RUN_GOOGLE_PROBE=true xvfb-run -a --server-args="-screen 0 1920x1080x24" \
+ *     npm run test:e2e:google-probe
+ *
+ * On success it writes docs/screenshots/google-signin-probe.png as evidence.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { existsSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { launchRealBrowser } from '../../src/index.js';
+
+const CHROME = process.env.CHROME_PATH || '/usr/bin/google-chrome';
+const TEST_TIMEOUT = 180000;
+
+const SECURE_WARNING = 'This browser or app may not be secure';
+const ACCOUNT_NOT_FOUND = "Couldn't find your Google Account";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SCREENSHOT = path.resolve(
+  HERE,
+  '../../../docs/screenshots/google-signin-probe.png'
+);
+
+/** Why the probe cannot run here, or `false` when it can. */
+function skipReason() {
+  if (process.env.RUN_GOOGLE_PROBE !== 'true') {
+    return 'set RUN_GOOGLE_PROBE=true to run the live Google sign-in probe';
+  }
+  if (!existsSync(CHROME)) {
+    return `no Chrome binary at ${CHROME}; set CHROME_PATH`;
+  }
+  if (process.platform === 'linux' && !process.env.DISPLAY) {
+    return 'the headful Google probe needs a display; run under xvfb-run';
+  }
+  return false;
+}
+
+describe(
+  'E2E Tests - Google sign-in probe (#102)',
+  { skip: skipReason() },
+  () => {
+    it(
+      'a clean default launch reaches the account lookup, not the "not secure" wall',
+      { timeout: TEST_TIMEOUT },
+      async () => {
+        // A clearly nonexistent address, so a trusted browser lands on
+        // "Couldn't find your Google Account" instead of a password prompt.
+        const address = `bc-parity-probe-${Date.now()}@gmail.com`;
+        const session = await launchRealBrowser({
+          headless: false,
+          executablePath: CHROME,
+          args:
+            process.env.CHROME_NO_SANDBOX === 'true' ? ['--no-sandbox'] : [],
+        });
+        try {
+          const { page } = session;
+          await page.goto('https://accounts.google.com/signin/v2/identifier', {
+            waitUntil: 'load',
+            timeout: 60000,
+          });
+          await page.locator('input[type="email"]').fill(address);
+          await page.keyboard.press('Enter');
+
+          // Wait for either outcome so the assertion is not racing the network.
+          await page
+            .waitForFunction(
+              (needles) =>
+                needles.some((needle) =>
+                  document.body.innerText.includes(needle)
+                ),
+              [ACCOUNT_NOT_FOUND, SECURE_WARNING],
+              { timeout: 60000 }
+            )
+            .catch(() => {});
+
+          await mkdir(path.dirname(SCREENSHOT), { recursive: true });
+          await page.screenshot({ path: SCREENSHOT, fullPage: true });
+
+          const bodyText = await page.evaluate(() => document.body.innerText);
+          assert.ok(
+            !bodyText.includes(SECURE_WARNING),
+            `Google flagged the clean launch as not secure. Screenshot: ${SCREENSHOT}`
+          );
+          assert.ok(
+            bodyText.includes(ACCOUNT_NOT_FOUND),
+            `expected "${ACCOUNT_NOT_FOUND}"; got a different page. Screenshot: ${SCREENSHOT}`
+          );
+        } finally {
+          await session.close();
+        }
+      }
+    );
+  }
+);

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

@@ -0,0 +1,118 @@
+/**
+ * E2E: `measureParity()` against every installed Chrome-family browser.
+ *
+ * The default real launch must be `ok` - no difference from the same binary
+ * started by hand, neither in the command line chrome://version reports nor in
+ * anything the environment probe reads - headful and headless, through either
+ * engine. The engine launch is `ok` only because every one of its extra
+ * switches is tied to the `engine-launch-switches` catalogue entry.
+ *
+ * Google Chrome is required. Chromium, Edge and Brave are measured when they
+ * are installed; a browser that is not installed defines no test rather than
+ * a skipped one, so the parity workflow's "no SKIP" gate still holds.
+ *
+ *     RUN_E2E=true xvfb-run -a --server-args="-screen 0 1920x1080x24" \
+ *       npm run test:e2e:parity
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import { measureParity } from '../../src/browser/parity.js';
+import { resolveSystemBrowserExecutable } from '../../src/browser/system-browser.js';
+import {
+  PARITY_CHROME as CHROME,
+  paritySkipReason,
+} from '../helpers/e2e-browser.js';
+
+const TEST_TIMEOUT = 180000;
+
+async function installedBrowsers() {
+  const browsers = [{ name: 'chrome', executablePath: CHROME }];
+  for (const channel of ['chromium', 'msedge', 'brave']) {
+    const executablePath = await resolveSystemBrowserExecutable({
+      channel,
+    }).catch(() => null);
+    if (executablePath) {
+      browsers.push({ name: channel, executablePath });
+    }
+  }
+  return browsers;
+}
+
+function describeUnlisted(report) {
+  return JSON.stringify(
+    report.unlisted.map(({ path, expected, actual }) => ({
+      path,
+      expected,
+      actual,
+    }))
+  );
+}
+
+// Every browser is measured headful too, so a display is required.
+const skip = paritySkipReason();
+const browsers = skip ? [] : await installedBrowsers();
+
+describe('E2E Tests - measureParity', { skip }, () => {
+  for (const { name, executablePath } of browsers) {
+    for (const headless of [false, true]) {
+      const mode = headless ? 'headless' : 'headful';
+
+      for (const engine of ['playwright', 'puppeteer']) {
+        it(
+          `${name} ${mode}: the real launch through ${engine} matches a hand-started browser`,
+          { timeout: TEST_TIMEOUT },
+          async () => {
+            const report = await measureParity({
+              engine,
+              executablePath,
+              headless,
+            });
+            assert.equal(report.browser.launch, 'real');
+            assert.deepEqual(report.commandLine.extra, []);
+            assert.deepEqual(report.commandLine.missing, []);
+            assert.equal(report.commandLine.attachment.length, 1);
+            assert.equal(report.ok, true, describeUnlisted(report));
+            assert.deepEqual(report.differences, []);
+          }
+        );
+      }
+    }
+
+    it(
+      `${name}: an engine launch is explained by the catalogue`,
+      { timeout: TEST_TIMEOUT },
+      async () => {
+        const report = await measureParity({
+          engine: 'playwright',
+          executablePath,
+          launch: 'engine',
+        });
+        assert.ok(report.commandLine.extra.length > 0);
+        assert.equal(report.ok, true, describeUnlisted(report));
+        assert.ok(
+          report.differences.every(
+            (entry) => entry.limitation === 'engine-launch-switches'
+          )
+        );
+      }
+    );
+  }
+
+  it(
+    'reports an opt-in restriction as requested, not as a leak',
+    { timeout: TEST_TIMEOUT },
+    async () => {
+      const report = await measureParity({
+        executablePath: CHROME,
+        restrictions: ['no-sync'],
+      });
+      assert.deepEqual(report.commandLine.extra, ['--disable-sync']);
+      assert.equal(report.ok, true, describeUnlisted(report));
+      assert.deepEqual(
+        report.differences.map(({ path, requested }) => ({ path, requested })),
+        [{ path: 'commandLine.extra.--disable-sync', requested: true }]
+      );
+    }
+  );
+});

package/tests/e2e/playwright.e2e.test.js

@@ -12,6 +12,7 @@ import assert from 'node:assert';
 // Dynamic import for playwright since it may not be installed
 let playwright;
 let createCommander;
+const TOGGLE_SLIDER = '[data-testid="toggle-switch"] + .toggle-slider';
 
 describe(
   'E2E Tests - Playwright Engine',
@@ -124,12 +125,11 @@ describe(
         }
 
         await commander.click({ selector: '[data-testid="radio-male"]' });
-        const checked = await commander.getAttribute({
-          selector: '[data-testid="radio-male"]',
-          attribute: 'checked',
-        });
-        // Playwright returns empty string for checked attribute when true
-        assert.ok(checked !== null);
+        // React controls the live property without adding a checked attribute.
+        assert.strictEqual(
+          await page.locator('[data-testid="radio-male"]').isChecked(),
+          true
+        );
       });
 
       it('should check checkbox', async () => {
@@ -237,7 +237,7 @@ describe(
         const initialStatus = await commander.textContent({
           selector: '[data-testid="toggle-status"]',
         });
-        await commander.click({ selector: '[data-testid="toggle-switch"]' });
+        await commander.click({ selector: TOGGLE_SLIDER });
         await commander.wait({ ms: 50 });
         const newStatus = await commander.textContent({
           selector: '[data-testid="toggle-status"]',
@@ -337,7 +337,10 @@ describe(
         }
 
         // Scroll to target item (item 15)
-        await commander.scroll({ selector: '[data-testid="scroll-item-15"]' });
+        await commander.scrollIntoView({
+          locatorOrElement: page.locator('[data-testid="scroll-item-15"]'),
+          behavior: 'instant',
+        });
         await commander.wait({ ms: 500 });
 
         // Element should now be visible
@@ -354,17 +357,22 @@ describe(
 
         // Use click which auto-scrolls
         let alertHandled = false;
-        page.on('dialog', async (dialog) => {
+        const onDialog = async (dialog) => {
           alertHandled = true;
           await dialog.accept();
-        });
-
-        await commander.click({
-          selector: '[data-testid="scroll-target-button"]',
-        });
-        await commander.wait({ ms: 100 });
-
-        assert.strictEqual(alertHandled, true);
+        };
+        commander.onDialog(onDialog);
+
+        try {
+          await commander.click({
+            selector: '[data-testid="scroll-target-button"]',
+          });
+          await commander.wait({ ms: 100 });
+
+          assert.strictEqual(alertHandled, true);
+        } finally {
+          commander.offDialog(onDialog);
+        }
       });
     });
 

package/tests/e2e/puppeteer.e2e.test.js

@@ -12,6 +12,7 @@ import assert from 'node:assert';
 // Dynamic import for puppeteer since it may not be installed
 let puppeteer;
 let createCommander;
+const TOGGLE_SLIDER = '[data-testid="toggle-switch"] + .toggle-slider';
 
 describe('E2E Tests - Puppeteer Engine', { skip: !process.env.RUN_E2E }, () => {
   let browser;
@@ -216,30 +217,23 @@ describe('E2E Tests - Puppeteer Engine', { skip: !process.env.RUN_E2E }, () => {
         return;
       }
 
-      // Get initial state
-      const initialStatus = await commander.textContent({
-        selector: '[data-testid="toggle-status"]',
-      });
-
-      // Toggle
-      await commander.click({ selector: '[data-testid="toggle-switch"]' });
-      await commander.wait({ ms: 50 });
-
-      // Verify changed
-      const newStatus = await commander.textContent({
-        selector: '[data-testid="toggle-status"]',
-      });
-      assert.notStrictEqual(initialStatus.trim(), newStatus.trim());
-
-      // Toggle back
-      await commander.click({ selector: '[data-testid="toggle-switch"]' });
-      await commander.wait({ ms: 50 });
+      const initialChecked = await page.$eval(
+        '[data-testid="toggle-switch"]',
+        (input) => input.checked
+      );
+      await commander.click({ selector: TOGGLE_SLIDER });
+      const changedChecked = await page.$eval(
+        '[data-testid="toggle-switch"]',
+        (input) => input.checked
+      );
+      assert.notStrictEqual(changedChecked, initialChecked);
 
-      // Verify back to original
-      const finalStatus = await commander.textContent({
-        selector: '[data-testid="toggle-status"]',
-      });
-      assert.strictEqual(initialStatus.trim(), finalStatus.trim());
+      await commander.click({ selector: TOGGLE_SLIDER });
+      const finalChecked = await page.$eval(
+        '[data-testid="toggle-switch"]',
+        (input) => input.checked
+      );
+      assert.strictEqual(finalChecked, initialChecked);
     });
 
     it('should interact with custom dropdown', async () => {