browser-commander 0.19.0 → 0.21.0

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

@@ -1,126 +1,305 @@
-import { describe, it, mock, beforeEach, afterEach } from 'node:test';
+import { describe, it } from 'node:test';
 import assert from 'node:assert';
+import { access } from 'node:fs/promises';
 
-describe('launcher', () => {
-  describe('launchBrowser args option', () => {
-    let originalEnv;
-    let mockChromium;
-    let mockPuppeteer;
-    let launchBrowser;
-    let capturedPlaywrightArgs;
-    let capturedPuppeteerArgs;
-
-    beforeEach(async () => {
-      // Save original environment
-      originalEnv = { ...process.env };
-
-      // Reset captured args
-      capturedPlaywrightArgs = null;
-      capturedPuppeteerArgs = null;
-
-      // Create mock browser context for Playwright
-      const mockBrowserContext = {
-        pages: () => [
-          {
-            bringToFront: async () => {},
-          },
-        ],
-        close: async () => {},
-      };
+import {
+  launchBrowser,
+  launchBrowserWithDependencies,
+  resolveLaunchExecutable,
+} from '../../../src/browser/launcher.js';
+import { TEMPORARY_PROFILE_PREFIX } from '../../../src/browser/profile-directory.js';
+
+const exists = (file) =>
+  access(file).then(
+    () => true,
+    () => false
+  );
+
+function fakePage(calls = []) {
+  return {
+    bringToFront: async () => calls.push(['bringToFront']),
+    emulateMedia: async (options) => calls.push(['emulateMedia', options]),
+    emulateMediaFeatures: async (features) =>
+      calls.push(['emulateMediaFeatures', features]),
+  };
+}
+
+/** A launchRealBrowser stand-in that records what it was asked for. */
+function fakeRealLauncher(calls, { engine = 'playwright' } = {}) {
+  return async (options) => {
+    calls.push(['launchRealBrowser', options]);
+    const page = fakePage(calls);
+    const context = { pages: () => [page], close: async () => {} };
+    const browser =
+      engine === 'playwright'
+        ? { contexts: () => [context], close: async () => {} }
+        : { pages: async () => [page], close: async () => {} };
+    const close = async () => calls.push(['close']);
+    if (engine === 'puppeteer') {
+      browser.close = close;
+    }
+    return {
+      browser,
+      page,
+      downloads: null,
+      close,
+      userDataDir: '/tmp/browser-commander-profile-x',
+      temporaryProfile: true,
+      args: ['--user-data-dir=/tmp/browser-commander-profile-x'],
+    };
+  };
+}
+
+const systemChrome = async () => '/usr/bin/google-chrome';
+
+describe('launchBrowser', () => {
+  it('starts the real browser by default, with nothing added (issue #103)', async () => {
+    const calls = [];
+    const googleBefore = process.env.GOOGLE_API_KEY;
+
+    const result = await launchBrowserWithDependencies(
+      {},
+      {
+        launchRealBrowser: fakeRealLauncher(calls),
+        resolveSystem: systemChrome,
+        settleMs: 0,
+      }
+    );
+
+    const [, options] = calls.find(([name]) => name === 'launchRealBrowser');
+    assert.equal(options.engine, 'playwright');
+    assert.equal(options.executablePath, '/usr/bin/google-chrome');
+    assert.equal('slowMo' in options, false);
+    assert.equal(options.userDataDir, undefined);
+    assert.deepEqual(options.restrictions, []);
+    assert.deepEqual(options.args, []);
+    assert.equal(result.launch, 'real');
+    assert.equal(result.temporaryProfile, true);
+    // The host process environment is never changed.
+    assert.equal(process.env.GOOGLE_API_KEY, googleBefore);
+
+    // Playwright gets the attached default context, like the persistent
+    // context it used to get, and closing it closes the browser.
+    assert.equal(typeof result.browser.pages, 'function');
+    await result.browser.close();
+    assert.deepEqual(calls.at(-1), ['close']);
+  });
 
-      // Create mock browser for Puppeteer
-      const mockBrowser = {
-        pages: async () => [
+  it('returns the connected Puppeteer browser in real mode', async () => {
+    const calls = [];
+    const result = await launchBrowserWithDependencies(
+      { engine: 'puppeteer', restrictions: ['no-sync'], slowMo: 20 },
+      {
+        launchRealBrowser: fakeRealLauncher(calls, { engine: 'puppeteer' }),
+        resolveSystem: systemChrome,
+        settleMs: 0,
+      }
+    );
+
+    const [, options] = calls[0];
+    assert.deepEqual(options.restrictions, ['no-sync']);
+    assert.equal(options.slowMo, 20);
+    await result.close();
+    assert.deepEqual(calls.at(-1), ['close']);
+  });
+
+  it('emulates the colour scheme on the attached page', async () => {
+    const calls = [];
+    await launchBrowserWithDependencies(
+      { colorScheme: 'dark' },
+      {
+        launchRealBrowser: fakeRealLauncher(calls),
+        resolveSystem: systemChrome,
+        settleMs: 0,
+      }
+    );
+
+    assert.deepEqual(
+      calls.find(([name]) => name === 'emulateMedia'),
+      ['emulateMedia', { colorScheme: 'dark' }]
+    );
+  });
+
+  it('closes the browser when post-launch setup fails', async () => {
+    const calls = [];
+    await assert.rejects(
+      () =>
+        launchBrowserWithDependencies(
+          { fingerprint: { timezone: 'Not/AZone' } },
           {
-            bringToFront: async () => {},
-          },
-        ],
-        close: async () => {},
-      };
+            launchRealBrowser: fakeRealLauncher(calls),
+            resolveSystem: systemChrome,
+            settleMs: 0,
+          }
+        ),
+      /timezone|Not\/AZone/i
+    );
+    assert.deepEqual(calls.at(-1), ['close']);
+  });
 
-      // Mock Playwright's chromium
-      mockChromium = {
-        launchPersistentContext: async (userDataDir, options) => {
-          capturedPlaywrightArgs = options.args;
-          return mockBrowserContext;
-        },
-      };
+  it('rejects an invalid engine, launch mode or restriction before launching', async () => {
+    await assert.rejects(
+      () => launchBrowser({ engine: 'invalid-engine' }),
+      /Invalid engine: invalid-engine/
+    );
+    await assert.rejects(
+      () => launchBrowser({ launch: 'attach' }),
+      /Invalid launch mode: attach/
+    );
+    await assert.rejects(
+      () => launchBrowser({ restrictions: ['no-such-restriction'] }),
+      /Unknown launch restriction "no-such-restriction"/
+    );
+  });
 
-      // Mock Puppeteer
-      mockPuppeteer = {
-        default: {
-          launch: async (options) => {
-            capturedPuppeteerArgs = options.args;
-            return mockBrowser;
-          },
+  describe("launch: 'engine'", () => {
+    function fakePlaywright(calls) {
+      const page = fakePage(calls);
+      return {
+        launchPersistentContext: async (userDataDir, options) => {
+          calls.push(['launchPersistentContext', userDataDir, options]);
+          return {
+            pages: () => [page],
+            close: async () => calls.push(['context.close']),
+          };
         },
       };
+    }
 
-      // Use mock.module to mock the dynamic imports
-      // Since we can't easily mock dynamic imports in Node.js test runner,
-      // we'll test the CHROME_ARGS constant usage directly
-    });
-
-    afterEach(() => {
-      // Restore original environment
-      process.env = originalEnv;
-    });
+    it('uses a fresh temporary profile, deleted on close', async () => {
+      const calls = [];
+      const result = await launchBrowserWithDependencies(
+        { launch: 'engine' },
+        { loadEngineModule: async () => fakePlaywright(calls), settleMs: 0 }
+      );
 
-    it('should export CHROME_ARGS constant', async () => {
-      const { CHROME_ARGS } = await import('../../../src/core/constants.js');
-      assert.ok(Array.isArray(CHROME_ARGS));
-      assert.ok(CHROME_ARGS.length > 0);
-    });
+      const [, userDataDir, options] = calls[0];
+      assert.ok(userDataDir.includes(TEMPORARY_PROFILE_PREFIX));
+      assert.equal(await exists(userDataDir), true);
+      assert.equal(options.slowMo, 0);
+      // Only the automation off switch the engine launch needs; none of the
+      // pre-#103 CHROME_ARGS.
+      assert.deepEqual(options.args, [
+        '--disable-blink-features=AutomationControlled',
+      ]);
+      assert.equal('env' in options, false);
+      assert.equal(result.launch, 'engine');
 
-    it('should include expected default Chrome args', async () => {
-      const { CHROME_ARGS } = await import('../../../src/core/constants.js');
-      assert.ok(CHROME_ARGS.includes('--disable-session-crashed-bubble'));
-      assert.ok(CHROME_ARGS.includes('--no-first-run'));
-      assert.ok(CHROME_ARGS.includes('--no-default-browser-check'));
+      await result.browser.close();
+      assert.deepEqual(calls.at(-1), ['context.close']);
+      assert.equal(await exists(userDataDir), false);
     });
 
-    it('launchBrowser function should accept args option', async () => {
-      // We can verify the function signature by checking that it
-      // destructures args from options without throwing
-      const { launchBrowser } =
-        await import('../../../src/browser/launcher.js');
-      assert.ok(typeof launchBrowser === 'function');
+    it('passes restriction environment to the browser process only', async () => {
+      const calls = [];
+      const googleBefore = process.env.GOOGLE_API_KEY;
+      const result = await launchBrowserWithDependencies(
+        { launch: 'engine', restrictions: ['legacy-launch-browser'] },
+        { loadEngineModule: async () => fakePlaywright(calls), settleMs: 0 }
+      );
 
-      // The function should accept options object with args array
-      // We can't fully test the launch without actual browsers,
-      // but we can verify the function exists and is callable
+      const [, , options] = calls[0];
+      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'));
+      await result.close();
     });
 
-    it('launchBrowser should throw for invalid engine', async () => {
-      const { launchBrowser } =
-        await import('../../../src/browser/launcher.js');
-
-      await assert.rejects(
-        () => launchBrowser({ engine: 'invalid-engine' }),
-        (error) => {
-          assert.ok(error.message.includes('Invalid engine'));
-          assert.ok(error.message.includes('invalid-engine'));
-          return true;
-        }
+    it('launches Puppeteer without --start-maximized', async () => {
+      const calls = [];
+      const page = fakePage(calls);
+      const puppeteer = {
+        launch: async (options) => {
+          calls.push(['launch', options]);
+          return {
+            pages: async () => [page],
+            close: async () => calls.push(['browser.close']),
+          };
+        },
+      };
+      const result = await launchBrowserWithDependencies(
+        { engine: 'puppeteer', launch: 'engine' },
+        { loadEngineModule: async () => puppeteer, settleMs: 0 }
       );
+
+      const [, options] = calls[0];
+      assert.equal(options.args.includes('--start-maximized'), false);
+      await result.close();
+      assert.deepEqual(calls.at(-1), ['browser.close']);
     });
+  });
+});
 
-    it('launchBrowser should accept args in options', async () => {
-      const { launchBrowser } =
-        await import('../../../src/browser/launcher.js');
+describe('resolveLaunchExecutable', () => {
+  it('honours an explicit channel or executable path', async () => {
+    const requests = [];
+    const resolveSystem = async (request) => {
+      requests.push(request);
+      return '/resolved';
+    };
+    await resolveLaunchExecutable(
+      { engine: 'playwright', channel: 'msedge' },
+      { resolveSystem }
+    );
+    await resolveLaunchExecutable(
+      { engine: 'playwright', executablePath: '/opt/chrome' },
+      { resolveSystem }
+    );
+    assert.deepEqual(requests, [
+      { channel: 'msedge', executablePath: undefined },
+      { channel: 'chrome', executablePath: '/opt/chrome' },
+    ]);
+  });
 
-      // Verify the function signature accepts args
-      // This test validates that the args parameter is correctly destructured
-      // by attempting to call with an invalid engine (which fails before browser launch)
-      // but proves args is accepted without error during options parsing
-      const customArgs = ['--no-sandbox', '--disable-setuid-sandbox'];
+  it("falls back to the engine's downloaded Chromium without an installed Chrome", async () => {
+    const notInstalled = async () => {
+      throw new Error('Chrome is not installed');
+    };
+    const executable = await resolveLaunchExecutable(
+      { engine: 'playwright' },
+      {
+        resolveSystem: notInstalled,
+        loadEngineModule: async () => ({
+          executablePath: () => process.execPath,
+        }),
+      }
+    );
+    assert.equal(executable, process.execPath);
 
-      await assert.rejects(
-        () => launchBrowser({ engine: 'invalid', args: customArgs }),
-        /Invalid engine/
-      );
+    await assert.rejects(
+      () =>
+        resolveLaunchExecutable(
+          { engine: 'playwright' },
+          {
+            resolveSystem: notInstalled,
+            loadEngineModule: async () => ({
+              executablePath: () => '/nonexistent/chrome',
+            }),
+          }
+        ),
+      /Chrome is not installed/
+    );
+  });
+});
 
-      // If we got here, the args option was accepted without error
-    });
+describe('public launch API', () => {
+  it('exports the launch modes, restrictions and profile helpers', async () => {
+    const api = await import('../../../src/index.js');
+    assert.deepEqual(api.LAUNCH_MODES, ['real', 'engine']);
+    assert.ok(api.LAUNCH_RESTRICTIONS.some(({ id }) => id === 'no-sync'));
+    assert.ok(api.LAUNCH_RESTRICTION_PRESETS['legacy-defaults']);
+    for (const name of [
+      'resolveRestrictions',
+      'mergeFeatureSwitches',
+      'resolveLaunchExecutable',
+      'createTemporaryUserDataDir',
+      'prepareUserDataDir',
+      'removeUserDataDir',
+      'reserveLoopbackPort',
+      'PortRaceError',
+    ]) {
+      assert.equal(typeof api[name], 'function', name);
+    }
   });
 });

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

@@ -38,12 +38,24 @@ describe('emulateMedia', () => {
         () =>
           emulateMedia({
             page: mockPage,
-            engine: 'selenium',
+            engine: 'webkit-classic',
             colorScheme: 'dark',
           }),
         /Unsupported engine/
       );
     });
+
+    it('should explain that the selenium engine has no media emulation', async () => {
+      await assert.rejects(
+        () =>
+          emulateMedia({
+            page: {},
+            engine: 'selenium',
+            colorScheme: 'dark',
+          }),
+        /not available with the selenium engine.*webdriver-no-cdp-emulation/
+      );
+    });
   });
 
   describe('Playwright engine', () => {

package/tests/unit/browser/migration/bookmarks.test.js

@@ -0,0 +1,69 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+
+import {
+  countBookmarks,
+  migrateBookmarks,
+} from '../../../../src/browser/migration/bookmarks.js';
+import {
+  assertNothingMigrated,
+  migrateBetween,
+  readProfileJson,
+  writeProfileJson,
+} from '../../../helpers/migration-fixtures.js';
+import { useTempDirectories } from '../../../helpers/temp-directory.js';
+
+const makeTempDir = useTempDirectories('bc-bookmarks-');
+
+const SAMPLE_BOOKMARKS = {
+  checksum: 'source-checksum',
+  roots: {
+    bookmark_bar: {
+      type: 'folder',
+      children: [
+        { type: 'url', name: 'A', url: 'https://a.example/' },
+        {
+          type: 'folder',
+          children: [{ type: 'url', name: 'B', url: 'https://b.example/' }],
+        },
+      ],
+    },
+    other: { type: 'folder', children: [] },
+  },
+};
+
+describe('countBookmarks', () => {
+  it('counts url nodes recursively across roots', () => {
+    assert.equal(countBookmarks(SAMPLE_BOOKMARKS), 2);
+  });
+
+  it('returns 0 for empty or invalid trees', () => {
+    assert.equal(countBookmarks({}), 0);
+    assert.equal(countBookmarks(null), 0);
+  });
+});
+
+describe('migrateBookmarks', () => {
+  it('copies the Bookmarks JSON verbatim and reports the count', async () => {
+    const source = await makeTempDir();
+    const target = await makeTempDir();
+    await writeProfileJson(source, 'Bookmarks', SAMPLE_BOOKMARKS);
+
+    const report = await migrateBetween(migrateBookmarks, source, target);
+
+    assert.equal(report.migrated, 2);
+    assert.deepEqual(report.skipped, []);
+    const copied = await readProfileJson(target, 'Bookmarks');
+    assert.deepEqual(copied, SAMPLE_BOOKMARKS);
+  });
+
+  it('reports a skip when the source has no bookmarks', async () => {
+    const source = await makeTempDir();
+    const target = await makeTempDir();
+
+    const report = await migrateBetween(migrateBookmarks, source, target);
+
+    assertNothingMigrated(report, 'source-has-no-bookmarks');
+    assert.equal(report.skipped.length, 1);
+  });
+});

package/tests/unit/browser/migration/chromium-crypto.test.js

@@ -0,0 +1,94 @@
+import assert from 'node:assert';
+import { randomBytes } from 'node:crypto';
+import { describe, it } from 'node:test';
+
+import {
+  createWindowsProfileKey,
+  encryptChromiumValue,
+} from '../../../../src/browser/migration/chromium-crypto.js';
+import {
+  decryptChromiumCookie,
+  deriveChromiumCookieKey,
+} from '../../../../src/browser/browser-cookie-crypto.js';
+
+describe('encryptChromiumValue', () => {
+  for (const platform of ['darwin', 'linux']) {
+    it(`round-trips through AES-128-CBC on ${platform}`, () => {
+      const key = deriveChromiumCookieKey('safe-storage-pass', platform);
+      const encrypted = encryptChromiumValue({
+        plaintext: 'hunter2',
+        key,
+        platform,
+        prefix: 'v11',
+      });
+      assert.equal(encrypted.subarray(0, 3).toString('ascii'), 'v11');
+      const decrypted = decryptChromiumCookie({
+        encryptedValue: encrypted,
+        host: 'accounts.example.com',
+        databaseVersion: 0,
+        platform,
+        key,
+      });
+      assert.equal(decrypted, 'hunter2');
+    });
+  }
+
+  it('round-trips through AES-256-GCM on win32', () => {
+    const key = randomBytes(32);
+    const encrypted = encryptChromiumValue({
+      plaintext: 'p@ssw0rd',
+      key,
+      platform: 'win32',
+      prefix: 'v10',
+    });
+    assert.equal(encrypted.subarray(0, 3).toString('ascii'), 'v10');
+    const decrypted = decryptChromiumCookie({
+      encryptedValue: encrypted,
+      host: 'login.example.com',
+      databaseVersion: 0,
+      platform: 'win32',
+      key,
+    });
+    assert.equal(decrypted, 'p@ssw0rd');
+  });
+
+  it('requires a Buffer key and a supported platform', () => {
+    assert.throws(
+      () =>
+        encryptChromiumValue({
+          plaintext: 'x',
+          key: 'nope',
+          platform: 'linux',
+        }),
+      /target encryption key/
+    );
+    assert.throws(
+      () =>
+        encryptChromiumValue({
+          plaintext: 'x',
+          key: randomBytes(16),
+          platform: 'sunos',
+        }),
+      /unsupported/
+    );
+  });
+});
+
+describe('createWindowsProfileKey', () => {
+  it('tags the DPAPI-protected key and base64-encodes it', async () => {
+    const encryptDpapi = (input) => Buffer.concat([Buffer.from('ENC'), input]);
+    const { key, encryptedKeyBase64 } = await createWindowsProfileKey({
+      encryptDpapi,
+      generateKey: () => Buffer.alloc(32, 7),
+    });
+    assert.equal(key.length, 32);
+    const decoded = Buffer.from(encryptedKeyBase64, 'base64');
+    assert.equal(decoded.subarray(0, 5).toString('ascii'), 'DPAPI');
+    assert.equal(decoded.subarray(5, 8).toString('ascii'), 'ENC');
+    assert.deepEqual(decoded.subarray(8), Buffer.alloc(32, 7));
+  });
+
+  it('requires an encryptDpapi function', async () => {
+    await assert.rejects(createWindowsProfileKey({}), /encryptDpapi/);
+  });
+});