browser-commander 0.19.0 → 0.21.0

package/src/parity/version-page.js

@@ -0,0 +1,144 @@
+/**
+ * Read chrome://version of a browser started with the reference command line.
+ *
+ * The browser rewrites its own command line: headless mode appends
+ * `--ozone-platform=headless`, `--use-angle=swiftshader-webgl`,
+ * `--no-first-run` and more, and a Linux build may append
+ * `--ozone-platform=x11`. chrome://version shows the rewritten line, so the
+ * automated browser's line cannot be compared with the argv a person typed.
+ * It is compared with what the same binary shows for that argv instead.
+ *
+ * A page cannot read chrome://version, so this capture needs a debugger. It
+ * uses a fixed `--remote-debugging-port` - which issue #101 measured to change
+ * nothing a page observes - and speaks raw CDP over the global WebSocket, so
+ * no automation engine is involved.
+ */
+import { startProcess } from '../utilities/subprocess.js';
+import { reserveLoopbackPort } from '../browser/debugging-port.js';
+import {
+  createTemporaryUserDataDir,
+  removeUserDataDir,
+} from '../browser/profile-directory.js';
+
+/** Evaluated in chrome://version; returns null until the page has rendered. */
+const READ_VERSION_PAGE = `(() => {
+  const text = (id) => (document.getElementById(id)?.textContent ?? '').trim();
+  if (!text('command_line')) return null;
+  return {
+    commandLine: text('command_line'),
+    version: text('version'),
+    executablePath: text('executable_path'),
+  };
+})()`;
+
+/** Send CDP commands over one page WebSocket. */
+function openCdpSocket(url) {
+  if (typeof globalThis.WebSocket !== 'function') {
+    throw new Error('Reading chrome://version needs Node.js 22.4 or newer');
+  }
+  const socket = new globalThis.WebSocket(url);
+  const pending = new Map();
+  let nextId = 1;
+  socket.addEventListener('message', (event) => {
+    const message = JSON.parse(String(event.data));
+    const waiter = pending.get(message.id);
+    if (typeof waiter === 'function') {
+      pending.delete(message.id);
+      waiter(message);
+    }
+  });
+  const opened = new Promise((resolve, reject) => {
+    socket.addEventListener('open', resolve, { once: true });
+    socket.addEventListener('error', reject, { once: true });
+  });
+  return {
+    async send(method, params = {}) {
+      await opened;
+      const id = nextId++;
+      const reply = new Promise((resolve) => pending.set(id, resolve));
+      socket.send(JSON.stringify({ id, method, params }));
+      const message = await reply;
+      if (message.error) {
+        throw new Error(`${method}: ${message.error.message}`);
+      }
+      return message.result;
+    },
+    close() {
+      socket.close();
+    },
+  };
+}
+
+async function openVersionTarget(port, deadline) {
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(
+        `http://127.0.0.1:${port}/json/new?chrome://version`,
+        { method: 'PUT' }
+      );
+      if (response.ok) {
+        return await response.json();
+      }
+    } catch {
+      // The DevTools HTTP server is not up yet.
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(`no DevTools endpoint on port ${port}`);
+}
+
+async function evaluateUntilReady(cdp, deadline) {
+  while (Date.now() < deadline) {
+    const { result } = await cdp.send('Runtime.evaluate', {
+      expression: READ_VERSION_PAGE,
+      returnByValue: true,
+    });
+    if (result?.value) {
+      return result.value;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error('chrome://version did not render');
+}
+
+/**
+ * Start `executablePath` with the reference command line plus a fixed
+ * debugging port and read chrome://version.
+ *
+ * @param {Object} options
+ * @param {string} options.executablePath
+ * @param {boolean} [options.headless=false]
+ * @param {number} [options.timeout=30000]
+ * @returns {Promise<{commandLine: string, version: string, executablePath: string}>}
+ */
+export async function readReferenceVersionPage({
+  executablePath,
+  headless = false,
+  timeout = 30_000,
+  start = startProcess,
+}) {
+  const userDataDir = await createTemporaryUserDataDir();
+  const port = await reserveLoopbackPort();
+  const child = start(
+    executablePath,
+    [
+      `--user-data-dir=${userDataDir}`,
+      `--remote-debugging-port=${port}`,
+      ...(headless ? ['--headless=new'] : []),
+      'about:blank',
+    ],
+    { killGrace: 3000 }
+  );
+  let cdp;
+  try {
+    const deadline = Date.now() + timeout;
+    const target = await openVersionTarget(port, deadline);
+    cdp = openCdpSocket(target.webSocketDebuggerUrl);
+    return await evaluateUntilReady(cdp, deadline);
+  } finally {
+    cdp?.close();
+    child.kill('SIGTERM');
+    await child.exited;
+    await removeUserDataDir(userDataDir);
+  }
+}

package/src/traces/bundle.js

@@ -58,6 +58,7 @@ export async function openTraceBundle(options = {}) {
 
   const eventsPath = path.join(root, TRACE_FILES.EVENTS);
   const eventsHandle = await fs.open(eventsPath, 'a', TRACE_FILE_MODE);
+  let closeEventsPromise;
 
   let written = 0;
   let sequence = 0;
@@ -69,6 +70,12 @@ export async function openTraceBundle(options = {}) {
   const counts = { checkpoints: 0, events: 0, mutationBatches: 0 };
   const problems = [];
 
+  /** Close the timeline exactly once, after every queued append. */
+  function closeEvents() {
+    closeEventsPromise ??= appendQueue.then(() => eventsHandle.close());
+    return closeEventsPromise;
+  }
+
   const fits = (bytes) =>
     bytes <= maxResourceBytes && written + bytes <= maxBundleBytes;
 
@@ -308,6 +315,8 @@ export async function openTraceBundle(options = {}) {
     writeMutations,
     writeArtifact,
     drop,
+    /** Close an unfinished bundle without manufacturing a manifest. */
+    abort: closeEvents,
     /**
      * Write the manifest and close the timeline.
      *
@@ -325,8 +334,7 @@ export async function openTraceBundle(options = {}) {
             : manifest.outcome,
       };
       // Anything a listener reported on its way out is still queued.
-      await appendQueue;
-      await eventsHandle.close();
+      await closeEvents();
       await fs.writeFile(
         path.join(root, TRACE_FILES.MANIFEST),
         `${JSON.stringify(finished, null, 2)}\n`,

package/src/traces/recorder.js

@@ -74,6 +74,18 @@ function normalizeEvents(events) {
   return [...new Set(events)];
 }
 
+/**
+ * Reject a malformed side export before the bundle opens any file handles.
+ *
+ * @param {Object|null} links - Optional Links Notation export options
+ * @returns {void}
+ */
+function validateLinksOptions(links) {
+  if (links && (typeof links.output !== 'string' || links.output === '')) {
+    throw new Error('trace links require an output path');
+  }
+}
+
 /**
  * Start recording a session.
  *
@@ -111,6 +123,10 @@ export async function startTrace(options = {}) {
   }
   const eventSources = normalizeEvents(events);
   const privacyOptions = normalizePrivacyOptions(privacy);
+  // Validate the optional side export before opening the authoritative bundle.
+  // Otherwise a rejected start (for example `links: {}`) strands the bundle's
+  // events handle because no running trace is returned for the caller to stop.
+  validateLinksOptions(links);
   const engine = commander?.engine ?? null;
   const identity = createTraceIdentity({ page });
 
@@ -139,9 +155,6 @@ export async function startTrace(options = {}) {
   const startedAt = new Date(now()).toISOString();
 
   if (links) {
-    if (typeof links.output !== 'string' || links.output === '') {
-      throw new Error('trace links require an output path');
-    }
     linksSink = await openTraceLinks({
       output: links.output,
       include: links.include,

package/src/utilities/subprocess.js

@@ -0,0 +1,199 @@
+import { ProcessRunner } from 'command-stream/process-runner';
+
+/**
+ * Every subprocess Browser Commander starts - browsers, WebDriver servers, the
+ * engine bridge, credential tools (`security`, `secret-tool`, `kwallet-query`,
+ * `powershell.exe`, `icacls`, `whoami`) and the user's own browser opener -
+ * goes through command-stream (issue #104). Its `exec` mode runs the file
+ * directly with exact argv boundaries, no shell in between, and gives one
+ * consistent surface for streaming output, cancellation and exit codes. The
+ * Rust crate uses the `command-stream` crate and the Python package a
+ * `subprocess` wrapper with the same two functions.
+ *
+ * The lightweight `command-stream/process-runner` entry point is used so the
+ * optional PTY and terminal-rendering modules are never loaded.
+ */
+
+function runnerFor(file, args, { env, cwd, stdin = 'ignore', killGrace }) {
+  return new ProcessRunner(
+    { mode: 'exec', file, args },
+    {
+      mirror: false,
+      capture: true,
+      stdin,
+      ...(env ? { env } : {}),
+      ...(cwd ? { cwd } : {}),
+      ...(killGrace === undefined ? {} : { killGrace }),
+    }
+  );
+}
+
+/** Error raised when a command exits with a non-zero status. */
+export class CommandError extends Error {
+  constructor(file, args, result) {
+    const stderr = String(result.stderr ?? '').trim();
+    super(
+      `${file} exited with code ${result.code}${stderr ? `: ${stderr}` : ''}`
+    );
+    this.name = 'CommandError';
+    this.file = file;
+    this.args = args;
+    this.code = result.code;
+    this.exitCode = result.code;
+    this.stdout = String(result.stdout ?? '');
+    this.stderr = String(result.stderr ?? '');
+  }
+}
+
+/**
+ * Run a command to completion and return its output.
+ *
+ * @param {string} file - Executable to run (resolved through PATH)
+ * @param {string[]} [args] - Exact arguments
+ * @param {Object} [options]
+ * @param {Object<string,string>} [options.env] - Environment for the child only
+ * @param {string} [options.cwd] - Working directory
+ * @param {string|Buffer} [options.input] - Data written to the child's stdin
+ * @param {boolean} [options.check=true] - Throw {@link CommandError} on a non-zero exit
+ * @returns {Promise<{stdout: string, stderr: string, code: number}>}
+ */
+export async function runCommand(file, args = [], options = {}) {
+  const { env, cwd, input, check = true } = options;
+  const runner = runnerFor(file, args, {
+    env,
+    cwd,
+    stdin: input === undefined ? 'ignore' : input,
+  });
+  let result;
+  try {
+    result = await runner;
+  } catch (error) {
+    // A missing executable fails the spawn itself; report it like execFile.
+    if (error && error.code === undefined) {
+      error.code = 'ENOENT';
+    }
+    throw error;
+  }
+  const normalized = {
+    stdout: String(result.stdout ?? ''),
+    stderr: String(result.stderr ?? ''),
+    code: result.code,
+  };
+  if (check && normalized.code !== 0) {
+    throw new CommandError(file, args, normalized);
+  }
+  return normalized;
+}
+
+/**
+ * Start a long-running process, such as a browser or a driver server.
+ *
+ * The returned handle has the part of the `ChildProcess` surface the launchers
+ * rely on (`pid`, `exitCode`, `kill()`, `stderr`/`stdout` `data` events and an
+ * `exit` event), plus an `exited` promise.
+ *
+ * @param {string} file - Executable path
+ * @param {string[]} args - Exact arguments
+ * @param {Object} [options]
+ * @param {Object<string,string>} [options.env] - Environment for the child only
+ * @param {boolean} [options.forwardOutput=false] - Mirror the child's output to this process
+ * @param {number} [options.killGrace=2000] - Milliseconds between SIGTERM and SIGKILL
+ * @returns {ManagedProcess}
+ */
+export function startProcess(file, args = [], options = {}) {
+  const { env, cwd, forwardOutput = false, killGrace = 2000 } = options;
+  const runner = runnerFor(file, args, { env, cwd, killGrace });
+  return new ManagedProcess(runner, { forwardOutput });
+}
+
+class OutputChannel {
+  constructor() {
+    this.listeners = new Set();
+  }
+
+  on(event, listener) {
+    if (event === 'data') {
+      this.listeners.add(listener);
+    }
+    return this;
+  }
+
+  off(event, listener) {
+    this.listeners.delete(listener);
+    return this;
+  }
+
+  emit(chunk) {
+    for (const listener of this.listeners) {
+      listener(chunk);
+    }
+  }
+}
+
+/** Handle for a process started by {@link startProcess}. */
+export class ManagedProcess {
+  constructor(runner, { forwardOutput }) {
+    this.runner = runner;
+    this.exitCode = null;
+    this.signalCode = null;
+    this.stdout = new OutputChannel();
+    this.stderr = new OutputChannel();
+    this.exitListeners = new Set();
+    runner.on('stdout', (chunk) => {
+      if (forwardOutput) {
+        process.stdout.write(chunk);
+      }
+      this.stdout.emit(chunk);
+    });
+    runner.on('stderr', (chunk) => {
+      if (forwardOutput) {
+        process.stderr.write(chunk);
+      }
+      this.stderr.emit(chunk);
+    });
+    runner.start();
+    this.exited = Promise.resolve(runner)
+      .catch((error) => ({ code: error?.code ?? 1 }))
+      .then((result) => {
+        this.exitCode = typeof result.code === 'number' ? result.code : 1;
+        for (const listener of this.exitListeners) {
+          listener(this.exitCode);
+        }
+        return this.exitCode;
+      });
+  }
+
+  /** Operating system process id, once spawned. */
+  get pid() {
+    return this.runner.pid;
+  }
+
+  on(event, listener) {
+    if (event === 'exit') {
+      if (this.exitCode !== null) {
+        listener(this.exitCode);
+      } else {
+        this.exitListeners.add(listener);
+      }
+    }
+    return this;
+  }
+
+  once(event, listener) {
+    return this.on(event, listener);
+  }
+
+  /**
+   * Stop the process: the signal first, then SIGKILL after the grace period.
+   *
+   * @param {string} [signal='SIGTERM']
+   * @returns {boolean} Whether a running process was signalled
+   */
+  kill(signal) {
+    if (this.exitCode !== null) {
+      return false;
+    }
+    this.runner.kill(signal);
+    return true;
+  }
+}

package/tests/e2e/api-coverage.e2e.test.js

@@ -0,0 +1,174 @@
+/**
+ * API coverage of the generic handle methods (issue #104).
+ *
+ * `serve --stdio` promises that any public Playwright or Puppeteer method can
+ * be called through `handle.call`, so the Rust and Python ports need no
+ * binding per method. This suite walks the real engine objects through the
+ * same dispatcher `serve` uses and asserts that `handle.describe` lists every
+ * method the engine declares for that type:
+ *
+ * - Puppeteer: `puppeteer-core/lib/types.d.ts`.
+ * - Playwright: `playwright-core/types/types.d.ts`. Playwright's wire
+ *   protocol description (`protocol.yml`) is not shipped in the npm
+ *   package, so the published client API declarations are the reference.
+ *
+ * When an engine upgrade adds a method, the declarations grow and this test
+ * shows whether the bridge reaches it.
+ *
+ * Run with: npm run test:e2e:api-coverage
+ */
+import { after, before, describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import { createDispatcher } from '../../src/cli/dispatcher.js';
+import {
+  playwrightDeclarations,
+  puppeteerDeclarations,
+} from '../helpers/declared-api.js';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
+import { sendHtml, startFixtureHost } from '../helpers/fixture-server.js';
+
+const E2E = { skip: !process.env.RUN_E2E, timeout: 180_000 };
+
+const PAGE = `<!doctype html><title>API coverage</title>
+<p id="text">coverage</p><iframe srcdoc="<p>inner</p>"></iframe>`;
+
+/**
+ * How to reach one declared type from the session roots. Each step is
+ * `['call', method, args]` or `['get', property]`, run with handle.call or
+ * handle.get on the previous handle; `from` names the starting handle.
+ */
+/** Page-level types both engines expose the same way, under their own names. */
+function sharedPaths({ response, request }) {
+  return {
+    Browser: { from: 'browser', steps: [] },
+    BrowserContext: { from: 'context', steps: [] },
+    Page: { from: 'page', steps: [] },
+    [response]: { from: 'page', steps: [['call', 'goto', ['$url']]] },
+    [request]: {
+      from: 'page',
+      steps: [
+        ['call', 'goto', ['$url']],
+        ['call', 'request', []],
+      ],
+    },
+    Frame: { from: 'page', steps: [['call', 'mainFrame', []]] },
+    ElementHandle: { from: 'page', steps: [['call', '$', ['#text']]] },
+    JSHandle: {
+      from: 'page',
+      steps: [['call', 'evaluateHandle', [{ $function: '() => window' }]]],
+    },
+    Locator: { from: 'page', steps: [['call', 'locator', ['#text']]] },
+    Keyboard: { from: 'page', steps: [['get', 'keyboard']] },
+    Mouse: { from: 'page', steps: [['get', 'mouse']] },
+    Touchscreen: { from: 'page', steps: [['get', 'touchscreen']] },
+    Coverage: { from: 'page', steps: [['get', 'coverage']] },
+  };
+}
+
+const PLAYWRIGHT_PATHS = {
+  ...sharedPaths({ response: 'Response', request: 'Request' }),
+  FrameLocator: { from: 'page', steps: [['call', 'frameLocator', ['iframe']]] },
+  Clock: { from: 'page', steps: [['get', 'clock']] },
+  APIRequestContext: { from: 'page', steps: [['get', 'request']] },
+  Tracing: { from: 'context', steps: [['get', 'tracing']] },
+  CDPSession: {
+    from: 'context',
+    steps: [['call', 'newCDPSession', ['$page']]],
+  },
+  BrowserType: { from: 'engine', steps: [['get', 'chromium']] },
+  APIRequest: { from: 'engine', steps: [['get', 'request']] },
+  Selectors: { from: 'engine', steps: [['get', 'selectors']] },
+};
+
+const PUPPETEER_PATHS = {
+  ...sharedPaths({ response: 'HTTPResponse', request: 'HTTPRequest' }),
+  PuppeteerNode: { from: 'engine', steps: [] },
+  Accessibility: { from: 'page', steps: [['get', 'accessibility']] },
+  Tracing: { from: 'page', steps: [['get', 'tracing']] },
+  Target: { from: 'page', steps: [['call', 'target', []]] },
+  CDPSession: { from: 'page', steps: [['call', 'createCDPSession', []]] },
+};
+
+const ENGINES = {
+  playwright: { paths: PLAYWRIGHT_PATHS, declarations: playwrightDeclarations },
+  puppeteer: { paths: PUPPETEER_PATHS, declarations: puppeteerDeclarations },
+};
+
+/** Follow one path from the session roots to a handle. */
+async function reach(dispatch, roots, { from, steps }, url) {
+  const substitute = (arg) =>
+    arg === '$url' ? url : arg === '$page' ? roots.page : arg;
+  let handle = roots[from];
+  for (const [kind, name, args = []] of steps) {
+    handle =
+      kind === 'get'
+        ? await dispatch('handle.get', { handle, property: name })
+        : await dispatch('handle.call', {
+            handle,
+            method: name,
+            args: args.map(substitute),
+          });
+  }
+  return handle;
+}
+
+for (const [engine, { paths, declarations }] of Object.entries(ENGINES)) {
+  describe(`E2E - handle.describe covers the ${engine} API (issue #104)`, () => {
+    let server;
+    let dispatcher;
+    let roots;
+
+    before(async () => {
+      if (!process.env.RUN_E2E) {
+        return;
+      }
+      server = await startFixtureHost((_path, _req, res) =>
+        sendHtml(res, PAGE)
+      );
+      dispatcher = createDispatcher();
+      const { session } = await dispatcher.dispatch('session.launch', {
+        engine,
+        headless: true,
+        ...CHROME_LAUNCH_OPTIONS,
+      });
+      roots = {
+        ...(await dispatcher.dispatch('handle.root', {
+          name: `session:${session}`,
+        })),
+        engine: await dispatcher.dispatch('handle.root', { name: engine }),
+      };
+    });
+
+    after(async () => {
+      await dispatcher?.close();
+      await server?.close();
+    });
+
+    it('every mapped type is still declared by the engine', E2E, () => {
+      const declared = declarations();
+      const missing = Object.keys(paths).filter((type) => !declared.has(type));
+      assert.deepEqual(missing, []);
+    });
+
+    for (const type of Object.keys(paths)) {
+      it(`${type}: every declared method is reachable`, E2E, async () => {
+        const { dispatch } = dispatcher;
+        const handle = await reach(
+          dispatch,
+          roots,
+          paths[type],
+          server.baseUrl
+        );
+        assert.ok(handle?.$handle, `${type} did not resolve to a handle`);
+
+        const described = await dispatch('handle.describe', { handle });
+        const available = new Set(described.methods);
+        const missing = [...declarations().get(type)].filter(
+          (method) => !available.has(method)
+        );
+        assert.deepEqual(missing, [], `${type} (${described.type})`);
+      });
+    }
+  });
+}