browser-commander 0.28.0 → 0.30.0

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/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/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/
+    );
+  }
+});

package/tests/unit/traces/issue-160-rotation.test.js

@@ -0,0 +1,140 @@
+import { it } from 'node:test';
+import { openTraceBundle } from '../../../src/traces/bundle.js';
+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 { readTrace } from '../../../src/traces/reader.js';
+import {
+  createFakePage,
+  createFakeCommander,
+} from '../../helpers/trace-fixtures.js';
+
+function assertUniqueIncreasingSequences(events) {
+  const sequences = events.map((event) => event.sequence);
+  assert.deepEqual(
+    sequences,
+    [...new Set(sequences)].sort((a, b) => a - b)
+  );
+}
+
+it('rotates before oversized checkpoints and retains every segment by default', async () => {
+  const output = await fs.mkdtemp(path.join(os.tmpdir(), 'bc-rotation-'));
+  const page = createFakePage({
+    snapshot: {
+      html: `<div>${'payload'.repeat(1500)}</div>`,
+      state: { url: 'https://example.test' },
+    },
+  });
+  try {
+    const trace = await startTrace({
+      commander: createFakeCommander(page),
+      output,
+      screenshots: false,
+      links: { output: path.join(output, 'trace.lino'), dom: 'full' },
+      limits: { rotate: { maxBytes: 2048 } },
+    });
+    assert.equal(trace.links, path.join(output, 'trace.lino'));
+    for (let i = 0; i < 8; i++) {
+      await trace.checkpoint(`snapshot-${i}`);
+      await trace.event('step', { payload: 'x'.repeat(1500), i });
+    }
+    await trace.stop();
+    assert.equal(trace.stopped, true);
+    const opened = await readTrace(trace.path);
+    assert.equal(opened.events.filter((e) => e.action === 'step').length, 8);
+    assert.equal(opened.events.filter((e) => e.kind === 'dropped').length, 0);
+    assert.ok(opened.checkpoints.length >= 8);
+    assert.match(await opened.html(opened.checkpoints[0].index), /payload/);
+    assert.match(await fs.readFile(trace.links, 'utf8'), /dom-snapshot/);
+    assert.ok(
+      JSON.parse(await fs.readFile(path.join(output, 'segments.json'), 'utf8'))
+        .segments.length > 4
+    );
+  } finally {
+    await fs.rm(output, { recursive: true, force: true });
+  }
+});
+
+it('automatically rotates continuous traces instead of permanently dropping later events', async () => {
+  const output = await fs.mkdtemp(path.join(os.tmpdir(), 'bc-continuous-'));
+  try {
+    const trace = await startTrace({
+      commander: createFakeCommander(createFakePage()),
+      output,
+      mode: 'continuous',
+      screenshots: false,
+      limits: { maxBundleBytes: 2048 },
+    });
+    for (let i = 0; i < 12; i++) {
+      await trace.event('step', { i, payload: 'x'.repeat(1500) });
+    }
+    await trace.stop();
+    const opened = await readTrace(output);
+    assert.equal(opened.events.filter((e) => e.action === 'step').length, 12);
+    assert.equal(opened.events.filter((e) => e.kind === 'dropped').length, 0);
+    assertUniqueIncreasingSequences(opened.events);
+  } finally {
+    await fs.rm(output, { recursive: true, force: true });
+  }
+});
+
+it('caps mutation intervals with a marker and records the next interval', async () => {
+  const output = await fs.mkdtemp(path.join(os.tmpdir(), 'bc-interval-'));
+  const bundle = await openTraceBundle({
+    output,
+    limits: { maxMutationBytes: 512 },
+  });
+  try {
+    await bundle.writeMutations(1, [
+      { records: [{ kind: 'attribute', value: 'a' }] },
+      { records: [{ value: 'x'.repeat(1000) }] },
+    ]);
+    assert.equal(bundle.mutationTruncated, true);
+    assert.equal(await bundle.writeMutations(1, [{ records: [] }]), null);
+    const first = await fs.readFile(
+      path.join(output, 'mutations/0001.ndjson'),
+      'utf8'
+    );
+    assert.ok(Buffer.byteLength(first) <= 512);
+    assert.match(first, /truncated/);
+    await bundle.writeMutations(2, [
+      { records: [{ kind: 'attribute', value: 'next' }] },
+    ]);
+    assert.equal(bundle.mutationTruncated, false);
+    assert.match(
+      await fs.readFile(path.join(output, 'mutations/0002.ndjson'), 'utf8'),
+      /next/
+    );
+  } finally {
+    await bundle.abort();
+    await fs.rm(output, { recursive: true, force: true });
+  }
+});
+
+it('keeps timeline sequences unique across drops and rotation', async () => {
+  const output = await fs.mkdtemp(path.join(os.tmpdir(), 'bc-drop-rotation-'));
+  try {
+    const trace = await startTrace({
+      commander: createFakeCommander(createFakePage()),
+      output,
+      mode: 'continuous',
+      initialCheckpoint: false,
+      screenshots: false,
+      limits: { maxBundleBytes: 4096, maxEventBytes: 1024 },
+    });
+    await trace.event('oversized', { payload: 'x'.repeat(2000) });
+    for (let i = 0; i < 8; i++) {
+      await trace.event('step', { i, payload: 'x'.repeat(300) });
+    }
+    await trace.stop();
+    const opened = await readTrace(output);
+    assert.equal(opened.events.filter((e) => e.kind === 'dropped').length, 1);
+    assert.equal(opened.events.filter((e) => e.action === 'step').length, 8);
+    assert.ok(trace.segments.length > 1);
+    assertUniqueIncreasingSequences(opened.events);
+  } finally {
+    await fs.rm(output, { recursive: true, force: true });
+  }
+});

package/tests/unit/traces/issue-162-defaults.test.js

@@ -0,0 +1,223 @@
+import { describe, 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 { readTrace } from '../../../src/traces/reader.js';
+import { attachCommanderFeatures } from '../../../src/core/commander-features.js';
+import { launchBrowserWithDependencies } from '../../../src/browser/launcher.js';
+import { makeBrowserCommander } from '../../../src/factory.js';
+import { attachLaunchDebug } from '../../../src/traces/debug-session.js';
+import {
+  createFakePage,
+  createFakeCommander,
+} from '../../helpers/trace-fixtures.js';
+
+describe('complete recording defaults (issue #162)', { timeout: 15000 }, () => {
+  async function fixture(run) {
+    const output = await fs.mkdtemp(path.join(os.tmpdir(), 'bc-defaults-'));
+    const page = createFakePage();
+    const commander = createFakeCommander(page, { destroy: async () => {} });
+    const previous = { ...process.env };
+    delete process.env.BROWSER_COMMANDER_DEBUG;
+    delete process.env.BROWSER_COMMANDER_TRACE;
+    try {
+      await run({ output, page, commander });
+    } finally {
+      await commander.destroy();
+      for (const key of [
+        'BROWSER_COMMANDER_DEBUG',
+        'BROWSER_COMMANDER_TRACE',
+      ]) {
+        if (previous[key] === undefined) {
+          delete process.env[key];
+        } else {
+          process.env[key] = previous[key];
+        }
+      }
+      await fs.rm(output, { recursive: true, force: true });
+    }
+  }
+
+  it('captures an initial snapshot, changes, actions and network with a default links file', async () => {
+    await fixture(async ({ output, page, commander }) => {
+      const trace = await startTrace({ commander, output, screenshots: false });
+      try {
+        assert.equal(trace.mode, 'continuous');
+        assert.equal(trace.checkpoints[0].name, 'initial');
+        assert.equal(trace.links, path.join(output, 'trace.lino'));
+        assert.ok(page.listenerCount('request') > 0);
+        assert.ok(
+          page.state.initScripts.some(
+            (call) => call.name === 'installMutationRecorderInPage'
+          )
+        );
+        await commander.click('#delete');
+      } finally {
+        await trace.stop();
+      }
+      const opened = await readTrace(output);
+      assert.equal(
+        opened.events.find((event) => event.kind === 'interaction').source,
+        'commander'
+      );
+      assert.match(
+        await fs.readFile(trace.links, 'utf8'),
+        /initial|dom-snapshot/
+      );
+    });
+  });
+
+  it('preserves explicit checkpoint, network and links opt-outs', async () => {
+    await fixture(async ({ output, page, commander }) => {
+      const trace = await startTrace({
+        commander,
+        output,
+        mode: 'checkpoints',
+        network: false,
+        links: false,
+      });
+      try {
+        assert.equal(trace.mode, 'checkpoints');
+        assert.equal(trace.checkpoints.length, 0);
+        assert.equal(trace.links, null);
+        assert.equal(page.listenerCount('request'), 0);
+      } finally {
+        await trace.stop();
+      }
+    });
+  });
+
+  it('rejects unbounded action queues before opening recording files', async () => {
+    await fixture(async ({ output, page }) => {
+      for (const maxQueuedUserActions of [Infinity, 0, -1, 1.5]) {
+        await assert.rejects(
+          startTrace({ page, output, limits: { maxQueuedUserActions } }),
+          /maxQueuedUserActions/
+        );
+      }
+      assert.deepEqual(await fs.readdir(output), []);
+    });
+  });
+
+  it('starts commander debugging immediately, and finalizes it on destroy', async () => {
+    await fixture(async ({ output, commander }) => {
+      attachCommanderFeatures(commander, { debug: { output } }, () => {});
+      assert.ok(commander.ready instanceof Promise);
+      await commander.ready;
+      assert.equal(commander.tracePath, output);
+      await commander.destroy();
+      assert.equal((await readTrace(output)).manifest.mode, 'continuous');
+    });
+  });
+
+  it('records the very first call with no options and chooses a unique session directory', async () => {
+    await fixture(async ({ output, page }) => {
+      const cwd = process.cwd();
+      process.chdir(output);
+      page.locator = () => ({});
+      page.context = () => ({});
+      page.url = () => 'https://example.com/first';
+      let commander;
+      try {
+        commander = makeBrowserCommander({
+          page,
+          enableNetworkTracking: false,
+          enableNavigationManager: false,
+          enableDialogManager: false,
+        });
+        page.goto = async () => true;
+        await commander.goto({
+          url: 'https://example.com/first',
+          waitAfter: false,
+        });
+        assert.match(
+          commander.tracePath,
+          /browser-commander-traces[/\\].+-\d+-[a-f0-9]{8}$/
+        );
+        await commander.destroy();
+        const trace = await readTrace(commander.tracePath);
+        assert.equal(
+          trace.events.filter((event) => event.source === 'commander').length,
+          1
+        );
+      } finally {
+        await commander?.destroy();
+        process.chdir(cwd);
+      }
+    });
+  });
+
+  for (const disabled of ['option', 'environment']) {
+    it(`respects the ${disabled} opt-out even with BROWSER_COMMANDER_TRACE`, async () => {
+      await fixture(async ({ output, page, commander }) => {
+        process.env.BROWSER_COMMANDER_TRACE = output;
+        if (disabled === 'environment') {
+          process.env.BROWSER_COMMANDER_DEBUG = '0';
+        }
+        attachCommanderFeatures(
+          commander,
+          disabled === 'option' ? { debug: false } : {},
+          () => {}
+        );
+        await commander.ready;
+        assert.equal(page.listenerCount('request'), 0);
+        assert.equal(commander.tracePath, null);
+      });
+    });
+  }
+
+  it('keeps a launch opt-out when a default commander adopts the page', async () => {
+    await fixture(async ({ output, page, commander }) => {
+      const launched = await attachLaunchDebug({ page }, { debug: false });
+      attachCommanderFeatures(commander, { output }, () => {});
+      await commander.ready;
+      assert.equal(launched.tracePath, null);
+      assert.equal(commander.tracePath, null);
+      assert.equal(page.listenerCount('request'), 0);
+    });
+  });
+
+  it('starts a launch recording before returning, reuses it in a commander, and closes it', async () => {
+    await fixture(async ({ output, page, commander }) => {
+      let closed = 0;
+      page.bringToFront = async () => {};
+      const browser = {
+        pages: () => [page],
+        close: async () => {
+          closed += 1;
+        },
+      };
+      const launched = await launchBrowserWithDependencies(
+        { debug: { output } },
+        {
+          resolveSystem: async () => '/usr/bin/google-chrome',
+          settleMs: 0,
+          launchRealBrowser: async () => ({
+            page,
+            browser: { contexts: () => [browser] },
+            close: browser.close,
+          }),
+        }
+      );
+      try {
+        assert.equal(launched.tracePath, output);
+        const requests = page.listenerCount('request');
+        attachCommanderFeatures(commander, {}, () => {});
+        await commander.ready;
+        assert.equal(commander.tracePath, output);
+        assert.equal(page.listenerCount('request'), requests);
+        await commander.click('#delete');
+      } finally {
+        await launched.close();
+      }
+      assert.equal(closed, 1);
+      const opened = await readTrace(output);
+      assert.equal(
+        opened.events.filter((event) => event.kind === 'interaction').length,
+        1
+      );
+    });
+  });
+});