browser-commander 0.26.3 → 0.28.0

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 () => {

package/tests/unit/browser/tab-selection.test.js

@@ -0,0 +1,38 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { pickForegroundPage } from '../../../src/browser/connector.js';
+
+it('explicit URL selection wins over emulated visibility', async () => {
+  const pages = ['background', 'automation'].map((name) => ({
+    url: () => `https://example.com/${name}`,
+    evaluate: async () => 'visible',
+  }));
+  assert.equal(
+    await pickForegroundPage(pages, { url: /automation/ }),
+    pages[1]
+  );
+  await assert.rejects(pickForegroundPage(pages, { url: /missing/ }), /No tab/);
+});
+
+it('focus emulation is disabled before reading foreground visibility', async () => {
+  let emulated = true;
+  const session = {
+    send: async (method) => {
+      if (method === 'Emulation.setFocusEmulationEnabled') {
+        emulated = false;
+      }
+      return { targetInfo: { targetId: 'background' } };
+    },
+    detach: async () => {},
+  };
+  const context = { newCDPSession: async () => session };
+  const background = {
+    context: () => context,
+    evaluate: async () => (emulated ? 'visible' : 'hidden'),
+  };
+  const foreground = {
+    context: () => context,
+    evaluate: async () => 'visible',
+  };
+  assert.equal(await pickForegroundPage([background, foreground]), foreground);
+});

package/tests/unit/capture/capture.test.js

@@ -0,0 +1,52 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import UPNG from 'upng-js';
+import {
+  screenshot,
+  encodeAnimation,
+  UnsupportedCaptureError,
+} from '../../../src/capture/index.js';
+
+const png = (color) =>
+  Buffer.from(
+    UPNG.encode([new Uint8Array(color).buffer], 1, 1, 0, undefined, true)
+  );
+it('screenshots honor WebP format without handing unsupported options to the engine', async () => {
+  const page = {
+    screenshot: async (options) => {
+      assert.equal(options.type, 'png');
+      return png([255, 0, 0, 255]);
+    },
+  };
+  const result = await screenshot({
+    page,
+    engine: 'playwright',
+    format: 'webp',
+    quality: 80,
+  });
+  assert.equal(result.subarray(8, 12).toString(), 'WEBP');
+});
+it('animation encoders produce multiple frames with no external binary', async () => {
+  const frames = [png([255, 0, 0, 255]), png([0, 0, 255, 255])];
+  assert.equal(
+    (await encodeAnimation(frames, { format: 'gif', fps: 5 }))
+      .subarray(0, 6)
+      .toString(),
+    'GIF89a'
+  );
+  const apng = await encodeAnimation(frames, { format: 'apng', fps: 5 });
+  assert.equal(
+    UPNG.decode(
+      apng.buffer.slice(apng.byteOffset, apng.byteOffset + apng.length)
+    ).frames.length,
+    2
+  );
+  const webp = await encodeAnimation(frames, { format: 'webp', fps: 5 });
+  assert.equal(webp.toString('latin1').split('ANMF').length - 1, 2);
+});
+it('rejects unsupported options with a typed capability error', async () => {
+  await assert.rejects(
+    screenshot({ page: {}, engine: 'unknown' }),
+    UnsupportedCaptureError
+  );
+});

package/tests/unit/capture/cleanup.test.js

@@ -0,0 +1,24 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createTraceStop } from '../../../src/traces/stop.js';
+
+it('failed video export still releases the trace resources', async () => {
+  const released = [];
+  const stop = createTraceStop({
+    getStopped: () => false,
+    setStopped: () => {},
+    options: {},
+    detachers: [],
+    navigationCapture: async () => {},
+    video: {
+      stop: async () => {
+        throw new Error('encoder failed');
+      },
+    },
+    detachNetwork: async () => released.push('network'),
+    mutations: { stop: async () => released.push('mutations') },
+    bundle: { abort: async () => released.push('bundle') },
+  });
+  await assert.rejects(stop(), /encoder failed/);
+  assert.deepEqual(released, ['network', 'mutations', 'bundle']);
+});

package/tests/unit/capture/viewport.test.js

@@ -0,0 +1,168 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { screenshot } from '../../../src/capture/index.js';
+import { parseCommandLine } from '../../../src/cli/args.js';
+
+function cdpPage(session, capture) {
+  return {
+    context: () => ({ newCDPSession: async () => session }),
+    createCDPSession: async () => session,
+    screenshot: capture,
+  };
+}
+
+for (const engine of ['playwright', 'puppeteer']) {
+  it(`${engine} emulated viewports preserve engine pixel scaling`, async () => {
+    const page = cdpPage(
+      {
+        send: async () => assert.fail('native view ignores emulation'),
+        detach: async () => {},
+      },
+      async (options) => {
+        assert.equal(options.fullPage, false);
+        return Buffer.from('emulated viewport');
+      }
+    );
+    page.viewportSize = () => ({ width: 320, height: 200 });
+    page.viewport = () => ({ width: 320, height: 200, deviceScaleFactor: 2 });
+    assert.equal(
+      (await screenshot({ page, engine, stableViewport: true })).toString(),
+      'emulated viewport'
+    );
+  });
+}
+
+it('Puppeteer BiDi without CDP uses a viewport-only fallback', async () => {
+  const error = Object.assign(new Error(''), { name: 'UnsupportedOperation' });
+  const page = {
+    createCDPSession: async () => {
+      throw error;
+    },
+    screenshot: async (options) => {
+      assert.equal(options.fullPage, false);
+      return Buffer.from('bidi viewport');
+    },
+  };
+  assert.equal(
+    (
+      await screenshot({ page, engine: 'puppeteer', stableViewport: true })
+    ).toString(),
+    'bidi viewport'
+  );
+});
+
+it('the shared CLI parses stable viewport capture', () => {
+  assert.equal(
+    parseCommandLine(['screenshot', 'viewport.png', '--stable-viewport'])
+      .options.stableViewport,
+    true
+  );
+});
+it('Firefox without CDP falls back to its existing viewport', async () => {
+  const page = {
+    context: () => ({
+      newCDPSession: async () => {
+        throw new Error('CDP sessions are only supported by Chromium');
+      },
+    }),
+    screenshot: async (options) => {
+      assert.equal(options.fullPage, false);
+      assert.equal(options.caret, 'initial');
+      return Buffer.from('firefox viewport');
+    },
+  };
+  assert.equal(
+    (await screenshot({ page, stableViewport: true })).toString(),
+    'firefox viewport'
+  );
+});
+
+for (const engine of ['playwright', 'puppeteer']) {
+  it(`${engine} stable viewport captures the view and detaches CDP`, async () => {
+    let detached = false;
+    const session = {
+      send: async (method, options) => {
+        assert.equal(method, 'Page.captureScreenshot');
+        assert.deepEqual(options, {
+          format: 'png',
+          fromSurface: false,
+          captureBeyondViewport: false,
+        });
+        return { data: Buffer.from('viewport').toString('base64') };
+      },
+      detach: async () => {
+        detached = true;
+      },
+    };
+    const page = cdpPage(session, async () =>
+      assert.fail('view capture must bypass engine screenshot')
+    );
+    assert.equal(
+      (await screenshot({ page, engine, stableViewport: true })).toString(),
+      'viewport'
+    );
+    assert.equal(detached, true);
+  });
+  it(`${engine} stable viewport has a viewport-only headless fallback`, async () => {
+    let detached = false;
+    const session = {
+      send: async () => {
+        throw new Error('Unable to capture screenshot');
+      },
+      detach: async () => {
+        detached = true;
+      },
+    };
+    const page = cdpPage(session, async (options) => {
+      assert.equal(options.fullPage, false);
+      return Buffer.from('fallback');
+    });
+    assert.equal(
+      (await screenshot({ page, engine, stableViewport: true })).toString(),
+      'fallback'
+    );
+    assert.equal(detached, true);
+  });
+}
+it('stable viewport rejects regions and visual capture styling', async () => {
+  for (const options of [
+    { fullPage: true },
+    { selector: '#pager' },
+    { clip: { x: 0, y: 0, width: 1, height: 1 } },
+    { hideCaret: true },
+    { animations: 'disabled' },
+    { omitBackground: true },
+  ]) {
+    await assert.rejects(
+      screenshot({
+        page: { screenshot: async () => Buffer.alloc(0) },
+        stableViewport: true,
+        ...options,
+      }),
+      /stableViewport/
+    );
+  }
+});
+it('stable viewport preserves genuine protocol errors and detaches', async () => {
+  const error = new Error('Target closed');
+  let detached = false;
+  const page = {
+    context: () => ({
+      newCDPSession: async () => ({
+        send: async () => {
+          throw error;
+        },
+        detach: async () => {
+          detached = true;
+        },
+      }),
+    }),
+    screenshot: async () =>
+      assert.fail('unrelated errors must not invoke fallback'),
+  };
+  await assert.rejects(
+    screenshot({ page, stableViewport: true }),
+    (actual) => actual === error
+  );
+  assert.equal(detached, true);
+});

package/tests/unit/cli/dispatcher.test.js

@@ -121,6 +121,31 @@ describe('dispatcher: high-level methods', () => {
     assert.deepEqual(pages[0].calls, [['fill', '#q', 'v']]);
   });
 
+  for (const engine of ['playwright', 'puppeteer']) {
+    for (const keepOpen of [false, true]) {
+      it(`closes ${engine} launches with detach support according to keepOpen=${keepOpen}`, async () => {
+        const { dependencies, launches } = createFakeDependencies();
+        const launchBrowser = dependencies.launchBrowser;
+        let detached = false;
+        const dispatcher = createDispatcher({
+          dependencies: {
+            ...dependencies,
+            launchBrowser: async (options) => ({
+              ...(await launchBrowser(options)),
+              detach: async () => {
+                detached = true;
+              },
+            }),
+          },
+        });
+        await dispatcher.dispatch('session.launch', { engine, keepOpen });
+        await dispatcher.close();
+        assert.equal(launches[0].closed, !keepOpen);
+        assert.equal(detached, keepOpen);
+      });
+    }
+  }
+
   it('connects without closing the browser', async () => {
     const { dispatcher, connections } = setup();
 

package/tests/unit/core/navigation-budget.test.js

@@ -0,0 +1,120 @@
+// feature-parity: navigation.budget@native-typed
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createNavigationManager } from '../../../src/core/navigation-manager.js';
+import { goto } from '../../../src/browser/navigation.js';
+import { createNetworkTracker } from '../../../src/core/network-tracker.js';
+import {
+  createMockPlaywrightPage,
+  createMockLogger,
+} from '../../helpers/mocks.js';
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const noWait = {
+  waitForStableUrlBefore: false,
+  waitForStableUrlAfter: false,
+  waitForNetworkIdle: false,
+  verify: false,
+};
+
+it('managed goto honors every no-wait option and keeps tracking', async () => {
+  const page = createMockPlaywrightPage();
+  let idleCalls = 0;
+  const manager = createNavigationManager({
+    page,
+    engine: 'playwright',
+    log: createMockLogger(),
+    networkTracker: {
+      reset() {},
+      waitForNetworkIdle: async () => {
+        idleCalls++;
+        await delay(80);
+        return true;
+      },
+    },
+  });
+  const started = performance.now();
+  const result = await goto({
+    page,
+    navigationManager: manager,
+    url: 'data:text/html,<h1>fixture</h1>',
+    timeout: 50,
+    ...noWait,
+  });
+  assert.equal(result.navigated, true);
+  assert.equal(idleCalls, 0);
+  assert.ok(performance.now() - started < 70);
+  assert.equal(manager.getSessionId(), 1);
+});
+
+it('engine navigation and stalled readiness share a single budget', async () => {
+  const page = createMockPlaywrightPage();
+  page.goto = async () => delay(30);
+  const manager = createNavigationManager({
+    page,
+    engine: 'playwright',
+    log: createMockLogger(),
+  });
+  const started = performance.now();
+  const result = await goto({
+    page,
+    navigationManager: manager,
+    url: 'data:text/html,fixture',
+    timeout: 60,
+    ...noWait,
+    checks: [{ name: 'stall', run: async () => new Promise(() => {}) }],
+  });
+  assert.equal(result.status, 'timed_out');
+  assert.ok(performance.now() - started < 100);
+  assert.equal(manager.isNavigating(), false);
+});
+
+it('caller abort promptly interrupts and unregisters its listener', async () => {
+  const page = createMockPlaywrightPage();
+  page.goto = async () => delay(180);
+  const manager = createNavigationManager({
+    page,
+    engine: 'playwright',
+    log: createMockLogger(),
+  });
+  const controller = new AbortController();
+  let listeners = 0;
+  const add = controller.signal.addEventListener.bind(controller.signal);
+  const remove = controller.signal.removeEventListener.bind(controller.signal);
+  controller.signal.addEventListener = (...args) => {
+    listeners++;
+    return add(...args);
+  };
+  controller.signal.removeEventListener = (...args) => {
+    listeners--;
+    return remove(...args);
+  };
+  const pending = goto({
+    page,
+    navigationManager: manager,
+    url: 'data:text/html,fixture',
+    timeout: 1000,
+    signal: controller.signal,
+    ...noWait,
+  });
+  setTimeout(() => controller.abort(), 20);
+  const result = await pending;
+  assert.equal(result.status, 'interrupted');
+  assert.equal(listeners, 0);
+  assert.equal(manager.isNavigating(), false);
+});
+
+it('an idle network wait respects a shorter timeout than its quiet period', async () => {
+  const page = createMockPlaywrightPage();
+  const tracker = createNetworkTracker({
+    page,
+    engine: 'playwright',
+    log: createMockLogger(),
+  });
+  const started = performance.now();
+  assert.equal(
+    await tracker.waitForNetworkIdle({ timeout: 30, idleTime: 100 }),
+    false
+  );
+  assert.ok(performance.now() - started < 80);
+});