browser-commander 0.17.2 → 0.18.0

package/tests/helpers/download-server.js

@@ -0,0 +1,109 @@
+/**
+ * A tiny server for the real-browser download tests (issue #88).
+ *
+ * The issue's acceptance criteria are about downloads a mock cannot produce:
+ * a link the browser downloads instead of navigating to, a file built in the
+ * page from a blob, a navigation that turns into a download, a name the page
+ * only hints at, and a transfer the server aborts halfway.
+ */
+
+import { sendHtml, sendNotFound, startFixtureHost } from './fixture-server.js';
+
+/** Bytes every fixture download is expected to produce. */
+export const REPORT_BODY = 'quarterly report body';
+
+/** A body only its leading bytes identify as a PDF. */
+export const PDF_BODY = `%PDF-1.7\n${REPORT_BODY}`;
+
+/** A page offering the download shapes the issue lists. */
+export const DOWNLOADS_PAGE = `<!doctype html>
+<html><body style="margin:0">
+  <a id="link" href="/file/report.pdf" download>Download the report</a>
+  <a id="navigating" href="/attachment">Open the statement</a>
+  <a id="unnamed" href="/unnamed" download>Download without a name</a>
+  <a id="broken" href="/aborted" download>Download a broken file</a>
+  <button id="blob">Build and download</button>
+  <script>
+    document.getElementById('blob').addEventListener('click', () => {
+      const blob = new Blob([${JSON.stringify(REPORT_BODY)}], {
+        type: 'text/plain',
+      });
+      const url = URL.createObjectURL(blob);
+      const anchor = document.createElement('a');
+      anchor.href = url;
+      anchor.download = 'generated.txt';
+      document.body.appendChild(anchor);
+      anchor.click();
+    });
+  </script>
+</body></html>`;
+
+/**
+ * Answer a request for one of the fixture downloads.
+ *
+ * @param {string} path - Request path
+ * @param {Object} res - Node response
+ * @returns {boolean} Whether the request was a download
+ */
+function serveDownload(path, res) {
+  if (path.startsWith('/file/')) {
+    res.writeHead(200, {
+      'content-type': 'application/pdf',
+      'content-disposition': `attachment; filename="${path.slice('/file/'.length)}"`,
+    });
+    res.end(REPORT_BODY);
+    return true;
+  }
+
+  if (path === '/attachment') {
+    // No `download` attribute on the link: the browser starts navigating and
+    // turns the navigation into a download once it reads this header.
+    res.writeHead(200, {
+      'content-type': 'application/pdf',
+      'content-disposition': 'attachment; filename="statement.pdf"',
+    });
+    res.end(REPORT_BODY);
+    return true;
+  }
+
+  if (path === '/unnamed') {
+    // Nothing names this file and the server declares nothing useful: only the
+    // bytes themselves can give it a suffix.
+    res.writeHead(200, { 'content-type': 'application/octet-stream' });
+    res.end(PDF_BODY);
+    return true;
+  }
+
+  if (path === '/aborted') {
+    res.writeHead(200, {
+      'content-type': 'application/pdf',
+      'content-length': '1000000',
+      'content-disposition': 'attachment; filename="broken.pdf"',
+    });
+    res.write('partial');
+    res.destroy();
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Start the download fixture server on an ephemeral port.
+ *
+ * @returns {Promise<{baseUrl: string, close: Function}>} Server handle
+ */
+export async function startDownloadServer() {
+  return startFixtureHost((path, req, res) => {
+    if (serveDownload(path, res)) {
+      return;
+    }
+
+    if (path === '/') {
+      sendHtml(res, DOWNLOADS_PAGE);
+      return;
+    }
+
+    sendNotFound(res);
+  });
+}

package/tests/helpers/e2e-browser.js

@@ -0,0 +1,67 @@
+/**
+ * The browser an end-to-end suite runs against (issues #87, #88).
+ *
+ * Every real-browser suite needs the same three things before it can test
+ * anything: a throwaway profile, the arguments a sandbox-less container
+ * needs, and a directory the browser may write downloads into. Starting a
+ * browser is not what those suites are about, so it lives here once and they
+ * read as the behaviour they check.
+ */
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { launchBrowser } from '../../src/browser/launcher.js';
+
+/**
+ * Extra Chrome arguments for environments without a usable sandbox.
+ *
+ * Containers commonly forbid unprivileged user namespaces, where Chromium
+ * refuses to start at all; CHROME_NO_SANDBOX=true makes a suite runnable
+ * there without weakening how the library launches browsers for everyone else.
+ */
+export const SANDBOX_ARGS =
+  process.env.CHROME_NO_SANDBOX === 'true' ? ['--no-sandbox'] : [];
+
+/**
+ * Launch a real browser for one engine, with its own profile.
+ *
+ * @param {Object} options - Launch options
+ * @param {string} options.engine - 'playwright' or 'puppeteer'
+ * @param {string} [options.downloadDirectory] - Where managed downloads are kept
+ * @returns {Promise<{browser: Object, page: Object, downloads: Object, cleanup: Function}>} The launched browser and a `cleanup` that closes it and removes the profile
+ */
+export async function launchE2EBrowser(options = {}) {
+  const { engine, downloadDirectory } = options;
+  const userDataDir = await fs.mkdtemp(
+    path.join(os.tmpdir(), 'bc-e2e-profile-')
+  );
+
+  const launched = await launchBrowser({
+    engine,
+    userDataDir,
+    headless: process.env.HEADLESS !== 'false',
+    slowMo: 0,
+    args: SANDBOX_ARGS,
+    ...(process.env.CHROME_PATH
+      ? { executablePath: process.env.CHROME_PATH }
+      : {}),
+    ...(downloadDirectory
+      ? { downloads: { directory: downloadDirectory } }
+      : {}),
+  });
+
+  return {
+    ...launched,
+    /**
+     * Close the browser and remove the profile this helper created.
+     *
+     * @returns {Promise<void>} Resolves once both are gone
+     */
+    cleanup: async () => {
+      await launched.browser?.close();
+      await fs.rm(userDataDir, { recursive: true, force: true });
+    },
+  };
+}

package/tests/helpers/file-modes.js

@@ -0,0 +1,31 @@
+/**
+ * Checking owner-only permissions where the platform actually has them.
+ *
+ * Node accepts a `mode` on Windows and then ignores it: NTFS permissions are
+ * ACLs, not POSIX bits, and `fs.stat` reports a synthesised `0o666` whatever
+ * the file was created with. Asserting the mode there would be asserting
+ * Node's emulation rather than our code, so the permission check runs on the
+ * platforms that enforce it and the rest of each test runs everywhere.
+ */
+
+import assert from 'node:assert';
+import fs from 'node:fs/promises';
+
+/** Whether this platform enforces POSIX mode bits. */
+export const HAS_POSIX_MODES = process.platform !== 'win32';
+
+/**
+ * Assert that a path carries the mode the code asked for.
+ *
+ * @param {string} target - File or directory to inspect
+ * @param {number} expected - Expected permission bits, e.g. `0o600`
+ * @returns {Promise<void>} Resolves once checked, or immediately on Windows
+ */
+export async function assertMode(target, expected) {
+  if (!HAS_POSIX_MODES) {
+    return;
+  }
+
+  const { mode } = await fs.stat(target);
+  assert.strictEqual(mode & 0o777, expected);
+}

package/tests/helpers/fixture-server.js

@@ -0,0 +1,56 @@
+/**
+ * The bit of a fixture server that has nothing to do with the fixtures.
+ *
+ * The readiness pages (issue #89) and the download endpoints (issue #88) need
+ * the same thing underneath: a localhost server on a port nobody else is using,
+ * with a handle that shuts it down again.
+ */
+
+import { createServer } from 'node:http';
+
+/**
+ * Send an HTML fixture page.
+ *
+ * @param {Object} res - Node response
+ * @param {string} body - Page markup
+ * @returns {void}
+ */
+export function sendHtml(res, body) {
+  res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+  res.end(body);
+}
+
+/**
+ * Answer a request for a fixture that does not exist.
+ *
+ * @param {Object} res - Node response
+ * @returns {void}
+ */
+export function sendNotFound(res) {
+  res.writeHead(404, { 'content-type': 'text/plain' });
+  res.end('not found');
+}
+
+/**
+ * Start a fixture server on an ephemeral port.
+ *
+ * @param {Function} handle - Request handler, called with (path, req, res)
+ * @param {Function} [onClose] - Teardown to run before the server closes
+ * @returns {Promise<{baseUrl: string, close: Function}>} Server handle
+ */
+export async function startFixtureHost(handle, onClose) {
+  const server = createServer((req, res) => {
+    handle(req.url.split('?')[0], req, res);
+  });
+
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address();
+
+  return {
+    baseUrl: `http://127.0.0.1:${port}`,
+    close: async () => {
+      await onClose?.();
+      await new Promise((resolve) => server.close(resolve));
+    },
+  };
+}

package/tests/helpers/mocks.js

@@ -2,6 +2,67 @@
  * Mock utilities for unit tests
  */
 
+/**
+ * Members shared by the Playwright and Puppeteer page mocks.
+ *
+ * Both engines expose the same event, input and frame surface, so the mocks
+ * describe it once. `mouse` records its clicks because the `scroll: 'none'`
+ * click path dispatches real pointer input at a measured point.
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} options.url - URL the mock page reports
+ * @param {Map} options.eventListeners - Listener registry shared with the page
+ * @returns {Object} Shared page members
+ */
+function createSharedPageBehaviors(options) {
+  const { url, eventListeners } = options;
+
+  return {
+    mainFrame: () => ({
+      url: () => url,
+    }),
+    bringToFront: async () => {},
+    on: (event, handler) => {
+      if (!eventListeners.has(event)) {
+        eventListeners.set(event, []);
+      }
+      eventListeners.get(event).push(handler);
+    },
+    off: (event, handler) => {
+      const handlers = eventListeners.get(event);
+      if (handlers) {
+        const idx = handlers.indexOf(handler);
+        if (idx !== -1) {
+          handlers.splice(idx, 1);
+        }
+      }
+    },
+    emit: (event, data) => {
+      const handlers = eventListeners.get(event);
+      if (handlers) {
+        handlers.forEach((h) => h(data));
+      }
+    },
+    click: async (sel, opts = {}) => {},
+    type: async (sel, text, opts = {}) => {},
+    keyboard: {
+      press: async (key) => {},
+      type: async (text) => {},
+      down: async (key) => {},
+      up: async (key) => {},
+    },
+    mouse: {
+      clicks: [],
+      async click(x, y, opts = {}) {
+        this.clicks.push({ x, y, opts });
+      },
+      async move(x, y) {},
+      async down() {},
+      async up() {},
+    },
+  };
+}
+
 /**
  * Create a mock Playwright page object
  */
@@ -122,40 +183,8 @@ export function createMockPlaywrightPage(options = {}) {
         return fn;
       }
     },
-    mainFrame: () => ({
-      url: () => url,
-    }),
+    ...createSharedPageBehaviors({ url, eventListeners }),
     context: () => ({}),
-    bringToFront: async () => {},
-    on: (event, handler) => {
-      if (!eventListeners.has(event)) {
-        eventListeners.set(event, []);
-      }
-      eventListeners.get(event).push(handler);
-    },
-    off: (event, handler) => {
-      const handlers = eventListeners.get(event);
-      if (handlers) {
-        const idx = handlers.indexOf(handler);
-        if (idx !== -1) {
-          handlers.splice(idx, 1);
-        }
-      }
-    },
-    emit: (event, data) => {
-      const handlers = eventListeners.get(event);
-      if (handlers) {
-        handlers.forEach((h) => h(data));
-      }
-    },
-    click: async (sel, opts = {}) => {},
-    type: async (sel, text, opts = {}) => {},
-    keyboard: {
-      press: async (key) => {},
-      type: async (text) => {},
-      down: async (key) => {},
-      up: async (key) => {},
-    },
     pdf: async (opts = {}) => Buffer.from('%PDF-1.4 mock playwright'),
   };
 }
@@ -289,39 +318,7 @@ export function createMockPuppeteerPage(options = {}) {
       }
     },
     content: async () => '<html><body>Mock page</body></html>',
-    mainFrame: () => ({
-      url: () => url,
-    }),
-    bringToFront: async () => {},
-    on: (event, handler) => {
-      if (!eventListeners.has(event)) {
-        eventListeners.set(event, []);
-      }
-      eventListeners.get(event).push(handler);
-    },
-    off: (event, handler) => {
-      const handlers = eventListeners.get(event);
-      if (handlers) {
-        const idx = handlers.indexOf(handler);
-        if (idx !== -1) {
-          handlers.splice(idx, 1);
-        }
-      }
-    },
-    emit: (event, data) => {
-      const handlers = eventListeners.get(event);
-      if (handlers) {
-        handlers.forEach((h) => h(data));
-      }
-    },
-    click: async (sel, opts = {}) => {},
-    type: async (sel, text, opts = {}) => {},
-    keyboard: {
-      press: async (key) => {},
-      type: async (text) => {},
-      down: async (key) => {},
-      up: async (key) => {},
-    },
+    ...createSharedPageBehaviors({ url, eventListeners }),
     pdf: async (opts = {}) => Buffer.from('%PDF-1.4 mock puppeteer'),
   };
 

package/tests/helpers/readiness-server.js

@@ -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

@@ -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;
+}