browser-commander 0.26.3 → 0.28.0

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

@@ -15,6 +15,8 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
 import { readFileSync } from 'node:fs';
+import { readFile, rm } from 'node:fs/promises';
+import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { ProcessRunner } from 'command-stream/process-runner';
@@ -23,6 +25,10 @@ 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';
+import {
+  closeRemoteBrowser,
+  SESSION_METADATA,
+} from '../../src/browser/persistent-session.js';
 
 const BIN = fileURLToPath(
   new URL('../../bin/browser-commander.js', import.meta.url)
@@ -124,8 +130,9 @@ for (const engine of ENGINES) {
       E2E,
       async () => {
         const { runner, printed } = startKeptOpenBrowser(engine);
+        let launched;
         try {
-          const launched = await printed;
+          launched = await printed;
           assert.match(launched.cdpEndpoint, /^http:\/\/127\.0\.0\.1:\d+$/u);
           const attach = [
             '--cdp-endpoint',
@@ -153,6 +160,18 @@ for (const engine of ENGINES) {
         } finally {
           runner.kill('SIGTERM');
           await Promise.resolve(runner).catch(() => {});
+          if (launched?.userDataDir) {
+            const file = path.join(launched.userDataDir, SESSION_METADATA);
+            const metadata = JSON.parse(await readFile(file, 'utf8'));
+            await closeRemoteBrowser(metadata.webSocketDebuggerUrl);
+            await assert.rejects(fetch(`${launched.cdpEndpoint}/json/version`));
+            // Chrome finishes flushing its profile after closing CDP.
+            await rm(launched.userDataDir, {
+              recursive: true,
+              force: true,
+              maxRetries: 5,
+            });
+          }
         }
       }
     );

package/tests/e2e/click-readiness.e2e.test.js

@@ -216,7 +216,7 @@ describe(
         });
 
         assert.strictEqual(result.ready, false);
-        assert.strictEqual(result.status, 'timed_out');
+        assert.strictEqual(result.status, 'timed_out', JSON.stringify(result));
         assert.ok(
           elapsed < 6000,
           `the wait took ${elapsed}ms for a 1500ms budget`

package/tests/e2e/navigation-budget.e2e.test.js

@@ -0,0 +1,132 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
+import { createCommander, predicate } from '../../src/index.js';
+import { sendHtml, startFixtureHost } from '../helpers/fixture-server.js';
+
+// Authored local fixtures only. Each deliberately stalled connection is closed
+// by server teardown; browser actions and suites have finite budgets.
+for (const engine of ['playwright', 'puppeteer']) {
+  describe(
+    `navigation budgets: ${engine}`,
+    { skip: !process.env.RUN_E2E, timeout: 60000 },
+    () => {
+      let browser;
+      let page;
+      let commander;
+      let server;
+      before(async () => {
+        server = await startFixtureHost((route, _req, res) => {
+          if (route === '/stall' || route === '/pending') {
+            return;
+          }
+          if (route === '/redirect') {
+            res.writeHead(302, { location: '/ready' });
+            res.end();
+            return;
+          }
+          if (route === '/continuous') {
+            sendHtml(
+              res,
+              '<h1>Continuous requests</h1><script>setInterval(() => fetch("/pending"), 60);</script>'
+            );
+            return;
+          }
+          sendHtml(res, '<h1 id="ready">Ready</h1>');
+        });
+        const { chromium } = await import('playwright');
+        const launchOptions = { headless: true, ...CHROME_LAUNCH_OPTIONS };
+        if (engine === 'playwright') {
+          browser = await chromium.launch(launchOptions);
+          page = await browser.newPage();
+        } else {
+          const { default: puppeteer } = await import('puppeteer');
+          browser = await puppeteer.launch({
+            ...launchOptions,
+            executablePath:
+              CHROME_LAUNCH_OPTIONS.executablePath ?? chromium.executablePath(),
+          });
+          page = await browser.newPage();
+        }
+        commander = createCommander({ page, engine });
+      });
+      after(async () => {
+        await commander?.destroy();
+        await browser?.close();
+        await server?.close();
+      });
+      const navigate = async (url, options = {}) => {
+        const start = performance.now();
+        const result = await commander.goto({
+          url,
+          timeout: 800,
+          verify: false,
+          waitForStableUrlBefore: false,
+          waitForStableUrlAfter: false,
+          waitForNetworkIdle: false,
+          ...options,
+        });
+        assert.ok(
+          performance.now() - start < 1600,
+          'end-to-end budget must bound elapsed time'
+        );
+        return result;
+      };
+      it('loads a data page quickly with tracking enabled', async () => {
+        assert.equal(
+          (await navigate('data:text/html,<h1>Authored fixture</h1>')).status,
+          'ready'
+        );
+        assert.ok(commander.networkTracker);
+        assert.ok(page.listenerCount?.('request') > 0);
+      });
+      it('follows redirects under the same deadline', async () => {
+        const result = await navigate(`${server.baseUrl}/redirect`);
+        assert.equal(result.status, 'ready');
+        assert.equal(page.url(), `${server.baseUrl}/ready`);
+      });
+      it('times out continuous network activity and cleans navigation state', async () => {
+        const result = await navigate(`${server.baseUrl}/continuous`, {
+          waitForNetworkIdle: true,
+        });
+        assert.equal(result.status, 'timed_out');
+        assert.equal(commander.navigationManager.isNavigating(), false);
+      });
+      it('bounds a stalled engine navigation', async () => {
+        assert.equal(
+          (await navigate(`${server.baseUrl}/stall`)).status,
+          'timed_out'
+        );
+      });
+      it('observes a positive selector check', async () => {
+        const ready = predicate({
+          name: 'selector_ready',
+          fn: async () =>
+            page.evaluate(() => Boolean(document.querySelector('#ready'))),
+        });
+        assert.equal(
+          (await navigate(`${server.baseUrl}/ready`, { checks: [ready] }))
+            .status,
+          'ready'
+        );
+      });
+      it('cancels a stalled call and preserves only the session listeners', async () => {
+        const abort = new AbortController();
+        const event =
+          engine === 'playwright' ? 'framenavigated' : 'framenavigated';
+        const count = page.listenerCount?.(event);
+        const timer = setTimeout(() => abort.abort(), 80);
+        try {
+          const result = await navigate(`${server.baseUrl}/stall`, {
+            signal: abort.signal,
+          });
+          assert.equal(result.status, 'interrupted');
+          assert.equal(commander.navigationManager.isNavigating(), false);
+          assert.equal(page.listenerCount?.(event), count);
+        } finally {
+          clearTimeout(timer);
+        }
+      });
+    }
+  );
+}

package/tests/e2e/reusable-session.e2e.test.js

@@ -0,0 +1,231 @@
+// feature-parity: elements.reusable@native-typed sessions.runtime@native-typed sessions.workflow@native-typed
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  createCommander,
+  launchBrowser,
+  saveStorageState,
+} from '../../src/index.js';
+import { mkdtemp, rm } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { sendHtml, startFixtureHost } from '../helpers/fixture-server.js';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
+
+for (const engine of ['playwright', 'puppeteer']) {
+  describe(
+    `reusable helpers and session cookies: ${engine}`,
+    { skip: !process.env.RUN_E2E, timeout: 60000 },
+    () => {
+      let browser, page, commander, server;
+      before(async () => {
+        server = await startFixtureHost((_route, _req, res) =>
+          sendHtml(
+            res,
+            `<p>Hello&nbsp;  world</p>
+        <button class="pick disabled">Disabled</button><button class="pick">Choose me</button>
+        <input type="checkbox" id="checkbox"><input type="radio" id="radio"><div id="hidden" hidden>Hidden</div>`
+          )
+        );
+        const { chromium } = await import('playwright');
+        const options = { headless: true, ...CHROME_LAUNCH_OPTIONS };
+        if (engine === 'playwright') {
+          browser = await chromium.launch(options);
+          page = await browser.newPage();
+        } else {
+          const { default: puppeteer } = await import('puppeteer');
+          browser = await puppeteer.launch({
+            ...options,
+            executablePath:
+              CHROME_LAUNCH_OPTIONS.executablePath ?? chromium.executablePath(),
+          });
+          page = await browser.newPage();
+        }
+        await page.goto(server.baseUrl);
+        commander = createCommander({ page, engine });
+      });
+      after(async () => {
+        await commander?.destroy();
+        await browser?.close();
+        await server?.close();
+      });
+      it('uses ordered selectors and normalizes nonbreaking spaces only when requested', async () => {
+        assert.equal(
+          await commander.findFirst({
+            selectors: ['#absent', '#hidden', '#checkbox'],
+            visible: true,
+          }),
+          '#checkbox'
+        );
+        assert.equal(
+          await commander.hasText({ texts: ['Hello world'] }),
+          false
+        );
+        assert.equal(
+          await commander.hasText({
+            texts: ['missing', 'Hello world'],
+            normalizeWhitespace: true,
+          }),
+          true
+        );
+      });
+      it('selects the requested index for enabled checks, clicks and scrolls', async () => {
+        assert.equal(
+          await commander.isEnabled({ selector: '.pick', index: 0 }),
+          false
+        );
+        assert.equal(
+          await commander.isEnabled({ selector: '.pick', index: 1 }),
+          true
+        );
+        await commander.installClickListener({
+          buttonText: 'Choose me',
+          storageKey: 'picked',
+        });
+        await commander.scrollIntoView({ selector: '.pick', index: 1 });
+        await commander.clickButton({
+          selector: '.pick',
+          index: 1,
+          verify: false,
+          waitAfterClick: 0,
+          waitForNavigation: false,
+        });
+        assert.deepEqual(await commander.readFlag({ storageKey: 'picked' }), {
+          status: 'observed',
+          set: true,
+        });
+        assert.deepEqual(await commander.readFlag({ storageKey: 'picked' }), {
+          status: 'observed',
+          set: true,
+        });
+        assert.equal(
+          await commander.uninstallClickListener({ storageKey: 'picked' }),
+          true
+        );
+        await page.evaluate(() => window.sessionStorage.removeItem('picked'));
+        await commander.clickButton({
+          selector: '.pick',
+          index: 1,
+          verify: false,
+          waitAfterClick: 0,
+          waitForNavigation: false,
+        });
+        assert.deepEqual(await commander.readFlag({ storageKey: 'picked' }), {
+          status: 'observed',
+          set: false,
+        });
+      });
+      it('checks checkboxes and radios idempotently with native input', async () => {
+        assert.equal(
+          await commander.isChecked({ selector: '#checkbox' }),
+          false
+        );
+        assert.deepEqual(await commander.check({ selector: '#checkbox' }), {
+          checked: true,
+          changed: true,
+          verified: true,
+        });
+        assert.deepEqual(await commander.check({ selector: '#checkbox' }), {
+          checked: true,
+          changed: false,
+          verified: true,
+        });
+        assert.equal(
+          (await commander.check({ selector: '#checkbox', checked: false }))
+            .verified,
+          true
+        );
+        assert.equal(
+          (await commander.check({ selector: '#radio' })).checked,
+          true
+        );
+      });
+      it('sets HttpOnly cookies across origins and clears by domain boundary', async () => {
+        await commander.setCookies({
+          cookies: [
+            {
+              name: 'session',
+              value: 'artificial',
+              domain: 'example.test',
+              path: '/',
+              expires: 0,
+              httpOnly: true,
+              sameSite: 'lax',
+            },
+            {
+              name: 'keep',
+              value: 'artificial',
+              domain: 'notexample.test',
+              path: '/',
+              expires: -1,
+            },
+          ],
+        });
+        const state = await saveStorageState(page);
+        const session = state.cookies.find(
+          (cookie) => cookie.name === 'session'
+        );
+        assert.ok(session);
+        assert.equal(session.httpOnly, true);
+        assert.equal(session.expires, -1);
+        assert.equal(session.sameSite, 'Lax');
+        await commander.clearCookies({ domain: 'example.test' });
+        const retained = (await saveStorageState(page)).cookies;
+        assert.equal(
+          retained.some((cookie) => cookie.name === 'session'),
+          false
+        );
+        assert.equal(
+          retained.some((cookie) => cookie.name === 'keep'),
+          true
+        );
+        await commander.clearCookies();
+      });
+      it('restores opted-in session cookies after closing a dedicated profile', async () => {
+        const directory = await mkdtemp(
+          path.join(os.tmpdir(), 'bc-persist-e2e-')
+        );
+        const { chromium } = await import('playwright');
+        const options = {
+          engine,
+          launch: 'engine',
+          headless: true,
+          ...CHROME_LAUNCH_OPTIONS,
+          executablePath:
+            CHROME_LAUNCH_OPTIONS.executablePath ?? chromium.executablePath(),
+          userDataDir: directory,
+          persistSessionCookies: true,
+        };
+        let result;
+        try {
+          result = await launchBrowser(options);
+          const sessionCommander = createCommander({
+            page: result.page,
+            engine,
+          });
+          await sessionCommander.setCookies([
+            {
+              name: 'session',
+              value: 'artificial',
+              domain: 'example.test',
+              path: '/',
+              expires: 0,
+              httpOnly: true,
+            },
+          ]);
+          await sessionCommander.destroy();
+          await result.close();
+          result = await launchBrowser(options);
+          const cookies = (await saveStorageState(result.page)).cookies;
+          assert.equal(
+            cookies.find((cookie) => cookie.name === 'session')?.value,
+            'artificial'
+          );
+        } finally {
+          await result?.close();
+          await rm(directory, { recursive: true, force: true });
+        }
+      });
+    }
+  );
+}

package/tests/unit/browser/attach/snapshot-launch.test.js

@@ -108,8 +108,8 @@ describe('describeAttachDifferences', () => {
 describe('snapshot attach launch option', () => {
   it('maps channels to the browser whose profile is copied', () => {
     assert.equal(snapshotBrowserForChannel('chrome'), 'chrome');
-    assert.equal(snapshotBrowserForChannel('chrome-beta'), 'chrome');
-    assert.equal(snapshotBrowserForChannel('msedge-dev'), 'edge');
+    assert.equal(snapshotBrowserForChannel('chrome-beta'), 'chrome-beta');
+    assert.equal(snapshotBrowserForChannel('msedge-dev'), 'edge-dev');
     assert.equal(snapshotBrowserForChannel('brave'), 'brave');
     assert.equal(snapshotBrowserForChannel('chromium'), 'chromium');
   });

package/tests/unit/browser/attach/snapshot.test.js

@@ -437,3 +437,36 @@ describe('snapshotUserDataDir', () => {
     await assert.rejects(stat(path.join(root, 'copy')), { code: 'ENOENT' });
   });
 });
+
+it('cookie-only snapshots include committed WAL data without history or storage', async () => {
+  const root = await makeTempDir();
+  const target = await makeTempDir();
+  await put(root, 'Local State', '{}');
+  await put(root, 'Default/History', 'private history');
+  await put(root, 'Default/Local Storage/unrelated', 'private storage');
+  await put(root, 'Default/Network/Cookies', '');
+  const writer = new BetterSqlite3(path.join(root, 'Default/Network/Cookies'));
+  writer.pragma('journal_mode=WAL');
+  writer.exec('CREATE TABLE cookies(value); INSERT INTO cookies VALUES (42)');
+  try {
+    await snapshotUserDataDir({
+      browser: 'chrome',
+      userDataDir: root,
+      to: target,
+      include: ['cookies'],
+    });
+    await assert.rejects(stat(path.join(target, 'Default/History')));
+    await assert.rejects(stat(path.join(target, 'Default/Local Storage')));
+    const copy = new BetterSqlite3(
+      path.join(target, 'Default/Network/Cookies'),
+      { readonly: true }
+    );
+    try {
+      assert.equal(copy.prepare('SELECT value FROM cookies').get().value, 42);
+    } finally {
+      copy.close();
+    }
+  } finally {
+    writer.close();
+  }
+});

package/tests/unit/browser/default-browser.test.js

@@ -119,3 +119,21 @@ describe('resolveDefaultBrowser', () => {
     assert.equal(browserForIdentifier('', 'darwin'), null);
   });
 });
+
+it('uses the modern macOS URL handler when LSHandlers is empty', async () => {
+  assert.equal(
+    await resolveDefaultBrowser({
+      platform: 'darwin',
+      runCommand: async (command) =>
+        command === 'osascript' ? 'com.google.chrome\n' : '()',
+    }),
+    'chrome'
+  );
+  assert.equal(
+    await resolveDefaultBrowser({
+      platform: 'darwin',
+      runCommand: async () => '',
+    }),
+    null
+  );
+});

package/tests/unit/browser/launch-building-blocks.test.js

@@ -73,7 +73,11 @@ describe('launch restrictions', () => {
       GOOGLE_DEFAULT_CLIENT_ID: 'no',
       GOOGLE_DEFAULT_CLIENT_SECRET: 'no',
     });
-    assert.ok(resolved.args.includes('--disable-features=Translate'));
+    assert.ok(
+      resolved.args.includes(
+        '--disable-features=SessionRestoreInfobar,Translate'
+      )
+    );
     assert.ok(LAUNCH_RESTRICTION_PRESETS['legacy-launch-browser']);
   });
 

package/tests/unit/browser/launch-diagnostics.test.js

@@ -0,0 +1,52 @@
+// feature-parity: launch.diagnostics@native-typed
+import { it } from 'node:test';
+import { redactLaunchEvidence } from '../../../src/browser/launch-diagnostics.js';
+
+it('diagnostics scrub URL credentials and queries and bound multibyte evidence', () => {
+  const redacted = redactLaunchEvidence(
+    ['https://', 'user:', 'private@example.test/secret?access=private'].join('')
+  );
+  assert.doesNotMatch(redacted, /private|example\.test/);
+  assert.ok(Buffer.byteLength(redactLaunchEvidence('😀'.repeat(4096))) <= 4096);
+});
+import assert from 'node:assert/strict';
+import { launchRealBrowser } from '../../../src/browser/real-browser.js';
+
+it('bad executable preserves bounded, redacted structured early-exit evidence', async () => {
+  await assert.rejects(
+    () =>
+      launchRealBrowser({
+        engine: 'playwright',
+        executablePath: process.execPath,
+        headless: true,
+        startupTimeout: 1000,
+      }),
+    (error) => {
+      assert.equal(error.name, 'BrowserLaunchError');
+      assert.equal(error.phase, 'endpoint');
+      assert.equal(error.engine, 'playwright');
+      assert.equal(error.category, 'early_exit');
+      assert.equal(typeof error.exitCode, 'number');
+      assert.match(error.stderrTail, /bad option/);
+      assert.ok(error.cause);
+      assert.ok(error.stderrTail.length <= 4096);
+      return true;
+    }
+  );
+});
+
+it('missing executable is classified without exposing its path', async () => {
+  await assert.rejects(
+    () =>
+      launchRealBrowser({
+        executablePath: '/private/secret-token/missing-browser',
+      }),
+    (error) => {
+      assert.equal(error.name, 'BrowserLaunchError');
+      assert.equal(error.category, 'missing_executable');
+      assert.ok(!JSON.stringify(error).includes('secret-token'));
+      assert.ok(!error.message.includes('secret-token'));
+      return true;
+    }
+  );
+});

package/tests/unit/browser/launcher.test.js

@@ -202,7 +202,11 @@ describe('launchBrowser', () => {
       assert.equal(options.env.GOOGLE_API_KEY, 'no');
       assert.equal(process.env.GOOGLE_API_KEY, googleBefore);
       assert.ok(options.args.includes('--no-first-run'));
-      assert.ok(options.args.includes('--disable-features=Translate'));
+      assert.ok(
+        options.args.includes(
+          '--disable-features=SessionRestoreInfobar,Translate'
+        )
+      );
       await result.close();
     });
 

package/tests/unit/browser/persistent-session.test.js

@@ -0,0 +1,59 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { closeRemoteBrowser } from '../../../src/browser/persistent-session.js';
+
+function websocket(context) {
+  const sockets = [];
+  class Socket {
+    constructor() {
+      sockets.push(this);
+      globalThis.queueMicrotask(() => this.onopen());
+    }
+    send(message) {
+      this.request = JSON.parse(message);
+    }
+    close() {
+      this.clientClosed = true;
+      this.onclose();
+    }
+    message(value) {
+      this.onmessage({ data: JSON.stringify(value) });
+    }
+  }
+  function createSocket() {
+    return new Socket();
+  }
+  context.mock.method(globalThis, 'WebSocket', createSocket);
+  return sockets;
+}
+
+it('waits for browser shutdown rather than closing on unrelated CDP events', async (context) => {
+  const sockets = websocket(context);
+  const closing = closeRemoteBrowser('ws://127.0.0.1/browser');
+  const socket = sockets[0];
+  await Promise.resolve();
+  socket.message({ method: 'Target.targetCreated', params: {} });
+  const prematurelyClosed = socket.clientClosed;
+  socket.message({ id: socket.request.id, result: {} });
+  socket.onclose();
+  await closing;
+  assert.equal(prematurelyClosed, undefined);
+});
+
+it('reports CDP shutdown errors instead of claiming the browser closed', async (context) => {
+  const sockets = websocket(context);
+  const closing = closeRemoteBrowser('ws://127.0.0.1/browser');
+  await Promise.resolve();
+  sockets[0].message({ id: 1, error: { message: 'shutdown refused' } });
+  await assert.rejects(closing, /shutdown refused/);
+});
+
+it('accepts Chrome disconnecting abruptly after its shutdown acknowledgement', async (context) => {
+  const sockets = websocket(context);
+  const closing = closeRemoteBrowser('ws://127.0.0.1/browser');
+  await Promise.resolve();
+  sockets[0].message({ id: 1, result: {} });
+  sockets[0].onerror();
+  sockets[0].onclose();
+  await closing;
+});

package/tests/unit/browser/quiet-ui.test.js

@@ -0,0 +1,16 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveRestrictions } from '../../../src/browser/restrictions.js';
+
+it('quiet-ui merges caller features and disables Translate in preferences', () => {
+  const result = resolveRestrictions(['quiet-ui'], {
+    disableFeatures: ['CustomFeature', 'Translate'],
+  });
+  const switches = result.args.filter((arg) =>
+    arg.startsWith('--disable-features=')
+  );
+  assert.equal(switches.length, 1);
+  assert.ok(switches[0].includes('SessionRestoreInfobar'));
+  assert.ok(switches[0].includes('CustomFeature'));
+  assert.equal(result.preferences.translate.enabled, false);
+});

package/tests/unit/browser/real-browser.test.js

@@ -405,7 +405,7 @@ describe('launchAndConnectRealBrowser', () => {
             },
           }
         ),
-      PortRaceError
+      (error) => error.category === 'port_race' && error.phase === 'endpoint'
     );
     assert.equal(attempts, 1);
   });