browser-commander 0.27.0 → 0.29.0

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

@@ -0,0 +1,32 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { isNavigationError } from '../../../src/core/navigation-safety.js';
+import { createManagedNavigator } from '../../../src/core/managed-navigation.js';
+
+it('classifies net::ERR_ABORTED as an interrupted navigation outcome', async () => {
+  const error = new Error(
+    'page.goto: net::ERR_ABORTED at https://example.test/a'
+  );
+  assert.equal(isNavigationError(error), true);
+  const goto = createManagedNavigator({
+    page: {
+      goto: async () => {
+        throw error;
+      },
+    },
+    state: {},
+    config: {},
+    triggerNavigationStart: async () => {},
+    updateCurrentUrl() {},
+    abandonNavigation() {},
+    waitForReady: async () => ({ ready: true }),
+  });
+  assert.equal(
+    (await goto({ url: 'https://example.test/a', returnOutcome: true })).status,
+    'interrupted'
+  );
+  assert.equal(
+    isNavigationError(new Error('net::ERR_NAME_NOT_RESOLVED')),
+    false
+  );
+});

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/core/trigger-stop-race.test.js

@@ -0,0 +1,80 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { createPageTriggerManager } from '../../../src/core/page-trigger-manager.js';
+
+const flush = () => new Promise((resolve) => globalThis.setImmediate(resolve));
+
+for (const concurrency of ['skip', 'queue', 'restart']) {
+  it(`retains DOM-ready work during stop (${concurrency})`, async () => {
+    const navigationManager = new EventEmitter();
+    const page = new EventEmitter();
+    page.url = () => 'https://example.test/new';
+    const manager = createPageTriggerManager({
+      navigationManager,
+      log: { debug() {} },
+      stopGraceMs: 20,
+    });
+    const calls = [];
+    let release;
+    manager.pageTrigger({
+      condition: () => true,
+      readyOn: 'domcontentloaded',
+      concurrency,
+      action: async (ctx) => {
+        calls.push(ctx.url);
+        if (calls.length === 1) {
+          await new Promise((resolve) => {
+            release = resolve;
+          });
+        }
+      },
+    });
+    manager.initialize({ page });
+    page.emit('domcontentloaded');
+    await flush();
+    const stopping = manager.stopCurrentAction();
+    page.emit('domcontentloaded');
+    await stopping;
+    assert.equal(calls.length, 1, 'grace expiry must never overlap actions');
+    release();
+    await flush();
+    await flush();
+    assert.equal(calls.length, 2, 'ready event survives grace expiry');
+    await manager.destroy();
+  });
+}
+
+it('queue coalesces repeated events and unregister cancels pending work', async () => {
+  const nav = new EventEmitter();
+  const page = new EventEmitter();
+  page.url = () => 'https://example.test/';
+  const manager = createPageTriggerManager({
+    navigationManager: nav,
+    log: { debug() {} },
+  });
+  let release;
+  let count = 0;
+  const remove = manager.pageTrigger({
+    condition: () => true,
+    concurrency: 'queue',
+    action: async () => {
+      count++;
+      await new Promise((resolve) => {
+        release = resolve;
+      });
+    },
+  });
+  manager.initialize({ page });
+  nav.emit('onPageReady', { url: page.url() });
+  await flush();
+  for (let i = 0; i < 20; i++) {
+    nav.emit('onPageReady', { url: page.url() });
+  }
+  await flush();
+  remove();
+  release();
+  await flush();
+  assert.equal(count, 1);
+  await manager.destroy();
+});

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

@@ -0,0 +1,58 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { dismissOverlays } from '../../../src/interactions/overlays.js';
+
+it('dismisses the first visible match and reports errors without failing the interaction', async () => {
+  const clicks = [],
+    reports = [];
+  const targets = [
+    { isVisible: async () => false, click: async () => clicks.push('hidden') },
+    {
+      isVisible: async () => true,
+      click: async () => {
+        clicks.push('visible');
+        throw new Error('detached');
+      },
+    },
+  ];
+  const locator = {
+    first: () => targets[0],
+    count: async () => targets.length,
+    nth: (i) => targets[i],
+  };
+  await dismissOverlays({
+    page: { locator: () => locator },
+    engine: 'playwright',
+    overlays: ['.dismiss'],
+    onDismiss: (report) => reports.push(report),
+  });
+  assert.deepEqual(clicks, ['visible']);
+  assert.equal(reports[0].status, 'error');
+  assert.equal(reports[0].error.message, 'detached');
+});
+
+it('reports successful dismissal and isolates reporting callback errors', async () => {
+  let clicked = false;
+  const target = {
+    isVisible: async () => true,
+    click: async () => {
+      clicked = true;
+    },
+  };
+  const reports = [];
+  await dismissOverlays({
+    page: { locator: () => ({ count: async () => 1, nth: () => target }) },
+    engine: 'playwright',
+    overlays: [
+      {
+        selector: '.dismiss',
+        onDismiss: (result) => {
+          reports.push(result);
+          throw new Error('reporting');
+        },
+      },
+    ],
+  });
+  assert.equal(clicked, true);
+  assert.equal(reports[0].status, 'dismissed');
+});

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/issue-160-privacy.test.js

@@ -0,0 +1,110 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { startTrace } from '../../../src/traces/recorder.js';
+import {
+  normalizePrivacyOptions,
+  redactValue,
+  redactHeaders,
+  redactUrl,
+} from '../../../src/traces/redaction.js';
+import {
+  createFakePage,
+  createFakeCommander,
+  makeSnapshot,
+} from '../../helpers/trace-fixtures.js';
+
+it('redacts JSON, form, multipart fields and credential header/query names', () => {
+  const privacy = normalizePrivacyOptions();
+  const cases = [
+    {
+      postData: JSON.stringify({
+        password: 'PRIVATE_A',
+        nested: { _xsrf: 'PRIVATE_B', otp: 123456 },
+        public: 'visible',
+      }),
+    },
+    { postData: 'public=visible&password=PRIVATE_A&_xsrf=PRIVATE_B' },
+    {
+      postData:
+        '--boundary\r\nContent-Disposition: form-data; name="password"\r\n\r\nPRIVATE_A\r\n--boundary--\r\n',
+    },
+    {
+      body: { data: JSON.stringify({ csrf: 'PRIVATE_B', public: 'visible' }) },
+    },
+  ];
+  for (const value of cases) {
+    const result = JSON.stringify(redactValue(value, privacy));
+    assert.doesNotMatch(result, /PRIVATE_[AB]|123456/);
+  }
+  assert.equal(
+    redactHeaders({ 'X-Xsrftoken': 'PRIVATE_A' }, privacy)['X-Xsrftoken'],
+    '[redacted]'
+  );
+  assert.doesNotMatch(
+    redactUrl('https://example.test/?xsrf=PRIVATE_A&csrf=PRIVATE_B', privacy),
+    /PRIVATE/
+  );
+  assert.ok(privacy.redactSelectors.includes('input[type=hidden]'));
+});
+
+it('redacts checkpoint HTML and mutations before bundle and incremental links writes', async () => {
+  const output = await fs.mkdtemp(path.join(os.tmpdir(), 'bc-private-'));
+  const page = createFakePage({
+    snapshot: makeSnapshot({ html: '<div>public PRIVATE_SENTINEL</div>' }),
+  });
+  try {
+    const trace = await startTrace({
+      commander: createFakeCommander(page),
+      output,
+      mode: 'continuous',
+      screenshots: false,
+      links: { output: path.join(output, 'trace.lino'), dom: 'full' },
+      privacy: { redactPatterns: [/PRIVATE_SENTINEL/g] },
+    });
+    page.queueMutations([
+      {
+        records: [
+          {
+            kind: 'attribute',
+            target: { path: '#public' },
+            value: 'public PRIVATE_SENTINEL',
+          },
+        ],
+      },
+    ]);
+    const cp = await trace.checkpoint('public');
+    await trace.stop();
+    assert.doesNotMatch(
+      await fs.readFile(path.join(output, cp.members.html), 'utf8'),
+      /PRIVATE_SENTINEL/
+    );
+    assert.doesNotMatch(
+      await fs.readFile(path.join(output, 'trace.lino'), 'utf8'),
+      /PRIVATE_SENTINEL/
+    );
+    const mutations = await fs.readFile(
+      path.join(output, 'mutations/0001.ndjson'),
+      'utf8'
+    );
+    assert.doesNotMatch(mutations, /PRIVATE_SENTINEL/);
+    assert.match(mutations, /public/);
+  } finally {
+    await fs.rm(output, { recursive: true, force: true });
+  }
+});
+
+it('redacts escaped script values, numeric OTPs and multipart file fields', () => {
+  const privacy = normalizePrivacyOptions();
+  for (const postData of [
+    '<script>const xsrfToken="PRIVATE_A\\"PRIVATE_B"; const otp=123456;</script>',
+    '--b\r\nContent-Disposition: form-data; name="password"; filename="public.txt"\r\n\r\nPRIVATE_A\r\n--b--\r\n',
+  ]) {
+    assert.doesNotMatch(
+      JSON.stringify(redactValue({ postData }, privacy)),
+      /PRIVATE_[AB]|123456/
+    );
+  }
+});