browser-commander 0.19.0 → 0.21.0

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/downloads.e2e.test.js

@@ -17,8 +17,12 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
-import { openBrowserCdpSession } from '../../src/downloads/sources.js';
-import { launchE2EBrowser } from '../helpers/e2e-browser.js';
+import {
+  browserContextIdForPage,
+  openBrowserCdpSession,
+} from '../../src/downloads/sources.js';
+import { makeBrowserCommander } from '../../src/factory.js';
+import { launchE2EBrowser, SANDBOX_ARGS } from '../helpers/e2e-browser.js';
 import {
   BLOB_PDF_BODY,
   PDF_BODY,
@@ -202,9 +206,16 @@ function describeDownloads(engine) {
       // than through the engine's download API. Issue #88 asks for "one
       // lifecycle for automated *and* manual downloads".
       const session = await openBrowserCdpSession({ engine, browser, page });
+      const browserContextId = await browserContextIdForPage({
+        engine,
+        browser,
+        page,
+        browserSession: session,
+      });
       const captured = downloads.capture({ timeout: 20000 });
       await session.send('Target.createTarget', {
         url: `${server.baseUrl}/file/manual.pdf`,
+        ...(browserContextId ? { browserContextId } : {}),
       });
 
       const artifact = await captured;
@@ -231,5 +242,71 @@ describe(
     for (const engine of ENGINES) {
       describeDownloads(engine);
     }
+
+    it('should persist a Blob from browser.newPage() (issue #97)', async () => {
+      const { chromium } = await import('playwright');
+      const directory = await fs.mkdtemp(
+        path.join(os.tmpdir(), 'bc-e2e-context-downloads-')
+      );
+      const browser = await chromium.launch({
+        headless: true,
+        args: SANDBOX_ARGS,
+      });
+      const page = await browser.newPage();
+      const commander = makeBrowserCommander({
+        page,
+        enableNetworkTracking: false,
+        enableNavigationManager: false,
+        enableDialogManager: false,
+      });
+
+      try {
+        const downloads = await commander.configureDownloads({
+          directory,
+          persist: true,
+        });
+        const completed = [];
+        downloads.on('completed', (artifact) => completed.push(artifact));
+        await page.setContent(`
+          <button id="download">Download</button>
+          <script>
+            document.querySelector('#download').addEventListener('click', () => {
+              const blob = new Blob([${JSON.stringify(BLOB_PDF_BODY)}], {
+                type: 'application/pdf',
+              });
+              const anchor = document.createElement('a');
+              anchor.href = URL.createObjectURL(blob);
+              anchor.download = 'declaration.pdf';
+              anchor.click();
+            });
+          </script>
+        `);
+
+        const artifact = await downloads.capture({
+          action: page.click.bind(page, '#download'),
+        });
+
+        assert.strictEqual(artifact.state, 'completed');
+        assert.strictEqual(path.basename(artifact.path), 'declaration.pdf');
+        assert.strictEqual(
+          await fs.readFile(artifact.path, 'utf8'),
+          BLOB_PDF_BODY
+        );
+        assert.strictEqual(completed.length, 1);
+        const staged = await fs.readdir(
+          path.join(directory, '.browser-commander-staging')
+        );
+        assert.deepStrictEqual(staged, []);
+        assert.ok(
+          !(await fs.readdir(directory)).some((entry) =>
+            entry.endsWith('.partial')
+          )
+        );
+      } finally {
+        await commander.destroy();
+        await browser.close();
+        await fs.rm(directory, { recursive: true, force: true });
+      }
+    });
   }
 );

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