browser-commander 0.20.0 → 0.21.1

package/tests/e2e/cli.e2e.test.js

@@ -0,0 +1,160 @@
+/**
+ * Real-browser tests of the `browser-commander` CLI (issue #104).
+ *
+ * The binary runs as a separate process through command-stream, the way a
+ * shell script, a Rust program or a Python program would use it:
+ *
+ * - `run tests/cli-contract/basic.json` must print, after normalization,
+ *   exactly `tests/cli-contract/basic.expected.json`. The Rust and Python
+ *   CLIs are checked against the same file, so all three agree.
+ * - `launch --keep-open` leaves a browser running that later `goto` and
+ *   `eval` commands reach with `--cdp-endpoint`.
+ *
+ * Run with: npm run test:e2e:cli
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { ProcessRunner } from 'command-stream/process-runner';
+
+import { normalizeRunOutput } from '../../../tests/cli-contract/normalize.mjs';
+import { runCommand } from '../../src/utilities/subprocess.js';
+import { SANDBOX_ARGS } from '../helpers/e2e-browser.js';
+import { repoPath } from '../helpers/repo.js';
+
+const BIN = fileURLToPath(
+  new URL('../../bin/browser-commander.js', import.meta.url)
+);
+const ENGINES = ['playwright', 'puppeteer'];
+const E2E = { skip: !process.env.RUN_E2E, timeout: 180_000 };
+
+/** Options that pick the test browser: CHROME_PATH and sandbox arguments. */
+function browserOptions(engine) {
+  return [
+    '--engine',
+    engine,
+    ...(process.env.CHROME_PATH
+      ? ['--executable-path', process.env.CHROME_PATH]
+      : []),
+    // "--arg=VALUE": a value that starts with "--" cannot follow a space.
+    ...SANDBOX_ARGS.map((arg) => `--arg=${arg}`),
+  ];
+}
+
+/** Run the CLI to completion and parse its one JSON document. */
+async function browserCommander(args) {
+  const { code, stdout, stderr } = await runCommand(
+    process.execPath,
+    [BIN, ...args],
+    { check: false }
+  );
+  let document;
+  try {
+    document = JSON.parse(stdout);
+  } catch {
+    throw new Error(`No JSON from ${args.join(' ')}: ${stdout}\n${stderr}`);
+  }
+  return { code, document };
+}
+
+/**
+ * Start `launch --keep-open` with stdin kept open, and resolve with its
+ * document once it has been printed.
+ */
+function startKeptOpenBrowser(engine) {
+  const runner = new ProcessRunner(
+    {
+      mode: 'exec',
+      file: process.execPath,
+      args: [
+        BIN,
+        'launch',
+        '--keep-open',
+        '--headless',
+        ...browserOptions(engine),
+      ],
+    },
+    { mirror: false, capture: true, stdin: 'pipe' }
+  );
+  let output = '';
+  const printed = new Promise((resolve, reject) => {
+    runner.on('stdout', (chunk) => {
+      output += chunk.toString();
+      if (output.includes('\n')) {
+        resolve(JSON.parse(output.split('\n')[0]));
+      }
+    });
+    Promise.resolve(runner).then(
+      (result) =>
+        reject(new Error(`launch exited early: ${output}${result.stderr}`)),
+      reject
+    );
+  });
+  runner.start();
+  return { runner, printed };
+}
+
+for (const engine of ENGINES) {
+  describe(`E2E - browser-commander CLI with ${engine} (issue #104)`, () => {
+    it(
+      'run basic.json matches the cross-language expected output',
+      E2E,
+      async () => {
+        const { code, document } = await browserCommander([
+          'run',
+          repoPath('tests', 'cli-contract', 'basic.json'),
+          ...browserOptions(engine),
+        ]);
+
+        const expected = JSON.parse(
+          readFileSync(
+            repoPath('tests', 'cli-contract', 'basic.expected.json'),
+            'utf8'
+          )
+        );
+        assert.deepEqual(normalizeRunOutput(document), expected);
+        assert.equal(code, 0);
+      }
+    );
+
+    it(
+      'launch --keep-open serves goto and eval over --cdp-endpoint',
+      E2E,
+      async () => {
+        const { runner, printed } = startKeptOpenBrowser(engine);
+        try {
+          const launched = await printed;
+          assert.match(launched.cdpEndpoint, /^http:\/\/127\.0\.0\.1:\d+$/u);
+          const attach = [
+            '--cdp-endpoint',
+            launched.cdpEndpoint,
+            '--engine',
+            engine,
+          ];
+
+          const url = `data:text/html,${encodeURIComponent(
+            '<title>Kept open</title><p id="x">42</p>'
+          )}`;
+          const goto = await browserCommander(['goto', url, ...attach]);
+          assert.equal(goto.code, 0);
+          assert.deepEqual(goto.document, { url, title: 'Kept open' });
+
+          // The second command attaches again and sees the page the first
+          // one left behind: the browser outlived both commands.
+          const evaluated = await browserCommander([
+            'eval',
+            "document.title + ':' + document.querySelector('#x').textContent",
+            ...attach,
+          ]);
+          assert.equal(evaluated.code, 0);
+          assert.deepEqual(evaluated.document, { value: 'Kept open:42' });
+        } finally {
+          runner.kill('SIGTERM');
+          await Promise.resolve(runner).catch(() => {});
+        }
+      }
+    );
+  });
+}

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

@@ -1,3 +1,4 @@
+// feature-parity: engine.playwright@native-typed
 /**
  * E2E tests for browser-commander using Playwright engine
  *
@@ -12,6 +13,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 +126,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 +238,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 +338,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 +358,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);
+        }
       });
     });