browser-commander 0.20.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/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})`);
+      });
+    }
+  });
+}

package/tests/e2e/cli.e2e.test.js

@@ -0,0 +1,160 @@
+/**
+ * Real-browser tests of the `browser-commander` CLI (issue #104).
+ *
+ * The binary runs as a separate process through command-stream, the way a
+ * shell script, a Rust program or a Python program would use it:
+ *
+ * - `run tests/cli-contract/basic.json` must print, after normalization,
+ *   exactly `tests/cli-contract/basic.expected.json`. The Rust and Python
+ *   CLIs are checked against the same file, so all three agree.
+ * - `launch --keep-open` leaves a browser running that later `goto` and
+ *   `eval` commands reach with `--cdp-endpoint`.
+ *
+ * Run with: npm run test:e2e:cli
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { ProcessRunner } from 'command-stream/process-runner';
+
+import { normalizeRunOutput } from '../../../tests/cli-contract/normalize.mjs';
+import { runCommand } from '../../src/utilities/subprocess.js';
+import { SANDBOX_ARGS } from '../helpers/e2e-browser.js';
+import { repoPath } from '../helpers/repo.js';
+
+const BIN = fileURLToPath(
+  new URL('../../bin/browser-commander.js', import.meta.url)
+);
+const ENGINES = ['playwright', 'puppeteer'];
+const E2E = { skip: !process.env.RUN_E2E, timeout: 180_000 };
+
+/** Options that pick the test browser: CHROME_PATH and sandbox arguments. */
+function browserOptions(engine) {
+  return [
+    '--engine',
+    engine,
+    ...(process.env.CHROME_PATH
+      ? ['--executable-path', process.env.CHROME_PATH]
+      : []),
+    // "--arg=VALUE": a value that starts with "--" cannot follow a space.
+    ...SANDBOX_ARGS.map((arg) => `--arg=${arg}`),
+  ];
+}
+
+/** Run the CLI to completion and parse its one JSON document. */
+async function browserCommander(args) {
+  const { code, stdout, stderr } = await runCommand(
+    process.execPath,
+    [BIN, ...args],
+    { check: false }
+  );
+  let document;
+  try {
+    document = JSON.parse(stdout);
+  } catch {
+    throw new Error(`No JSON from ${args.join(' ')}: ${stdout}\n${stderr}`);
+  }
+  return { code, document };
+}
+
+/**
+ * Start `launch --keep-open` with stdin kept open, and resolve with its
+ * document once it has been printed.
+ */
+function startKeptOpenBrowser(engine) {
+  const runner = new ProcessRunner(
+    {
+      mode: 'exec',
+      file: process.execPath,
+      args: [
+        BIN,
+        'launch',
+        '--keep-open',
+        '--headless',
+        ...browserOptions(engine),
+      ],
+    },
+    { mirror: false, capture: true, stdin: 'pipe' }
+  );
+  let output = '';
+  const printed = new Promise((resolve, reject) => {
+    runner.on('stdout', (chunk) => {
+      output += chunk.toString();
+      if (output.includes('\n')) {
+        resolve(JSON.parse(output.split('\n')[0]));
+      }
+    });
+    Promise.resolve(runner).then(
+      (result) =>
+        reject(new Error(`launch exited early: ${output}${result.stderr}`)),
+      reject
+    );
+  });
+  runner.start();
+  return { runner, printed };
+}
+
+for (const engine of ENGINES) {
+  describe(`E2E - browser-commander CLI with ${engine} (issue #104)`, () => {
+    it(
+      'run basic.json matches the cross-language expected output',
+      E2E,
+      async () => {
+        const { code, document } = await browserCommander([
+          'run',
+          repoPath('tests', 'cli-contract', 'basic.json'),
+          ...browserOptions(engine),
+        ]);
+
+        const expected = JSON.parse(
+          readFileSync(
+            repoPath('tests', 'cli-contract', 'basic.expected.json'),
+            'utf8'
+          )
+        );
+        assert.deepEqual(normalizeRunOutput(document), expected);
+        assert.equal(code, 0);
+      }
+    );
+
+    it(
+      'launch --keep-open serves goto and eval over --cdp-endpoint',
+      E2E,
+      async () => {
+        const { runner, printed } = startKeptOpenBrowser(engine);
+        try {
+          const launched = await printed;
+          assert.match(launched.cdpEndpoint, /^http:\/\/127\.0\.0\.1:\d+$/u);
+          const attach = [
+            '--cdp-endpoint',
+            launched.cdpEndpoint,
+            '--engine',
+            engine,
+          ];
+
+          const url = `data:text/html,${encodeURIComponent(
+            '<title>Kept open</title><p id="x">42</p>'
+          )}`;
+          const goto = await browserCommander(['goto', url, ...attach]);
+          assert.equal(goto.code, 0);
+          assert.deepEqual(goto.document, { url, title: 'Kept open' });
+
+          // The second command attaches again and sees the page the first
+          // one left behind: the browser outlived both commands.
+          const evaluated = await browserCommander([
+            'eval',
+            "document.title + ':' + document.querySelector('#x').textContent",
+            ...attach,
+          ]);
+          assert.equal(evaluated.code, 0);
+          assert.deepEqual(evaluated.document, { value: 'Kept open:42' });
+        } finally {
+          runner.kill('SIGTERM');
+          await Promise.resolve(runner).catch(() => {});
+        }
+      }
+    );
+  });
+}