browser-commander 0.17.2 → 0.19.0

package/tests/helpers/click-fixtures.js

@@ -0,0 +1,62 @@
+/**
+ * Shared fixtures for the click tests.
+ *
+ * The activation tests and the `clickElement` tests exercise the same two
+ * shapes - an element state probe result and a click-point probe result - so
+ * they live here instead of drifting apart in two files.
+ */
+
+/** State of a plain, enabled button that nothing has changed. */
+export const UNCHANGED_STATE = Object.freeze({
+  disabled: false,
+  ariaPressed: 'false',
+  ariaExpanded: null,
+  ariaSelected: null,
+  checked: false,
+  className: 'btn',
+  isConnected: true,
+});
+
+/** Click-point probe result for an element fully inside the viewport. */
+export const IN_VIEWPORT_POINT = Object.freeze({
+  x: 50,
+  y: 60,
+  width: 100,
+  height: 40,
+  top: 40,
+  left: 0,
+  viewport: { width: 800, height: 600 },
+  scroll: { x: 0, y: 0 },
+  inViewport: true,
+  hitsTarget: true,
+});
+
+/**
+ * A mutable window scroll position with the `evaluateOnPage` contract the
+ * click code uses: an empty argument list reads the position, a one-element
+ * list writes it. The list is what the real adapter takes - passing a bare
+ * object made Playwright try to spread it.
+ *
+ * @param {number} [initial] - Initial vertical scroll offset
+ * @returns {{current: Function, set: Function, evaluateOnPage: Function}} Scroll model
+ */
+export function createScrollModel(initial = 0) {
+  let scrollY = initial;
+
+  return {
+    current: () => scrollY,
+    set: (next) => {
+      scrollY = next;
+    },
+    evaluateOnPage: async (fn, args = []) => {
+      if (!Array.isArray(args)) {
+        throw new TypeError('evaluateOnPage takes an argument list');
+      }
+      if (args.length > 0) {
+        scrollY = args[0].y;
+        return undefined;
+      }
+      return { x: 0, y: scrollY };
+    },
+  };
+}

package/tests/helpers/download-fixtures.js

@@ -0,0 +1,125 @@
+/**
+ * Fixtures for the managed download tests (issue #88).
+ *
+ * The fake context speaks exactly the part of Playwright's download API the
+ * manager uses, so the tests exercise the real event plumbing without needing
+ * a browser.
+ */
+
+import { EventEmitter } from 'node:events';
+import { setImmediate as yieldToEngine } from 'node:timers/promises';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  makeTempDirectory as makeDirectory,
+  useTempDirectory,
+} from './temp-directory.js';
+
+/**
+ * Create a temporary directory that a test can write downloads into.
+ *
+ * @returns {Promise<string>} Absolute directory path
+ */
+export async function makeTempDirectory() {
+  return makeDirectory('bc-downloads-');
+}
+
+/**
+ * Build a fake Playwright download whose bytes are already on disk.
+ *
+ * @param {Object} options - Download options
+ * @param {string} options.dir - Directory to stage the bytes in
+ * @param {string} options.suggestedFilename - Name the page suggested
+ * @param {string|Buffer} [options.body] - File contents
+ * @param {string} [options.url] - Source URL
+ * @param {string} [options.failure] - Engine failure text, when it failed
+ * @returns {Promise<Object>} Fake download object
+ */
+export async function makeFakeDownload({
+  dir,
+  suggestedFilename,
+  body = 'hello',
+  url = 'https://example.com/file',
+  failure = null,
+}) {
+  const staged = path.join(
+    dir,
+    `staged-${Math.random().toString(36).slice(2)}`
+  );
+  if (!failure) {
+    await fs.writeFile(staged, body);
+  }
+
+  return {
+    url: () => url,
+    suggestedFilename: () => suggestedFilename,
+    failure: async () => failure,
+    path: async () => staged,
+    stagedPath: staged,
+  };
+}
+
+/**
+ * Expose an emitter the way an engine object does.
+ *
+ * @param {Object} emitter - Backing event emitter
+ * @returns {{on: Function, off: Function}} Subscription methods
+ */
+function subscriptionsOf(emitter) {
+  return {
+    on: (event, listener) => emitter.on(event, listener),
+    off: (event, listener) => emitter.off(event, listener),
+  };
+}
+
+/**
+ * Create a fake browser context that emits download events.
+ *
+ * @returns {Object} Context with `on`, `off` and `emitDownload`
+ */
+export function createFakeContext() {
+  const emitter = new EventEmitter();
+  return {
+    ...subscriptionsOf(emitter),
+    /**
+     * Emit a download and wait for the manager to finish handling it.
+     *
+     * @param {Object} download - Fake download object
+     * @returns {Promise<void>}
+     */
+    emitDownload: async (download) => {
+      emitter.emit('download', download);
+      // The manager's handler is async; yielding twice lets it run to the
+      // point where the artifact is saved and published.
+      await yieldToEngine();
+      await yieldToEngine();
+    },
+  };
+}
+
+/**
+ * Create a fake CDP session that speaks the Browser download domain.
+ *
+ * @returns {Object} Session with `send`, `on`, `off` and `emit`
+ */
+export function createFakeCdpSession() {
+  const emitter = new EventEmitter();
+  const sent = [];
+  return {
+    ...subscriptionsOf(emitter),
+    sent,
+    send: async (method, params) => {
+      sent.push({ method, params });
+    },
+    emit: (event, payload) => emitter.emit(event, payload),
+  };
+}
+
+/**
+ * Give a suite its own download directory, created and removed per test.
+ *
+ * @returns {{path: string}} Holder whose `path` is the current directory
+ */
+export function useTempDownloadDirectory() {
+  return useTempDirectory('bc-downloads-');
+}

package/tests/helpers/download-server.js

@@ -0,0 +1,129 @@
+/**
+ * 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 PDF large enough that Chromium writes it in more than one chunk.
+ *
+ * Issue #92 is a race between `Browser.downloadProgress` reporting
+ * `completed` and the staged bytes being readable, so a body the browser can
+ * write in a single instant is the one body that would not exercise it.
+ */
+export const BLOB_PDF_BODY = `%PDF-1.7\n${'blob pdf payload line\n'.repeat(40000)}%%EOF\n`;
+
+/** 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>
+  <button id="blob-pdf">Build and download a PDF</button>
+  <script>
+    const downloadBlob = (parts, type, name) => {
+      const url = URL.createObjectURL(new Blob(parts, { type }));
+      const anchor = document.createElement('a');
+      anchor.href = url;
+      anchor.download = name;
+      document.body.appendChild(anchor);
+      anchor.click();
+    };
+    document.getElementById('blob').addEventListener('click', () => {
+      downloadBlob([${JSON.stringify(REPORT_BODY)}], 'text/plain', 'generated.txt');
+    });
+    document.getElementById('blob-pdf').addEventListener('click', () => {
+      // Built from a repeated unit rather than shipped as one literal: the
+      // page has to produce the bytes, not receive them over the wire.
+      const line = ${JSON.stringify('blob pdf payload line\n')};
+      downloadBlob(
+        ['%PDF-1.7\\n', line.repeat(40000), '%%EOF\\n'],
+        'application/pdf',
+        'generated.pdf'
+      );
+    });
+  </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'),
   };