browser-commander 0.17.1 → 0.18.0

package/tests/helpers/trace-fixtures.js

@@ -0,0 +1,198 @@
+/**
+ * Fixtures for the trace tests (issue #87).
+ *
+ * The fake page answers the few calls the recorder makes — evaluate a capture
+ * function, take a screenshot, emit an engine event — so the recorder's own
+ * behaviour is tested without a browser. The functions that run *inside* a
+ * page are proven against real engines in `tests/e2e/traces.e2e.test.js`.
+ */
+
+import { EventEmitter } from 'node:events';
+import { useTempDirectory } from './temp-directory.js';
+
+/**
+ * Give a suite its own directory for trace bundles.
+ *
+ * @returns {{path: string}} Holder whose `path` is the current directory
+ */
+export function useTempTraceDirectory() {
+  return useTempDirectory('bc-traces-');
+}
+
+/**
+ * A snapshot shaped like the one the in-page capture returns.
+ *
+ * @param {Object} [overrides] - Fields to replace
+ * @returns {Object} `{html, state, truncated}`
+ */
+export function makeSnapshot(overrides = {}) {
+  const { state: stateOverrides, ...rest } = overrides;
+  return {
+    html: '<!DOCTYPE html>\n<html><body><p>captured</p></body></html>',
+    truncated: false,
+    ...rest,
+    state: {
+      url: 'https://example.com/report',
+      title: 'Report',
+      readyState: 'complete',
+      scroll: { x: 0, y: 0 },
+      viewport: { width: 1280, height: 720 },
+      activeElement: null,
+      controls: [
+        { path: 'form > input', tag: 'input', type: 'text', value: 'alice' },
+      ],
+      frames: [],
+      ...stateOverrides,
+    },
+  };
+}
+
+/**
+ * Create a fake page the recorder can drive.
+ *
+ * @param {Object} [options] - `{snapshot, mutations, screenshot}`
+ * @returns {Object} The fake page
+ */
+export function createFakePage(options = {}) {
+  const emitter = new EventEmitter();
+  const state = {
+    snapshot: options.snapshot ?? makeSnapshot(),
+    mutations: options.mutations ? [...options.mutations] : [],
+    droppedMutations: options.droppedMutations ?? 0,
+    screenshot: options.screenshot ?? Buffer.from('fake-png'),
+    screenshots: 0,
+    evaluated: [],
+    failures: new Map(),
+  };
+
+  return {
+    state,
+    /**
+     * Make one in-page call fail, the way a closed page does.
+     *
+     * @param {string} name - In-page function name
+     * @param {Error|string} failure - What it should throw
+     * @returns {void}
+     */
+    failEvaluate(name, failure) {
+      state.failures.set(
+        name,
+        failure instanceof Error ? failure : new Error(failure)
+      );
+    },
+    /**
+     * Replace what the next capture returns.
+     *
+     * @param {Object} snapshot - A snapshot from `makeSnapshot()`
+     * @returns {void}
+     */
+    setSnapshot(snapshot) {
+      state.snapshot = snapshot;
+    },
+    /**
+     * Queue mutation batches for the next drain.
+     *
+     * @param {Object[]} batches - Ordered batches
+     * @returns {void}
+     */
+    queueMutations(batches) {
+      state.mutations.push(...batches);
+    },
+    evaluate: async (fn, argument) => {
+      const name = typeof fn === 'function' ? fn.name : String(fn);
+      state.evaluated.push({ name, argument });
+      const failure = state.failures.get(name);
+      if (failure) {
+        throw failure;
+      }
+      if (name === 'captureSnapshotInPage') {
+        return state.snapshot;
+      }
+      if (name === 'drainMutationsInPage') {
+        const batches = state.mutations.splice(0, state.mutations.length);
+        const dropped = state.droppedMutations;
+        state.droppedMutations = 0;
+        return { batches, dropped, installed: true };
+      }
+      return true;
+    },
+    screenshot: async () => {
+      state.screenshots += 1;
+      return state.screenshot;
+    },
+    on: (event, listener) => emitter.on(event, listener),
+    off: (event, listener) => emitter.off(event, listener),
+    emit: (event, payload) => emitter.emit(event, payload),
+    listenerCount: (event) => emitter.listenerCount(event),
+  };
+}
+
+/**
+ * Create a fake commander around a fake page.
+ *
+ * @param {Object} page - The page from `createFakePage()`
+ * @param {Object} [extras] - Extra commander properties, such as `downloads`
+ * @returns {Object} The fake commander
+ */
+export function createFakeCommander(page, extras = {}) {
+  return {
+    page,
+    engine: 'playwright',
+    evaluate: (fn, argument) => page.evaluate(fn, argument),
+    click: async (selector) => ({ clicked: selector }),
+    goto: async (url) => ({ url }),
+    typeText: async (selector, text) => ({ selector, text }),
+    ...extras,
+  };
+}
+
+/**
+ * A download manager's subscription surface, without a browser.
+ *
+ * @returns {Object} `{on, off, emit, listenerCount}`
+ */
+export function createFakeDownloads() {
+  // The manager's subscription surface is an emitter's, so a plain one is the
+  // fixture: `on`, `off` and `listenerCount` are the calls the recorder makes.
+  return new EventEmitter();
+}
+
+/**
+ * A dialog manager's observation surface, without a browser.
+ *
+ * `raise()` plays the manager's own rule back: observers are told, and a
+ * dialog nobody answered is dismissed rather than left blocking the page.
+ *
+ * @returns {Object} `{observeDialogs, unobserveDialogs, observerCount, raise}`
+ */
+export function createFakeDialogManager() {
+  const observers = [];
+
+  return {
+    observeDialogs: (observer) => observers.push(observer),
+    unobserveDialogs: (observer) => {
+      const index = observers.indexOf(observer);
+      if (index !== -1) {
+        observers.splice(index, 1);
+      }
+    },
+    observerCount: () => observers.length,
+    raise: async ({ type, message }) => {
+      const dialog = {
+        dismissed: false,
+        type: () => type,
+        message: () => message,
+        dismiss: async () => {
+          dialog.dismissed = true;
+        },
+      };
+      for (const observer of observers) {
+        await observer(dialog);
+      }
+      if (!dialog.dismissed) {
+        await dialog.dismiss();
+      }
+      return dialog;
+    },
+  };
+}

package/tests/helpers/trace-server.js

@@ -0,0 +1,117 @@
+/**
+ * A tiny server for the real-browser trace tests (issue #87).
+ *
+ * The trace format claims to capture things a mock cannot produce: the value a
+ * user actually typed, DOM mutations an SPA makes without navigating, a full
+ * navigation that replaces the document and the observer with it, a dialog, a
+ * request that never reaches a server, and a download that lands on disk.
+ */
+
+import { sendHtml, sendNotFound, startFixtureHost } from './fixture-server.js';
+
+/** Text the download endpoint serves. */
+export const TRACE_DOWNLOAD_BODY = 'traced report body';
+
+/** A password the page is given, which must never reach a bundle. */
+export const TRACE_SECRET = 'correct-horse-battery-staple';
+
+/** The page the trace tests drive. */
+export const TRACE_PAGE = `<!doctype html>
+<html><head><title>Traced app</title></head>
+<body style="margin:0">
+  <form id="signup">
+    <input id="name" name="name" type="text" value="">
+    <input id="password" name="password" type="password" value="">
+    <select id="plan"><option value="free">Free</option><option value="pro">Pro</option></select>
+    <label><input id="terms" type="checkbox"> I agree</label>
+  </form>
+  <ul id="items"></ul>
+  <p id="status" data-state="idle">idle</p>
+  <iframe id="inner" name="inner" src="/frame" style="width:80px;height:40px"></iframe>
+  <a id="next" href="/next">Go to the next page</a>
+  <a id="download" href="/file/report.txt" download>Download the report</a>
+  <button id="add" type="button">Add an item</button>
+  <button id="touch" type="button">Change the status</button>
+  <button id="log" type="button">Log something</button>
+  <button id="boom" type="button">Throw</button>
+  <button id="ask" type="button">Ask</button>
+  <button id="unreachable" type="button">Call a server that is not there</button>
+  <script>
+    let added = 0;
+    document.getElementById('add').addEventListener('click', () => {
+      const item = document.createElement('li');
+      item.id = 'item-' + ++added;
+      item.textContent = 'item ' + added;
+      document.getElementById('items').appendChild(item);
+    });
+    document.getElementById('touch').addEventListener('click', () => {
+      const status = document.getElementById('status');
+      status.setAttribute('data-state', 'touched');
+      status.textContent = 'touched';
+    });
+    document.getElementById('log').addEventListener('click', () => {
+      console.log('something happened');
+    });
+    document.getElementById('boom').addEventListener('click', () => {
+      setTimeout(() => {
+        throw new Error('page error on purpose');
+      }, 0);
+    });
+    document.getElementById('ask').addEventListener('click', () => {
+      window.alert('are you sure?');
+    });
+    document.getElementById('unreachable').addEventListener('click', () => {
+      // Port 1 is never listening, so the request fails in the network stack
+      // rather than arriving somewhere and being answered with an error.
+      fetch('http://127.0.0.1:1/nope').catch(() => {});
+    });
+  </script>
+</body></html>`;
+
+/** The page a full navigation lands on. */
+export const NEXT_PAGE = `<!doctype html>
+<html><head><title>Next page</title></head>
+<body style="margin:0">
+  <p id="second">the second document</p>
+  <button id="grow" type="button">Grow</button>
+  <ul id="more"></ul>
+  <script>
+    document.getElementById('grow').addEventListener('click', () => {
+      const item = document.createElement('li');
+      item.id = 'grown';
+      item.textContent = 'grown after navigating';
+      document.getElementById('more').appendChild(item);
+    });
+  </script>
+</body></html>`;
+
+/**
+ * Start the fixture server the trace tests drive.
+ *
+ * @returns {Promise<{baseUrl: string, close: Function}>} Server handle
+ */
+export async function startTraceServer() {
+  return startFixtureHost((path, req, res) => {
+    if (path === '/' || path === '/app') {
+      sendHtml(res, TRACE_PAGE);
+      return;
+    }
+    if (path === '/next') {
+      sendHtml(res, NEXT_PAGE);
+      return;
+    }
+    if (path === '/frame') {
+      sendHtml(res, '<!doctype html><p id="framed">inside a frame</p>');
+      return;
+    }
+    if (path.startsWith('/file/')) {
+      res.writeHead(200, {
+        'content-type': 'text/plain',
+        'content-disposition': `attachment; filename="${path.slice('/file/'.length)}"`,
+      });
+      res.end(TRACE_DOWNLOAD_BODY);
+      return;
+    }
+    sendNotFound(res);
+  });
+}

package/tests/unit/core/dialog-manager.test.js

@@ -266,10 +266,98 @@ describe('dialog-manager', () => {
     });
   });
 
+  describe('observeDialogs', () => {
+    /**
+     * A manager already listening to the page, as every observer test needs.
+     *
+     * @returns {Object} The dialog manager
+     */
+    const listening = () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      manager.startListening();
+      return manager;
+    };
+
+    it('should still auto-dismiss when only observers are watching', async () => {
+      const manager = listening();
+
+      const seen = [];
+      manager.observeDialogs((dialog) => seen.push(dialog.message()));
+      const dialog = createMockDialog({ message: 'watched' });
+      await page.emit('dialog', dialog);
+
+      assert.deepStrictEqual(seen, ['watched']);
+      // Watching a dialog must not make the watcher responsible for it, or a
+      // traced run leaves the page waiting for an answer an untraced run got.
+      assert.strictEqual(dialog._wasDismissed(), true);
+    });
+
+    it('should tell observers about a dialog a handler answers', async () => {
+      const manager = listening();
+
+      const seen = [];
+      manager.observeDialogs((dialog) => seen.push(dialog.type()));
+      manager.onDialog(async (dialog) => dialog.accept('ok'));
+      const dialog = createMockDialog({ type: 'prompt' });
+      await page.emit('dialog', dialog);
+
+      assert.deepStrictEqual(seen, ['prompt']);
+      assert.strictEqual(dialog._acceptText(), 'ok');
+      assert.strictEqual(dialog._wasDismissed(), false);
+    });
+
+    it('should keep going when an observer throws', async () => {
+      const manager = listening();
+
+      let secondObserverCalled = false;
+      manager.observeDialogs(() => {
+        throw new Error('observer failed');
+      });
+      manager.observeDialogs(() => {
+        secondObserverCalled = true;
+      });
+      const dialog = createMockDialog();
+      await page.emit('dialog', dialog);
+
+      assert.strictEqual(secondObserverCalled, true);
+      assert.strictEqual(dialog._wasDismissed(), true);
+    });
+
+    it('should stop telling an observer that was removed', async () => {
+      const manager = listening();
+
+      let calls = 0;
+      const stop = manager.observeDialogs(() => {
+        calls += 1;
+      });
+      await page.emit('dialog', createMockDialog());
+      stop();
+      await page.emit('dialog', createMockDialog());
+
+      assert.strictEqual(calls, 1);
+    });
+
+    it('should refuse an observer that is not a function', () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+
+      assert.throws(() => manager.observeDialogs('nope'), /must be a function/);
+    });
+  });
+
   describe('integration with makeBrowserCommander', () => {
-    it('should expose onDialog on commander', async () => {
+    /**
+     * A commander driving the suite's page.
+     *
+     * @param {Object} [options] - Extra options for `makeBrowserCommander`
+     * @returns {Promise<Object>} The commander
+     */
+    const commanderFor = async (options = {}) => {
       const { makeBrowserCommander } = await import('../../../src/factory.js');
-      const commander = makeBrowserCommander({ page, verbose: false });
+      return makeBrowserCommander({ page, verbose: false, ...options });
+    };
+
+    it('should expose onDialog on commander', async () => {
+      const commander = await commanderFor();
 
       assert.ok(typeof commander.onDialog === 'function');
       assert.ok(typeof commander.offDialog === 'function');
@@ -278,8 +366,7 @@ describe('dialog-manager', () => {
     });
 
     it('should handle dialog via commander.onDialog', async () => {
-      const { makeBrowserCommander } = await import('../../../src/factory.js');
-      const commander = makeBrowserCommander({ page, verbose: false });
+      const commander = await commanderFor();
 
       let handlerCalled = false;
       commander.onDialog(async (dialog) => {
@@ -296,13 +383,34 @@ describe('dialog-manager', () => {
       await commander.destroy();
     });
 
+    it('should expose observeDialogs on commander', async () => {
+      const commander = await commanderFor();
+
+      const seen = [];
+      commander.observeDialogs((dialog) => seen.push(dialog.message()));
+      const dialog = createMockDialog({ message: 'from the commander' });
+      await page.emit('dialog', dialog);
+
+      assert.deepStrictEqual(seen, ['from the commander']);
+      assert.strictEqual(dialog._wasDismissed(), true);
+
+      await commander.destroy();
+    });
+
+    it('should throw observeDialogs when enableDialogManager is false', async () => {
+      const commander = await commanderFor({ enableDialogManager: false });
+
+      assert.throws(
+        () => commander.observeDialogs(() => {}),
+        /enableDialogManager/
+      );
+      // Removing an observer from a manager that never existed is a no-op,
+      // so cleanup code does not have to know whether tracing was on.
+      assert.doesNotThrow(() => commander.unobserveDialogs(() => {}));
+    });
+
     it('should throw onDialog when enableDialogManager is false', async () => {
-      const { makeBrowserCommander } = await import('../../../src/factory.js');
-      const commander = makeBrowserCommander({
-        page,
-        verbose: false,
-        enableDialogManager: false,
-      });
+      const commander = await commanderFor({ enableDialogManager: false });
 
       assert.throws(() => commander.onDialog(() => {}), /enableDialogManager/);
     });

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

@@ -4,7 +4,33 @@ import { createNavigationManager } from '../../../src/core/navigation-manager.js
 import {
   createMockPlaywrightPage,
   createMockLogger,
+  createMockNetworkTracker,
 } from '../../helpers/mocks.js';
+import { READINESS_STATUS } from '../../../src/core/readiness.js';
+
+/**
+ * Build a navigation manager wired to a network tracker whose idle wait is
+ * fully controlled by the test.
+ */
+function createManagerWithNetwork(options = {}) {
+  const { idle = true, onIdleWait = () => {} } = options;
+  const page = createMockPlaywrightPage();
+  const log = createMockLogger();
+  const networkTracker = createMockNetworkTracker();
+  networkTracker.waitForNetworkIdle = async (opts = {}) => {
+    onIdleWait(opts);
+    return typeof idle === 'function' ? await idle(opts) : idle;
+  };
+
+  const manager = createNavigationManager({
+    page,
+    engine: 'playwright',
+    log,
+    networkTracker,
+  });
+  manager.configure({ redirectStabilizationTime: 0 });
+  return { manager, page, log, networkTracker };
+}
 
 describe('navigation manager', () => {
   describe('setContent', () => {
@@ -59,4 +85,140 @@ describe('navigation manager', () => {
       await assert.doesNotReject(() => manager.setContent({ html: '' }));
     });
   });
+
+  describe('waitForReady', () => {
+    it('should never extend the caller deadline beyond the timeout', async () => {
+      // Regression test for issue #89: the old implementation waited
+      // `Math.max(60000, timeout - elapsed)`, so a 500ms budget could block for
+      // a full minute.
+      const idleTimeouts = [];
+      const { manager } = createManagerWithNetwork({
+        idle: true,
+        onIdleWait: (opts) => idleTimeouts.push(opts.timeout),
+      });
+
+      await manager.waitForReady({ timeout: 1000, reason: 'deadline test' });
+
+      assert.strictEqual(idleTimeouts.length, 1);
+      assert.ok(
+        idleTimeouts[0] <= 1000,
+        `network idle timeout ${idleTimeouts[0]} exceeded the 1000ms budget`
+      );
+    });
+
+    it('should report timed_out instead of claiming the page is ready', async () => {
+      // Regression test for issue #89: `waitForPageReady` logged "Page ready"
+      // and returned true even after network idle had failed.
+      const { manager } = createManagerWithNetwork({
+        // Burn the whole remaining budget, the way a real idle wait does.
+        idle: async (opts) => {
+          await new Promise((resolve) => setTimeout(resolve, opts.timeout));
+          return false;
+        },
+      });
+
+      const result = await manager.waitForReady({
+        timeout: 600,
+        reason: 'failure test',
+      });
+
+      assert.strictEqual(result.ready, false);
+      assert.strictEqual(result.status, READINESS_STATUS.TIMED_OUT);
+      assert.ok(result.checks.failed.includes('networkIdleFor'));
+      assert.ok(
+        result.elapsedMs < 3000,
+        `wait took ${result.elapsedMs}ms for a 600ms budget`
+      );
+    });
+
+    it('should report failed when a check fails before the deadline', async () => {
+      const { manager } = createManagerWithNetwork({ idle: false });
+
+      const result = await manager.waitForReady({ timeout: 5000 });
+
+      assert.strictEqual(result.ready, false);
+      assert.strictEqual(result.status, READINESS_STATUS.FAILED);
+      assert.ok(result.checks.failed.includes('networkIdleFor'));
+    });
+
+    it('should not emit onPageReady after a failed wait', async () => {
+      // Regression test for issue #89: cleanup and the ready event were both
+      // owned by completeNavigation(), so failing waits still announced ready.
+      const { manager } = createManagerWithNetwork({ idle: false });
+      const events = [];
+      manager.on('onPageReady', () => events.push('pageReady'));
+      manager.on('onNavigationComplete', (payload) =>
+        events.push(`complete:${payload.ready}`)
+      );
+
+      const ready = await manager.navigate({
+        url: 'https://example.com',
+        timeout: 1000,
+      });
+
+      assert.strictEqual(ready, false);
+      assert.ok(!events.includes('pageReady'));
+      assert.ok(events.includes('complete:false'));
+      assert.strictEqual(manager.isNavigating(), false);
+    });
+
+    it('should emit onPageReady exactly once when every check passes', async () => {
+      const { manager } = createManagerWithNetwork({ idle: true });
+      const events = [];
+      manager.on('onPageReady', () => events.push('pageReady'));
+
+      const result = await manager.waitForReady({ timeout: 2000 });
+
+      assert.strictEqual(result.ready, true);
+      assert.strictEqual(result.status, READINESS_STATUS.READY);
+      assert.deepStrictEqual(events, ['pageReady']);
+      assert.ok(result.checks.satisfied.includes('networkIdleFor'));
+    });
+
+    it('should record evidence for every check it ran', async () => {
+      const { manager } = createManagerWithNetwork({ idle: true });
+
+      const result = await manager.waitForReady({ timeout: 2000 });
+
+      assert.ok(Array.isArray(result.evidence));
+      assert.ok(result.evidence.length >= 2);
+      for (const entry of result.evidence) {
+        assert.strictEqual(typeof entry.name, 'string');
+        assert.strictEqual(typeof entry.satisfied, 'boolean');
+        assert.strictEqual(typeof entry.elapsedMs, 'number');
+      }
+    });
+
+    it('should stop running checks once the deadline is exhausted', async () => {
+      let secondCheckRan = false;
+      const { manager } = createManagerWithNetwork({ idle: true });
+
+      const slow = {
+        name: 'slow',
+        async run({ deadline }) {
+          await new Promise((resolve) => setTimeout(resolve, 60));
+          return {
+            satisfied: false,
+            detail: { remaining: deadline.remainingMs() },
+          };
+        },
+      };
+      const second = {
+        name: 'second',
+        async run() {
+          secondCheckRan = true;
+          return { satisfied: true };
+        },
+      };
+
+      const result = await manager.waitForReady({
+        timeout: 50,
+        checks: [slow, second],
+      });
+
+      assert.strictEqual(result.ready, false);
+      assert.strictEqual(secondCheckRan, false);
+      assert.ok(result.checks.pending.includes('second'));
+    });
+  });
 });