browser-commander 0.27.0 → 0.28.0

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

@@ -427,6 +427,27 @@ describe('readiness', () => {
       assert.strictEqual(result.ready, false);
     });
 
+    it('should preserve timer expiry while a fractional clock budget remains', async () => {
+      const clock = createFakeClock();
+      const deadline = createDeadline({ timeout: 20, now: clock.now });
+      // The timer and monotonic clock can disagree by a fraction of a
+      // millisecond. Freeze that disagreement to reproduce it every time.
+      clock.advance(19.4);
+      const result = await runReadinessChecks({
+        checks: [
+          { name: 'never', run: () => new Promise(() => {}) },
+          ok('unreached'),
+        ],
+        deadline,
+      });
+
+      assert.strictEqual(deadline.expired(), false);
+      assert.strictEqual(result.status, READINESS_STATUS.TIMED_OUT);
+      assert.strictEqual(result.ready, false);
+      assert.deepStrictEqual(result.checks.pending, ['unreached']);
+      assert.strictEqual(result.evidence[0].detail.reason, 'deadline reached');
+    });
+
     it('should report elapsed and total budget on the result', async () => {
       const clock = createFakeClock();
       const deadline = createDeadline({ timeout: 800, now: clock.now });

package/tests/unit/core/trigger-readiness.test.js

@@ -0,0 +1,39 @@
+import { EventEmitter } from 'node:events';
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createPageTriggerManager } from '../../../src/core/page-trigger-manager.js';
+
+it('DOM-ready triggers start without network idle and skip overlapping runs', async () => {
+  const events = new EventEmitter();
+  let release;
+  let calls = 0;
+  const manager = createPageTriggerManager({
+    navigationManager: events,
+    log: { debug() {} },
+  });
+  manager.pageTrigger({
+    readyOn: 'domcontentloaded',
+    concurrency: 'skip',
+    condition: () => true,
+    action: async () => {
+      calls++;
+      await new Promise((resolve) => {
+        release = resolve;
+      });
+    },
+  });
+  const page = new EventEmitter();
+  page.url = () => 'https://example.com/form';
+  manager.initialize({ page });
+  page.emit('domcontentloaded');
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(calls, 1);
+  page.emit('domcontentloaded');
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(calls, 1);
+  release();
+  await manager.destroy();
+  assert.equal(page.listenerCount('domcontentloaded'), 0);
+  assert.equal(events.listenerCount('onPageReady'), 0);
+});
+import { setImmediate } from 'node:timers';

package/tests/unit/elements/visible-count.test.js

@@ -0,0 +1,24 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { count } from '../../../src/elements/visibility.js';
+
+it('counts only visible matches when requested', async () => {
+  const locator = {
+    count: async () => 3,
+    evaluateAll: async (fn) =>
+      fn([
+        { getClientRects: () => [1], checkVisibility: () => true },
+        { getClientRects: () => [], checkVisibility: () => false },
+        { getClientRects: () => [1], checkVisibility: () => true },
+      ]),
+  };
+  assert.equal(
+    await count({
+      page: { locator: () => locator },
+      engine: 'playwright',
+      selector: 'div',
+      visible: true,
+    }),
+    2
+  );
+});

package/tests/unit/elements/wait-navigation.test.js

@@ -0,0 +1,26 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { waitForLocatorOrElement } from '../../../src/elements/locators.js';
+import { waitForSelector } from '../../../src/elements/selectors.js';
+
+for (const wait of [waitForLocatorOrElement, waitForSelector]) {
+  it(`${wait.name} treats a timeout after navigation as interrupted`, async () => {
+    let url = 'https://example.test/form';
+    const locator = {
+      first() {
+        return this;
+      },
+      async waitFor() {
+        url = 'https://example.test/sent';
+        throw Object.assign(new Error('timeout'), { name: 'TimeoutError' });
+      },
+    };
+    const result = await wait({
+      page: { url: () => url, locator: () => locator },
+      engine: 'playwright',
+      selector: 'button',
+      throwOnNavigation: false,
+    });
+    assert.ok(result === null || result === false);
+  });
+}

package/tests/unit/interactions/navigation-timeout.test.js

@@ -0,0 +1,39 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { clickButton } from '../../../src/interactions/click.js';
+
+for (const change of ['url', 'session', 'none']) {
+  it(`element timeout detects ${change} changes`, async () => {
+    let url = 'https://example.com/form';
+    let session = 1;
+    const error = Object.assign(new Error('waitFor: Timeout 5000ms exceeded'), {
+      name: 'TimeoutError',
+    });
+    const locator = {
+      first: () => locator,
+      waitFor: async () => {
+        if (change === 'url') {
+          url = 'https://example.com/done';
+        }
+        if (change === 'session') {
+          session++;
+        }
+        throw error;
+      },
+    };
+    const operation = clickButton({
+      page: { url: () => url, locator: () => locator },
+      engine: 'playwright',
+      navigationManager: { getSessionId: () => session },
+      selector: '#submit',
+    });
+    if (change === 'none') {
+      await assert.rejects(operation, error);
+    } else {
+      const result = await operation;
+      assert.equal(result.status, 'interrupted');
+      assert.equal(result.navigated, true);
+      assert.equal(result.dispatched, false);
+    }
+  });
+}

package/tests/unit/scripts/ci-timeout-budgets.test.js

@@ -202,6 +202,7 @@ describe('CI execution budgets', () => {
       'parity.yml engine-suites Engine lifecycle suites',
       'parity.yml fixture-suites React fixture suites',
       'parity.yml parity Fingerprint parity suite',
+      'parity.yml parity Stable viewport displayed-pixel regression',
       'parity.yml parity WebDriver suite',
       'parity.yml snapshots Python headful real-browser launches',
       'parity.yml snapshots Python native snapshot launches',

package/tests/unit/traces/bundle.test.js

@@ -232,6 +232,22 @@ describe('trace bundle writer (issue #87)', () => {
     assert.strictEqual(manifest.outcome, TRACE_OUTCOME.COMPLETE);
   });
 
+  it('retains every periodic drain in the same checkpoint interval', async () => {
+    const bundle = await open();
+    await bundle.writeMutations(1, [{ records: ['first'] }]);
+    await bundle.writeMutations(1, [{ records: ['second'] }]);
+    const lines = (
+      await fs.readFile(path.join(bundle.root, 'mutations/0001.ndjson'), 'utf8')
+    )
+      .trim()
+      .split('\n')
+      .map(JSON.parse);
+    assert.deepStrictEqual(lines, [
+      { records: ['first'] },
+      { records: ['second'] },
+    ]);
+  });
+
   it('should record a dropped member even under a tiny resource limit', async () => {
     // The record of a gap must not be the next thing that falls through it.
     const bundle = await open({ limits: { maxResourceBytes: 16 } });

package/tests/unit/traces/network.test.js

@@ -0,0 +1,97 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { startTrace } from '../../../src/traces/recorder.js';
+import { UnsupportedCaptureError } from '../../../src/capture/errors.js';
+import {
+  createFakeCommander,
+  createFakePage,
+} from '../../helpers/trace-fixtures.js';
+
+it('records filtered network metadata and bounded redacted bodies in HAR', async () => {
+  const output = await fs.mkdtemp(path.join(os.tmpdir(), 'commander-network-'));
+  const page = createFakePage();
+  try {
+    const trace = await startTrace({
+      commander: createFakeCommander(page),
+      output,
+      initialCheckpoint: false,
+      network: {
+        resourceTypes: ['fetch'],
+        bodies: true,
+        maxBodyBytes: 4,
+        har: true,
+      },
+    });
+    const request = {
+      url: () => 'https://example.test/api',
+      method: () => 'GET',
+      resourceType: () => 'fetch',
+      headers: () => ({
+        authorization: 'secret',
+        cookie: 'session',
+        accept: 'text/plain',
+      }),
+      timing: () => ({ startTime: Date.now(), responseEnd: 10 }),
+    };
+    page.emit('request', request);
+    page.emit('response', {
+      request: () => request,
+      url: request.url,
+      status: () => 200,
+      headers: () => ({ 'set-cookie': 'secret', 'content-type': 'text/plain' }),
+      body: async () => Buffer.from('abcdef'),
+    });
+    await trace.stop();
+    const events = await fs.readFile(
+      path.join(output, 'events.ndjson'),
+      'utf8'
+    );
+    assert.match(events, /network.response/);
+    assert.doesNotMatch(events, /secret|session/);
+    const har = JSON.parse(
+      await fs.readFile(path.join(output, 'network.har'), 'utf8')
+    );
+    assert.equal(har.log.entries.length, 1);
+    assert.equal(har.log.entries[0].response.content.text, 'YWJjZA==');
+    assert.equal(har.log.entries[0].response.content._truncated, true);
+  } finally {
+    await fs.rm(output, { recursive: true, force: true });
+  }
+});
+
+it('rejected video startup removes every installed observer', async () => {
+  const output = await fs.mkdtemp(path.join(os.tmpdir(), 'commander-start-'));
+  const page = createFakePage();
+  const listeners = new Set();
+  const evaluate = page.evaluate.bind(page);
+  page.evaluate = (fn, argument) =>
+    argument === 'mov' ? Promise.resolve(false) : evaluate(fn, argument);
+  const on = page.on.bind(page);
+  const off = page.off.bind(page);
+  page.on = (event, listener) => {
+    listeners.add(listener);
+    return on(event, listener);
+  };
+  page.off = (event, listener) => {
+    listeners.delete(listener);
+    return off(event, listener);
+  };
+  try {
+    await assert.rejects(
+      startTrace({
+        commander: createFakeCommander(page),
+        output,
+        links: { output: path.join(output, 'trace.lino') },
+        video: { format: 'mov' },
+        network: true,
+      }),
+      UnsupportedCaptureError
+    );
+    assert.equal(listeners.size, 0);
+  } finally {
+    await fs.rm(output, { recursive: true, force: true });
+  }
+});