browser-commander 0.26.2 → 0.27.0

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/catalogue-launch.test.js

@@ -6,6 +6,7 @@ import { useTempDirectories } from '../../helpers/temp-directory.js';
 import {
   BROWSER_SOURCES,
   resolveBrowserRoots,
+  resolveBrowserProtectionRoots,
 } from '../../../src/browser/browser-sources.js';
 import {
   assertDedicatedUserDataDir,
@@ -13,8 +14,51 @@ import {
 } from '../../../src/browser/system-browser.js';
 
 const temporary = useTempDirectories('bc-catalogue-protection-');
+const macOSOptions = {
+  platform: 'darwin',
+  homeDir: '/users/test',
+  environment: {},
+};
 
 describe('catalogue launch and protection (#121)', () => {
+  it('accepts dedicated macOS application profiles under Library (#132)', () => {
+    const options = macOSOptions;
+    for (const directory of [
+      'Library/Application Support/package-registry-manager/browser-profile',
+      'Library/Safari-backup/profile',
+      'Library/Cookies-backup/profile',
+      'Library/Containers/com.apple.Safari-helper/profile',
+    ]) {
+      assert.doesNotThrow(() =>
+        assertDedicatedUserDataDir(
+          path.posix.join(options.homeDir, directory),
+          options
+        )
+      );
+    }
+  });
+
+  it('protects Safari stores and Chrome profiles on macOS (#132)', () => {
+    const options = macOSOptions;
+    for (const directory of [
+      'Library/Safari',
+      'Library/Cookies',
+      'Library/Containers/com.apple.Safari',
+      'Library/Safari Technology Preview',
+      'Library/Containers/com.apple.SafariTechnologyPreview',
+      'Library/Application Support/Google/Chrome/Default',
+    ]) {
+      const root = path.posix.join(options.homeDir, directory);
+      for (const requested of [root, path.posix.join(root, 'new-profile')]) {
+        assert.throws(
+          () => assertDedicatedUserDataDir(requested, options),
+          /dedicated.*default profile/,
+          requested
+        );
+      }
+    }
+  });
+
   it('protects a new profile beneath a symlink to a default root', async () => {
     const homeDir = await temporary();
     const options = { homeDir, environment: {} };
@@ -47,7 +91,7 @@ describe('catalogue launch and protection (#121)', () => {
     }
   });
 
-  it('protects every catalogue root and descendant profile on every OS', () => {
+  it('protects every catalogue protection root and descendant profile on every OS', () => {
     for (const platform of ['linux', 'darwin', 'win32']) {
       const options = {
         platform,
@@ -55,7 +99,11 @@ describe('catalogue launch and protection (#121)', () => {
         environment: {},
       };
       for (const browser of BROWSER_SOURCES) {
-        for (const root of resolveBrowserRoots(browser.id, options)) {
+        const roots = resolveBrowserProtectionRoots(browser.id, options);
+        if (!browser.protectionRoots) {
+          assert.deepEqual(roots, resolveBrowserRoots(browser.id, options));
+        }
+        for (const root of roots) {
           assert.throws(
             () => assertDedicatedUserDataDir(root, options),
             /dedicated.*default profile/,

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-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/real-browser.test.js

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

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

@@ -0,0 +1,206 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import {
+  installSessionPersistence,
+  sessionPersistencePath,
+} from '../../../src/browser/session-persistence.js';
+import {
+  findSiteSessions,
+  readBrowserCookieSession,
+} from '../../../src/browser/browser-cookie-session.js';
+
+it('discovery reads Firefox and Safari through their existing cookie readers', async () => {
+  const read = [];
+  const sessions = await findSiteSessions(
+    {
+      domains: ['example.test'],
+      sources: ['firefox', 'safari'].map((browser) => ({
+        browser,
+        path: '/artificial/profile',
+      })),
+    },
+    {
+      readCookies: async (options) => {
+        read.push(options);
+        return [
+          { name: 'session', domain: '.example.test' },
+          { domain: 'notexample.test' },
+        ];
+      },
+    }
+  );
+  assert.equal(read.length, 2);
+  assert.ok(
+    read.every(
+      (options) => options.via === 'database' && options.cache === false
+    )
+  );
+  assert.ok(
+    sessions.every(
+      (session) =>
+        session.cookies.length === 1 &&
+        session.loggedIn === null &&
+        !session.error
+    )
+  );
+});
+
+it('non-Chromium session validation imports cookies into a disposable engine browser', async () => {
+  let seeded;
+  let closed = 0;
+  const sessions = await findSiteSessions(
+    {
+      domains: ['example.test'],
+      sources: [{ browser: 'firefox', path: '/artificial/profile' }],
+      isLoggedIn: async ({ cookies }) => cookies.length === 1,
+    },
+    {
+      readCookies: async () => [
+        {
+          name: 'session',
+          value: 'artificial',
+          domain: '.example.test',
+          path: '/',
+        },
+      ],
+      launch: async (options) => {
+        assert.equal(options.launch, 'engine');
+        assert.equal(options.userDataDir, undefined);
+        return {
+          page: {
+            context: () => ({
+              addCookies: async (cookies) => {
+                seeded = cookies;
+              },
+            }),
+          },
+          close: async () => closed++,
+        };
+      },
+    }
+  );
+  assert.equal(seeded.length, 1);
+  assert.equal(closed, 1);
+  assert.equal(sessions[0].loggedIn, true);
+});
+
+it('browser reads request cookie-only copies, filter domains and always close', async () => {
+  let closed = 0,
+    launched;
+  const result = {
+    page: {
+      context: () => ({
+        storageState: async () => ({
+          cookies: [{ domain: '.example.test' }, { domain: 'notexample.test' }],
+          origins: [],
+        }),
+      }),
+    },
+    close: async () => closed++,
+  };
+  const cookies = await readBrowserCookieSession(
+    {
+      browser: 'chrome',
+      profileDir: '/artificial/Default',
+      domainFilter: 'example.test',
+    },
+    {
+      launch: async (options) => {
+        launched = options;
+        return result;
+      },
+    }
+  );
+  assert.equal(cookies.length, 1);
+  assert.deepEqual(launched.attach.include, ['cookies']);
+  assert.equal(closed, 1);
+});
+it('live validation failure closes the snapshot and records the error', async () => {
+  let closed = 0;
+  const results = await findSiteSessions(
+    {
+      domains: ['example.test'],
+      sources: [{ browser: 'chrome', path: '/artificial/Default' }],
+      isLoggedIn: async () => {
+        throw new Error('artificial validation failure');
+      },
+    },
+    {
+      launch: async () => ({
+        page: {
+          context: () => ({
+            storageState: async () => ({ cookies: [], origins: [] }),
+          }),
+        },
+        close: async () => closed++,
+      }),
+    }
+  );
+  assert.equal(closed, 1);
+  assert.match(results[0].error, /validation failure/);
+});
+it('persistence requires a dedicated profile and writes only session cookies with restricted permissions', async () => {
+  assert.throws(
+    () => sessionPersistencePath({ persistSessionCookies: true }),
+    /dedicated/
+  );
+  const directory = await mkdtemp(path.join(os.tmpdir(), 'bc-session-test-'));
+  try {
+    let closed = 0;
+    const state = {
+      cookies: [
+        { name: 'session', expires: -1 },
+        { name: 'persistent', expires: 9999999999 },
+      ],
+      origins: [],
+    };
+    const page = { context: () => ({ storageState: async () => state }) };
+    const result = await installSessionPersistence(
+      { page, browser: {}, close: async () => closed++ },
+      { userDataDir: directory, persistSessionCookies: true }
+    );
+    await Promise.all([result.close(), result.close()]);
+    const file = path.join(directory, 'browser-commander-session.json');
+    assert.equal(closed, 1);
+    assert.deepEqual(JSON.parse(await readFile(file, 'utf8')).cookies, [
+      state.cookies[0],
+    ]);
+    if (process.platform !== 'win32') {
+      assert.equal((await stat(file)).mode & 0o777, 0o600);
+    }
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+it('session discovery continues after a source close failure', async () => {
+  let closed = 0;
+  const sessions = await findSiteSessions(
+    {
+      domains: ['example.test'],
+      sources: [
+        { browser: 'chrome', path: '/artificial/Default' },
+        { browser: 'chrome', path: '/artificial/Profile 1' },
+      ],
+    },
+    {
+      launch: async () => ({
+        page: {
+          context: () => ({
+            storageState: async () => ({ cookies: [], origins: [] }),
+          }),
+        },
+        close: async () => {
+          closed++;
+          throw new Error('artificial close failure');
+        },
+      }),
+    }
+  );
+  assert.equal(sessions.length, 2);
+  assert.equal(closed, 2);
+  assert.ok(sessions.every((session) => /close failure/.test(session.error)));
+});

package/tests/unit/browser/storage-state.test.js

@@ -106,6 +106,10 @@ describe('browser storage state', () => {
   });
 
   it('delegates Playwright saves to the page context', async () => {
+    temporaryDirectory = await mkdtemp(
+      path.join(os.tmpdir(), 'browser-commander-playwright-state-')
+    );
+    const filePath = path.join(temporaryDirectory, 'state.json');
     const savedState = { cookies: [], origins: [] };
     const calls = [];
     const page = {
@@ -117,8 +121,9 @@ describe('browser storage state', () => {
       }),
     };
 
-    assert.equal(await saveStorageState(page, '/tmp/state.json'), savedState);
-    assert.deepEqual(calls, [{ path: '/tmp/state.json' }]);
+    assert.equal(await saveStorageState(page, filePath), savedState);
+    assert.deepEqual(calls, [undefined]);
+    assert.deepEqual(JSON.parse(await readFile(filePath, 'utf8')), savedState);
   });
 
   it('saves Puppeteer cookies and current-origin localStorage', async () => {