browser-commander 0.19.0 → 0.21.0

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

@@ -0,0 +1,162 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import {
+  createCdpSession,
+  wrapCdpSession,
+} from '../../../src/browser/cdp-session.js';
+import { makeBrowserCommander } from '../../../src/factory.js';
+import * as publicApi from '../../../src/index.js';
+
+function createEngineSession() {
+  const calls = [];
+  const listeners = [];
+  return {
+    calls,
+    listeners,
+    detachCount: 0,
+    send(method, params) {
+      calls.push({ method, params });
+      return Promise.resolve({ echoed: method });
+    },
+    on(event, listener) {
+      listeners.push(['on', event, listener]);
+    },
+    once(event, listener) {
+      listeners.push(['once', event, listener]);
+    },
+    off(event, listener) {
+      listeners.push(['off', event, listener]);
+    },
+    detach() {
+      this.detachCount += 1;
+      return Promise.resolve();
+    },
+  };
+}
+
+function createPlaywrightPage(session) {
+  const context = {
+    targets: [],
+    newCDPSession(target) {
+      context.targets.push(target);
+      return Promise.resolve(session);
+    },
+  };
+  const page = { context: () => context, locator: () => ({}) };
+  return { page, context };
+}
+
+describe('createCdpSession', () => {
+  it('opens a Playwright session through page.context().newCDPSession(page)', async () => {
+    const session = createEngineSession();
+    const { page, context } = createPlaywrightPage(session);
+
+    const cdp = await createCdpSession(page, { engine: 'playwright' });
+
+    assert.equal(cdp.engine, 'playwright');
+    assert.equal(cdp.session, session);
+    assert.deepEqual(context.targets, [page]);
+  });
+
+  it('opens a Puppeteer session through page.createCDPSession()', async () => {
+    const session = createEngineSession();
+    const page = { createCDPSession: () => Promise.resolve(session) };
+
+    const cdp = await createCdpSession(page, { engine: 'puppeteer' });
+
+    assert.equal(cdp.engine, 'puppeteer');
+    assert.equal(cdp.session, session);
+  });
+
+  it('detects the engine from the page when it is not given', async () => {
+    const session = createEngineSession();
+    const { page } = createPlaywrightPage(session);
+
+    assert.equal((await createCdpSession(page)).engine, 'playwright');
+  });
+
+  it('accepts the older {browser, page, engine} form', async () => {
+    const session = createEngineSession();
+    const page = { createCDPSession: () => Promise.resolve(session) };
+
+    const cdp = await createCdpSession({
+      browser: {},
+      page,
+      engine: 'puppeteer',
+    });
+
+    assert.equal(cdp.session, session);
+  });
+
+  it('requires a page', async () => {
+    await assert.rejects(() => createCdpSession(undefined), /requires a page/u);
+  });
+});
+
+describe('the uniform CDP session surface', () => {
+  it('sends commands with empty params by default', async () => {
+    const session = createEngineSession();
+    const cdp = wrapCdpSession(session, 'puppeteer');
+
+    assert.deepEqual(await cdp.send('Browser.getVersion'), {
+      echoed: 'Browser.getVersion',
+    });
+    await cdp.send('Runtime.evaluate', { expression: '1' });
+    assert.deepEqual(session.calls, [
+      { method: 'Browser.getVersion', params: {} },
+      { method: 'Runtime.evaluate', params: { expression: '1' } },
+    ]);
+  });
+
+  it('forwards listeners and chains', () => {
+    const session = createEngineSession();
+    const cdp = wrapCdpSession(session, 'playwright');
+    const listener = () => {};
+
+    assert.equal(cdp.on('Network.requestWillBeSent', listener), cdp);
+    assert.equal(cdp.once('Page.loadEventFired', listener), cdp);
+    assert.equal(cdp.off('Network.requestWillBeSent', listener), cdp);
+    assert.deepEqual(
+      session.listeners.map(([kind, event]) => `${kind}:${event}`),
+      [
+        'on:Network.requestWillBeSent',
+        'once:Page.loadEventFired',
+        'off:Network.requestWillBeSent',
+      ]
+    );
+  });
+
+  it('detaches once', async () => {
+    const session = createEngineSession();
+    const cdp = wrapCdpSession(session, 'playwright');
+
+    await cdp.detach();
+    await cdp.detach();
+
+    assert.equal(session.detachCount, 1);
+  });
+});
+
+describe('public cdpSession entry points', () => {
+  it('exports createCdpSession and wrapCdpSession', () => {
+    assert.equal(publicApi.createCdpSession, createCdpSession);
+    assert.equal(publicApi.wrapCdpSession, wrapCdpSession);
+  });
+
+  it('opens a session from a commander', async () => {
+    const session = createEngineSession();
+    const { page } = createPlaywrightPage(session);
+    const commander = makeBrowserCommander({
+      page,
+      enableNetworkTracking: false,
+      enableNavigationManager: false,
+      enableDialogManager: false,
+    });
+
+    const cdp = await commander.createCdpSession();
+
+    assert.equal(cdp.engine, 'playwright');
+    assert.equal(cdp.session, session);
+  });
+});

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

@@ -3,6 +3,7 @@ import { describe, it } from 'node:test';
 
 import {
   connectBrowser,
+  pickForegroundPage,
   connectBrowserWithDependencies,
 } from '../../../src/browser/connector.js';
 import { connectBrowser as publicConnectBrowser } from '../../../src/index.js';
@@ -127,3 +128,25 @@ describe('connectBrowser', () => {
     );
   });
 });
+
+describe('pickForegroundPage', () => {
+  const page = (id, state) => ({ id, evaluate: async () => state });
+
+  it('prefers the visible tab over the first one', async () => {
+    const picked = await pickForegroundPage([
+      page('ntp', 'hidden'),
+      page('whats-new', 'visible'),
+    ]);
+    assert.equal(picked.id, 'whats-new');
+  });
+
+  it('falls back to the first tab when none reports visible', async () => {
+    const failing = {
+      id: 'crashed',
+      evaluate: async () => Promise.reject(new Error('gone')),
+    };
+    const picked = await pickForegroundPage([failing, page('b', 'hidden')]);
+    assert.equal(picked.id, 'crashed');
+    assert.equal(await pickForegroundPage([]), undefined);
+  });
+});

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

@@ -0,0 +1,238 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { PassThrough } from 'node:stream';
+import {
+  access,
+  mkdtemp,
+  readFile,
+  rm,
+  stat,
+  writeFile,
+} from 'node:fs/promises';
+import {
+  LAUNCH_RESTRICTIONS,
+  LAUNCH_RESTRICTION_PRESETS,
+  mergeFeatureSwitches,
+  resolveRestrictions,
+} from '../../../src/browser/restrictions.js';
+import {
+  FIRST_RUN_SENTINEL,
+  INITIAL_LOCAL_STATE,
+  LOCAL_STATE_FILE,
+  TEMPORARY_PROFILE_PREFIX,
+  createTemporaryUserDataDir,
+  prepareUserDataDir,
+  removeUserDataDir,
+} from '../../../src/browser/profile-directory.js';
+import {
+  PortRaceError,
+  assertFixedDebuggingPort,
+  classifyDevToolsOwnership,
+  parseDevToolsOutput,
+  reserveLoopbackPort,
+  watchDevToolsOutput,
+} from '../../../src/browser/debugging-port.js';
+import { CHROME_ARGS } from '../../../src/core/constants.js';
+import { detectAutomationControlledTriggers } from '../../../src/fingerprint/automation-parity.js';
+
+describe('launch restrictions', () => {
+  it('has unique ids and a description for each entry', () => {
+    const ids = LAUNCH_RESTRICTIONS.map((entry) => entry.id);
+    assert.equal(new Set(ids).size, ids.length);
+    for (const entry of LAUNCH_RESTRICTIONS) {
+      assert.ok(entry.description.length > 10, entry.id);
+      assert.ok(entry.args || entry.disableFeatures || entry.env, entry.id);
+    }
+  });
+
+  it('never offers a switch that turns AutomationControlled on', () => {
+    for (const entry of LAUNCH_RESTRICTIONS) {
+      assert.deepEqual(
+        detectAutomationControlledTriggers(entry.args ?? []),
+        [],
+        entry.id
+      );
+    }
+  });
+
+  it('keeps the pre-#103 defaults available as a preset', () => {
+    const { args } = resolveRestrictions(['legacy-defaults']);
+    assert.deepEqual([...args].sort(), [...CHROME_ARGS].sort());
+  });
+
+  it('adds the Google key override only to the browser environment', () => {
+    const resolved = resolveRestrictions(['legacy-launch-browser']);
+    assert.deepEqual(resolved.env, {
+      GOOGLE_API_KEY: 'no',
+      GOOGLE_DEFAULT_CLIENT_ID: 'no',
+      GOOGLE_DEFAULT_CLIENT_SECRET: 'no',
+    });
+    assert.ok(resolved.args.includes('--disable-features=Translate'));
+    assert.ok(LAUNCH_RESTRICTION_PRESETS['legacy-launch-browser']);
+  });
+
+  it('deduplicates ids and joins feature lists into one switch', () => {
+    const resolved = resolveRestrictions([
+      'no-translate',
+      'no-lens',
+      'no-translate',
+    ]);
+    assert.deepEqual(resolved.ids, ['no-translate', 'no-lens']);
+    assert.deepEqual(resolved.args, [
+      '--disable-features=Translate,LensOverlay',
+    ]);
+  });
+
+  it('rejects unknown names and non-arrays', () => {
+    assert.throws(() => resolveRestrictions(['nope']), RangeError);
+    assert.throws(() => resolveRestrictions('no-sync'), TypeError);
+  });
+
+  it('merges repeated feature switches into the first position', () => {
+    assert.deepEqual(
+      mergeFeatureSwitches([
+        '--a',
+        '--disable-features=A,B',
+        '--enable-features=X',
+        '--disable-features=B,C',
+        '--b',
+      ]),
+      ['--a', '--disable-features=A,B,C', '--enable-features=X', '--b']
+    );
+  });
+});
+
+describe('profile directory', () => {
+  it('creates a fresh profile with the First Run sentinel', async () => {
+    const dir = await createTemporaryUserDataDir();
+    try {
+      assert.ok(path.basename(dir).startsWith(TEMPORARY_PROFILE_PREFIX));
+      await access(path.join(dir, FIRST_RUN_SENTINEL));
+      assert.deepEqual(
+        JSON.parse(await readFile(path.join(dir, LOCAL_STATE_FILE), 'utf8')),
+        INITIAL_LOCAL_STATE
+      );
+    } finally {
+      await removeUserDataDir(dir);
+    }
+    await assert.rejects(() => access(dir), /ENOENT/);
+  });
+
+  it('never overwrites Local State that Chrome already wrote', async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), 'bc-profile-test-'));
+    try {
+      const localState = path.join(dir, LOCAL_STATE_FILE);
+      await writeFile(
+        localState,
+        '{"browser":{"enabled_labs_experiments":[]}}'
+      );
+      await prepareUserDataDir(dir);
+      assert.equal(
+        await readFile(localState, 'utf8'),
+        '{"browser":{"enabled_labs_experiments":[]}}'
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('keeps an existing sentinel untouched', async () => {
+    const parent = await mkdtemp(path.join(os.tmpdir(), 'bc-profile-test-'));
+    try {
+      const dir = path.join(parent, 'nested', 'profile');
+      await prepareUserDataDir(dir);
+      const sentinel = path.join(dir, FIRST_RUN_SENTINEL);
+      const before = await stat(sentinel);
+      await prepareUserDataDir(dir);
+      assert.equal((await stat(sentinel)).mtimeMs, before.mtimeMs);
+      assert.equal(await readFile(sentinel, 'utf8'), '');
+    } finally {
+      await rm(parent, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('debugging port', () => {
+  it('reserves a loopback port that can be bound again', async () => {
+    const port = await reserveLoopbackPort();
+    assert.ok(port > 0 && port < 65_536);
+    await new Promise((resolve, reject) => {
+      const server = net.createServer();
+      server.once('error', reject);
+      server.listen({ port, host: '127.0.0.1' }, () => server.close(resolve));
+    });
+  });
+
+  it('refuses port 0 and out-of-range ports', () => {
+    assert.throws(() => assertFixedDebuggingPort(0), /AutomationControlled/);
+    assert.throws(() => assertFixedDebuggingPort(70_000), RangeError);
+    assert.throws(() => assertFixedDebuggingPort('9222'), RangeError);
+    assert.equal(assertFixedDebuggingPort(9222), 9222);
+  });
+
+  it('parses the DevTools listening line', () => {
+    assert.deepEqual(
+      parseDevToolsOutput(
+        '\nDevTools listening on ws://127.0.0.1:9222/devtools/browser/1-2\n'
+      ),
+      {
+        listening: {
+          url: 'ws://127.0.0.1:9222/devtools/browser/1-2',
+          host: '127.0.0.1',
+          port: 9222,
+        },
+        bindFailed: false,
+      }
+    );
+    assert.equal(
+      parseDevToolsOutput(
+        'DevTools listening on ws://[::1]:9222/devtools/browser/x'
+      ).listening.host,
+      '::1'
+    );
+  });
+
+  it('classifies ownership, fallback and give-up output', () => {
+    const owned = parseDevToolsOutput(
+      'DevTools listening on ws://127.0.0.1:9222/devtools/browser/x'
+    );
+    assert.equal(classifyDevToolsOwnership(owned, 9222), 'owned');
+    assert.equal(classifyDevToolsOwnership(owned, 9223), 'race');
+    const fallback = parseDevToolsOutput(
+      'bind() failed\nDevTools listening on ws://[::1]:9222/devtools/browser/x'
+    );
+    assert.equal(classifyDevToolsOwnership(fallback, 9222), 'race');
+    assert.equal(
+      classifyDevToolsOwnership(
+        parseDevToolsOutput('Cannot start http server for devtools.'),
+        9222
+      ),
+      'race'
+    );
+    // Unrelated bind failures (mDNS, media router) are not conclusive.
+    assert.equal(
+      classifyDevToolsOwnership(parseDevToolsOutput('bind() failed'), 9222),
+      'pending'
+    );
+  });
+
+  it('watches a stream across chunk boundaries', () => {
+    const stream = new PassThrough();
+    const watcher = watchDevToolsOutput(stream);
+    assert.equal(watcher.available, true);
+    stream.emit('data', 'DevTools listening on ws://127.0.0.1:92');
+    assert.equal(watcher.state().listening, null);
+    stream.emit('data', '22/devtools/browser/abc\n');
+    assert.equal(watcher.state().listening.port, 9222);
+    assert.equal(watchDevToolsOutput(undefined).available, false);
+  });
+
+  it('names the port in race errors', () => {
+    const error = new PortRaceError(9222, 'bind failed');
+    assert.equal(error.port, 9222);
+    assert.match(error.message, /9222.*bind failed/);
+  });
+});

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

@@ -6,45 +6,64 @@ import {
   buildPuppeteerLaunchOptions,
   resolveChromeArgs,
 } from '../../../src/browser/launch-options.js';
+import { CHROME_ARGS } from '../../../src/core/constants.js';
 
 describe('browser launch options', () => {
-  it('applies safe defaults, appends extra arguments, and supports per-flag opt-out', () => {
-    const options = resolveChromeArgs({
-      args: ['--legacy-arg'],
-      extraArgs: ['--lang=en-US'],
-      ignoreDefaultArgs: ['--no-default-browser-check'],
-    });
+  it('adds no switches of its own by default (issue #103)', () => {
+    const options = resolveChromeArgs();
 
-    assert.ok(options.args.includes('--password-store=basic'));
-    assert.ok(options.args.includes('--no-first-run'));
-    assert.equal(options.args.includes('--no-default-browser-check'), false);
-    assert.deepEqual(options.args.slice(-2), ['--legacy-arg', '--lang=en-US']);
-    assert.deepEqual(options.ignoreDefaultArgs, ['--no-default-browser-check']);
+    assert.deepEqual(options.args, []);
+    assert.deepEqual(options.ignoreDefaultArgs, []);
   });
 
-  it('can ignore every Browser Commander default', () => {
+  it('appends custom args after opt-in restrictions', () => {
     const options = resolveChromeArgs({
+      restrictions: ['no-sync', 'no-translate'],
+      args: ['--legacy-arg', '--disable-features=Foo'],
       extraArgs: ['--lang=en-US'],
-      ignoreDefaultArgs: true,
     });
 
-    assert.deepEqual(options.args, ['--lang=en-US']);
-    assert.equal(options.ignoreDefaultArgs, true);
+    assert.deepEqual(options.args, [
+      '--disable-sync',
+      // Chrome keeps only the last --disable-features, so they are merged.
+      '--disable-features=Translate,Foo',
+      '--legacy-arg',
+      '--lang=en-US',
+    ]);
   });
 
-  it('can opt out of the password-store default specifically', () => {
-    const options = resolveChromeArgs({
-      ignoreDefaultArgs: ['--password-store=basic'],
+  it('restores the pre-#103 switches through the legacy-defaults preset', () => {
+    const options = resolveChromeArgs({ restrictions: ['legacy-defaults'] });
+
+    assert.deepEqual([...options.args].sort(), [...CHROME_ARGS].sort());
+  });
+
+  it('rejects malformed arguments and unknown restrictions', () => {
+    assert.throws(() => resolveChromeArgs({ args: '--x' }), TypeError);
+    assert.throws(
+      () => resolveChromeArgs({ ignoreDefaultArgs: 'yes' }),
+      TypeError
+    );
+    assert.throws(
+      () => resolveChromeArgs({ restrictions: ['no-such-thing'] }),
+      RangeError
+    );
+  });
+
+  it('never adds --start-maximized to Puppeteer', () => {
+    const options = buildPuppeteerLaunchOptions({
+      headless: false,
+      chromeArgs: [],
+      userDataDir: '/tmp/browser-commander-test',
     });
 
-    assert.equal(options.args.includes('--password-store=basic'), false);
-    assert.ok(options.args.includes('--no-first-run'));
+    assert.equal(options.args.includes('--start-maximized'), false);
   });
 
   it('forwards ignored defaults to both browser engines', () => {
     const playwright = buildPlaywrightLaunchOptions({
       headless: false,
-      slowMo: 150,
+      slowMo: 0,
       chromeArgs: [],
       ignoreDefaultArgs: ['--no-first-run'],
     });
@@ -99,7 +118,7 @@ describe('browser launch options', () => {
   it('omits browser selection options by default', () => {
     const playwright = buildPlaywrightLaunchOptions({
       headless: false,
-      slowMo: 150,
+      slowMo: 0,
       chromeArgs: [],
     });
     const puppeteer = buildPuppeteerLaunchOptions({