npm - browser-commander - Versions diffs - 0.17.2 → 0.19.0 - Mend

browser-commander 0.17.2 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (74) hide show

package/.jscpd-baseline.json +12 -17
package/CHANGELOG.md +68 -0
package/README.md +132 -0
package/eslint.config.js +5 -0
package/package.json +5 -1
package/src/bindings.js +13 -1
package/src/browser/connector.js +15 -3
package/src/browser/launcher.js +14 -2
package/src/browser/navigation.js +63 -0
package/src/core/dialog-manager.js +48 -0
package/src/core/navigation-manager.js +83 -87
package/src/core/navigation-readiness.js +133 -0
package/src/core/readiness.js +478 -0
package/src/downloads/attach.js +58 -0
package/src/downloads/destination.js +125 -0
package/src/downloads/manager.js +476 -0
package/src/downloads/naming.js +246 -0
package/src/downloads/sources.js +238 -0
package/src/downloads/staging.js +146 -0
package/src/downloads/store.js +256 -0
package/src/exports.js +86 -0
package/src/factory.js +55 -0
package/src/interactions/click-activation.js +317 -0
package/src/interactions/click-result.js +108 -0
package/src/interactions/click.js +766 -352
package/src/tests/index.js +75 -11
package/src/tests/tracing.js +236 -0
package/src/traces/bundle.js +338 -0
package/src/traces/deadline.js +33 -0
package/src/traces/identity.js +127 -0
package/src/traces/init-script.js +95 -0
package/src/traces/links.js +623 -0
package/src/traces/mutation-stream.js +232 -0
package/src/traces/observers.js +272 -0
package/src/traces/page-capture.js +601 -0
package/src/traces/reader.js +226 -0
package/src/traces/recorder.js +454 -0
package/src/traces/redaction.js +231 -0
package/src/traces/schema.js +229 -0
package/src/traces/viewer.js +448 -0
package/tests/e2e/click-readiness.e2e.test.js +240 -0
package/tests/e2e/downloads.e2e.test.js +235 -0
package/tests/e2e/traces.e2e.test.js +742 -0
package/tests/helpers/click-fixtures.js +62 -0
package/tests/helpers/download-fixtures.js +125 -0
package/tests/helpers/download-server.js +129 -0
package/tests/helpers/e2e-browser.js +67 -0
package/tests/helpers/file-modes.js +31 -0
package/tests/helpers/fixture-server.js +56 -0
package/tests/helpers/mocks.js +63 -66
package/tests/helpers/readiness-server.js +96 -0
package/tests/helpers/temp-directory.js +44 -0
package/tests/helpers/trace-fixtures.js +274 -0
package/tests/helpers/trace-server.js +173 -0
package/tests/unit/core/dialog-manager.test.js +118 -10
package/tests/unit/core/navigation-manager.test.js +162 -0
package/tests/unit/core/readiness.test.js +517 -0
package/tests/unit/downloads/attach.test.js +220 -0
package/tests/unit/downloads/destination.test.js +114 -0
package/tests/unit/downloads/manager.test.js +485 -0
package/tests/unit/downloads/naming.test.js +174 -0
package/tests/unit/downloads/staging.test.js +117 -0
package/tests/unit/downloads/store.test.js +215 -0
package/tests/unit/interactions/click-activation.test.js +283 -0
package/tests/unit/interactions/click-result.test.js +90 -0
package/tests/unit/interactions/click.test.js +409 -200
package/tests/unit/tests/tracing.test.js +299 -0
package/tests/unit/traces/bundle.test.js +260 -0
package/tests/unit/traces/links.test.js +557 -0
package/tests/unit/traces/reader.test.js +208 -0
package/tests/unit/traces/recorder.test.js +730 -0
package/tests/unit/traces/redaction.test.js +170 -0
package/tests/unit/traces/schema.test.js +92 -0
package/tests/unit/traces/viewer.test.js +294 -0

package/tests/helpers/readiness-server.js ADDED Viewed

@@ -0,0 +1,96 @@
+/**
+ * A tiny static server for the real-browser readiness and click tests.
+ *
+ * The issue #89 repros need pages that a mock cannot fake: an element far
+ * below the fold, a button whose handler does nothing, a link that navigates,
+ * and a page whose network never goes quiet. Serving them from localhost keeps
+ * the tests self-contained - no external app has to be running.
+ */
+import { sendHtml, sendNotFound, startFixtureHost } from './fixture-server.js';
+/** A button 4200px down a tall page, matching the issue #89 repro. */
+export const FAR_BELOW_FOLD_PAGE = `<!doctype html>
+<html><body style="margin:0">
+  <div style="height:4200px"></div>
+  <button id="target" style="height:40px">Far below the fold</button>
+  <div style="height:2000px"></div>
+  <script>
+    window.__clicks = 0;
+    document.getElementById('target').addEventListener('click', () => {
+      window.__clicks += 1;
+      document.getElementById('target').setAttribute('aria-pressed', 'true');
+    });
+  </script>
+</body></html>`;
+/** A button in the viewport whose handler does nothing observable. */
+export const NO_OP_PAGE = `<!doctype html>
+<html><body style="margin:0">
+  <button id="noop" style="height:40px">Does nothing</button>
+  <script>
+    window.__clicks = 0;
+    document.getElementById('noop').addEventListener('click', () => {
+      window.__clicks += 1;
+    });
+  </script>
+</body></html>`;
+/** A link that navigates to another page on the same server. */
+export const NAVIGATES_PAGE = `<!doctype html>
+<html><body style="margin:0">
+  <a id="go" href="/arrived">Go</a>
+</body></html>`;
+/** The navigation target. */
+export const ARRIVED_PAGE =
+  '<!doctype html><html><body><h1 id="arrived">Arrived</h1></body></html>';
+/** A page that keeps a request in flight forever, so the network never idles. */
+export const NEVER_IDLE_PAGE = `<!doctype html>
+<html><body>
+  <p id="loaded">loaded</p>
+  <script>fetch('/hang').catch(() => {});</script>
+</body></html>`;
+const PAGES = {
+  '/far-below-fold': FAR_BELOW_FOLD_PAGE,
+  '/no-op': NO_OP_PAGE,
+  '/navigates': NAVIGATES_PAGE,
+  '/arrived': ARRIVED_PAGE,
+  '/never-idle': NEVER_IDLE_PAGE,
+};
+/**
+ * Start the fixture server on an ephemeral port.
+ *
+ * @returns {Promise<{baseUrl: string, close: Function}>} Server handle
+ */
+export async function startFixtureServer() {
+  /** Requests parked on purpose, closed when the server shuts down. */
+  const hanging = new Set();
+  return startFixtureHost(
+    (path, req, res) => {
+      if (path === '/hang') {
+        hanging.add(res);
+        res.on('close', () => hanging.delete(res));
+        return;
+      }
+      const body = PAGES[path];
+      if (body === undefined) {
+        sendNotFound(res);
+        return;
+      }
+      sendHtml(res, body);
+    },
+    () => {
+      for (const res of hanging) {
+        res.destroy();
+      }
+      hanging.clear();
+    }
+  );
+}

package/tests/helpers/temp-directory.js ADDED Viewed

@@ -0,0 +1,44 @@
+/**
+ * Temporary directories for tests that write real files.
+ *
+ * Download and trace tests both need a directory of their own per test, and
+ * both may leave it read-only on purpose, so the lifecycle lives in one place.
+ */
+import { afterEach, beforeEach } from 'node:test';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Create a temporary directory.
+ *
+ * @param {string} [prefix] - Name prefix, to tell suites apart under /tmp
+ * @returns {Promise<string>} Absolute directory path
+ */
+export async function makeTempDirectory(prefix = 'bc-test-') {
+  return fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+/**
+ * Give each test in a suite its own directory.
+ *
+ * @param {string} [prefix] - Name prefix for the directories
+ * @returns {{path: string}} Holder whose `path` is the current directory
+ */
+export function useTempDirectory(prefix) {
+  const holder = { path: '' };
+  beforeEach(async () => {
+    holder.path = await makeTempDirectory(prefix);
+  });
+  afterEach(async () => {
+    // A test may have made the directory read-only on purpose; removing it
+    // still has to work, or the next test inherits the mess.
+    await fs.chmod(holder.path, 0o700).catch(() => {});
+    await fs.rm(holder.path, { recursive: true, force: true });
+  });
+  return holder;
+}

package/tests/helpers/trace-fixtures.js ADDED Viewed

@@ -0,0 +1,274 @@
+/**
+ * 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, frames}`
+ * @param {Object[]} [options.frames] - Extra frames, each `{mutations}`; the
+ *   page itself is always the main frame, and a page given no frames has no
+ *   `frames()` at all, the way a page object from neither engine would
+ * @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: [],
+    initScripts: [],
+    failures: new Map(),
+  };
+  const page = {
+    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: batches.map((batch) => ({
+            frameId: 'main',
+            mainFrame: true,
+            ...batch,
+          })),
+          dropped,
+          installed: true,
+          frameId: 'main',
+          mainFrame: true,
+        };
+      }
+      return true;
+    },
+    screenshot: async () => {
+      state.screenshots += 1;
+      return state.screenshot;
+    },
+    /**
+     * Register a script for every future document, the Playwright spelling.
+     *
+     * @param {Function} fn - The function to run
+     * @param {*} argument - Its argument
+     * @returns {Promise<void>} Resolves once registered
+     */
+    addInitScript: async (fn, argument) => {
+      state.initScripts.push({
+        name: typeof fn === 'function' ? fn.name : String(fn),
+        argument,
+      });
+    },
+    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),
+  };
+  if (options.frames) {
+    const children = options.frames.map((frame, index) =>
+      createFakeFrame(state, frame, `child-${index + 1}`)
+    );
+    page.frames = () => [
+      createFakeFrame(state, null, 'main', page),
+      ...children,
+    ];
+  }
+  return page;
+}
+/**
+ * One frame of a fake page.
+ *
+ * The main frame answers out of the page's own state, so a page with frames
+ * behaves exactly like one without for everything except the extra documents.
+ *
+ * @param {Object} state - The page's state
+ * @param {Object|null} frame - `{mutations, dropped}` for a child frame
+ * @param {string} frameId - What this frame calls itself
+ * @param {Object} [page] - The page, when this is the main frame
+ * @returns {Object} A frame with `evaluate`
+ */
+function createFakeFrame(state, frame, frameId, page) {
+  if (page) {
+    return { evaluate: page.evaluate };
+  }
+  const queued = frame?.mutations ? [...frame.mutations] : [];
+  return {
+    evaluate: async (fn, argument) => {
+      const name = typeof fn === 'function' ? fn.name : String(fn);
+      state.evaluated.push({ name, argument, frameId });
+      if (name === 'drainMutationsInPage') {
+        return {
+          batches: queued
+            .splice(0, queued.length)
+            .map((batch) => ({ frameId, mainFrame: false, ...batch })),
+          dropped: frame?.dropped ?? 0,
+          installed: true,
+          frameId,
+          mainFrame: false,
+        };
+      }
+      return true;
+    },
+  };
+}
+/**
+ * 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 ADDED Viewed

@@ -0,0 +1,173 @@
+/**
+ * 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"><li id="item-a">a</li><li id="item-b">b</li></ul>
+  <div id="subtree"><p id="old-child">old</p></div>
+  <p id="status" data-state="idle">idle</p>
+  <textarea id="notes"></textarea>
+  <div id="tall" style="height:3000px"></div>
+  <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="insert-first" type="button">Insert before the first item</button>
+  <button id="move-last" type="button">Move the last item to the front</button>
+  <button id="remove-one" type="button">Remove an item</button>
+  <button id="replace-subtree" type="button">Replace a subtree</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);
+    });
+    // Issue #93's third regression case: a replay that only appends gets
+    // every one of these wrong.
+    const items = () => document.getElementById('items');
+    document.getElementById('insert-first').addEventListener('click', () => {
+      const item = document.createElement('li');
+      item.id = 'inserted';
+      item.textContent = 'inserted first';
+      items().insertBefore(item, items().firstChild);
+    });
+    document.getElementById('move-last').addEventListener('click', () => {
+      items().insertBefore(items().lastElementChild, items().firstChild);
+    });
+    document.getElementById('remove-one').addEventListener('click', () => {
+      const gone = document.getElementById('item-a');
+      if (gone) gone.remove();
+    });
+    document.getElementById('replace-subtree').addEventListener('click', () => {
+      const subtree = document.getElementById('subtree');
+      subtree.replaceChildren();
+      const fresh = document.createElement('p');
+      fresh.id = 'new-child';
+      fresh.textContent = 'new';
+      subtree.appendChild(fresh);
+    });
+    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>`;
+/**
+ * A page that changes its own DOM while it is still loading.
+ *
+ * Issue #93's first regression case: the interval between a navigation and the
+ * next checkpoint used to be unrecorded, because the in-page observer died
+ * with the previous document. Everything this page builds happens before any
+ * automation could install an observer after the fact.
+ */
+export const INIT_PAGE = `<!doctype html>
+<html><head><title>Initializing page</title></head>
+<body style="margin:0">
+  <div id="root"></div>
+  <script>
+    const made = document.createElement('p');
+    made.id = 'made-while-loading';
+    made.textContent = 'built during initialization';
+    document.getElementById('root').appendChild(made);
+    document.getElementById('root').setAttribute('data-initialized', 'yes');
+  </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 === '/init') {
+      sendHtml(res, INIT_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);
+  });
+}