browser-commander 0.20.0 → 0.21.0

package/src/browser/parity.js

@@ -0,0 +1,439 @@
+/**
+ * Measure how far a browser Browser Commander drives is from the same browser
+ * started by hand (issue #103).
+ *
+ * Three things are compared, because each can give automation away on its
+ * own:
+ * - the command line, as the browser itself reports it on chrome://version,
+ *   against the one a person would type (`--user-data-dir` and, headless,
+ *   `--headless=new`);
+ * - the feature state the command line sets (`--enable-features`,
+ *   `--disable-features`, `--disable-blink-features`, ...);
+ * - everything a page can read, through the environment probe that also backs
+ *   the parity e2e suite.
+ *
+ * Every difference is either explained by an entry in the shared limitations
+ * catalogue, explained by an option the caller asked for, or unlisted. A
+ * report with unlisted differences is not `ok`; `browser-commander doctor`
+ * exits non-zero on it and CI fails.
+ */
+import { randomUUID } from 'node:crypto';
+
+import {
+  captureReferenceReport,
+  diffReports,
+  readProbeSource,
+  startProbeServer,
+} from '../parity/harness.js';
+import { readReferenceVersionPage } from '../parity/version-page.js';
+import { findFingerprintLimitation } from '../fingerprint/limitations.js';
+
+/**
+ * Switches whose value is different on every launch by construction. Their
+ * presence is compared; their value is not.
+ */
+const VOLATILE_SWITCHES = new Set(['--user-data-dir']);
+
+/**
+ * Markers Chrome itself writes around the switches it took from chrome://flags.
+ * A hand-started browser shows them too.
+ */
+const CHROME_MARKERS = new Set([
+  '--flag-switches-begin',
+  '--flag-switches-end',
+]);
+
+/** Switches that carry a comma-separated feature list. */
+const FEATURE_SWITCHES = new Set([
+  '--enable-features',
+  '--disable-features',
+  '--enable-blink-features',
+  '--disable-blink-features',
+]);
+
+/**
+ * The debugging port is how the library attaches. Issue #101 measured that a
+ * fixed non-zero port changes nothing a page can observe, so it is reported
+ * as the attachment rather than as a difference.
+ */
+const ATTACHMENT_SWITCHES = new Set(['--remote-debugging-port']);
+
+const URL_WORD = /^[a-z][a-z0-9+.-]*:/iu;
+
+/**
+ * Regroup whitespace-separated words into switches: a word starting with `--`
+ * starts a switch, any other word continues the previous one's value. The
+ * start URL, when there is one, is the last word and is dropped.
+ */
+function joinSwitchWords(words) {
+  const last = words.at(-1) ?? '';
+  if (words.length > 1 && !last.startsWith('--') && URL_WORD.test(last)) {
+    words.pop();
+  }
+  const tokens = [];
+  for (const word of words) {
+    if (word.startsWith('--') || tokens.length === 0) {
+      tokens.push(word);
+    } else {
+      tokens[tokens.length - 1] += ` ${word}`;
+    }
+  }
+  return tokens;
+}
+
+/**
+ * Split a command line into `--switch[=value]` entries.
+ *
+ * chrome://version prints the command line joined with spaces, so a value
+ * containing a space (a profile path, say) cannot be recovered exactly. Every
+ * `--` that follows whitespace starts a new switch; the executable and any
+ * trailing URL are not switches and are dropped.
+ *
+ * @param {string|string[]} commandLine
+ * @returns {Map<string, string|null>} switch name to value (`null` for a flag)
+ */
+export function parseSwitches(commandLine) {
+  const tokens = Array.isArray(commandLine)
+    ? commandLine
+    : joinSwitchWords(String(commandLine).trim().split(/\s+/u));
+  const switches = new Map();
+  for (const token of tokens) {
+    if (!token.startsWith('--')) {
+      continue;
+    }
+    const separator = token.indexOf('=');
+    if (separator === -1) {
+      switches.set(token, null);
+    } else {
+      switches.set(token.slice(0, separator), token.slice(separator + 1));
+    }
+  }
+  return switches;
+}
+
+function featureList(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .sort();
+}
+
+/**
+ * Compare the command line the browser reports with the reference one.
+ *
+ * @param {string[]} reference - Arguments the hand-started browser received
+ * @param {string|string[]} candidate - chrome://version command line
+ * @returns {{extra: string[], missing: string[], changed: Object[], attachment: string[], features: Object}}
+ */
+export function compareCommandLines(reference, candidate) {
+  const left = parseSwitches(reference);
+  const right = parseSwitches(candidate);
+  const extra = [];
+  const missing = [];
+  const changed = [];
+  const attachment = [];
+  const features = {};
+  const names = new Set([...left.keys(), ...right.keys()]);
+  for (const name of [...names].sort()) {
+    if (CHROME_MARKERS.has(name)) {
+      continue;
+    }
+    if (ATTACHMENT_SWITCHES.has(name)) {
+      if (right.has(name)) {
+        attachment.push(`${name}=${right.get(name)}`);
+      }
+      continue;
+    }
+    const format = (map) =>
+      map.get(name) === null ? name : `${name}=${map.get(name)}`;
+    if (!left.has(name)) {
+      extra.push(format(right));
+    } else if (!right.has(name)) {
+      missing.push(format(left));
+    } else if (
+      !VOLATILE_SWITCHES.has(name) &&
+      left.get(name) !== right.get(name)
+    ) {
+      changed.push({
+        name,
+        reference: left.get(name),
+        candidate: right.get(name),
+      });
+    }
+    if (FEATURE_SWITCHES.has(name)) {
+      features[name] = {
+        reference: featureList(left.get(name)),
+        candidate: featureList(right.get(name)),
+      };
+    }
+  }
+  return { extra, missing, changed, attachment, features };
+}
+
+function commandLineDifferences(comparison) {
+  return [
+    ...comparison.extra.map((entry) => ({
+      path: `commandLine.extra.${entry.split('=')[0]}`,
+      reference: null,
+      candidate: entry,
+    })),
+    ...comparison.missing.map((entry) => ({
+      path: `commandLine.missing.${entry.split('=')[0]}`,
+      reference: entry,
+      candidate: null,
+    })),
+    ...comparison.changed.map(({ name, reference, candidate }) => ({
+      path: `commandLine.changed.${name}`,
+      reference,
+      candidate,
+    })),
+  ];
+}
+
+// Switches that change which Blink features and field trials are active. A
+// non-Chrome-branded build (Chromium) applies its testing field-trial config
+// unless told otherwise, so Playwright's --disable-field-trial-config alone
+// changes the API surface (the Protected Audience methods on navigator) and
+// the language list on Chromium, while Chrome and Edge are unaffected.
+const FEATURE_CONFIG_SWITCHES = new Set([
+  '--disable-field-trial-config',
+  '--disable-features',
+  '--enable-features',
+]);
+
+// Surfaces those switches are measured to move: which properties an object
+// exposes, and the reduced or full Accept-Language list.
+const FEATURE_CONFIG_SURFACES = /(?:^|\.)(?:keys|languages)$/u;
+
+function changesFeatureConfig(extraSwitches = []) {
+  return extraSwitches.some((entry) =>
+    FEATURE_CONFIG_SWITCHES.has(entry.split('=')[0])
+  );
+}
+
+/**
+ * Explain a difference: a limitation id, `requested` for a switch the caller
+ * asked for (or that follows from an option they set), or `null`.
+ */
+export function explainDifference(difference, context) {
+  const { path } = difference;
+  if (path.startsWith('commandLine.')) {
+    const value = String(difference.candidate ?? difference.reference ?? '');
+    if (context.requestedArgs.some((arg) => arg === value)) {
+      return { requested: true };
+    }
+    if (context.launch === 'engine') {
+      return { limitation: 'engine-launch-switches' };
+    }
+    return {};
+  }
+  if (
+    context.launch === 'engine' &&
+    FEATURE_CONFIG_SURFACES.test(path) &&
+    changesFeatureConfig(context.extraSwitches)
+  ) {
+    return { limitation: 'engine-launch-switches' };
+  }
+  if (path.startsWith('navigator.userAgentData.brands')) {
+    return { limitation: 'grease-brand-not-reproduced' };
+  }
+  if (path === 'navigator.webdriver' && context.attached) {
+    return { limitation: 'automation-controlled-is-launch-only' };
+  }
+  return {};
+}
+
+/**
+ * Tag every difference with its explanation and split out the unlisted ones.
+ *
+ * @param {Object[]} differences - `{path, reference, candidate}` entries
+ * @param {Object} context
+ * @returns {{differences: Object[], unlisted: Object[]}}
+ */
+export function classifyDifferences(differences, context) {
+  const tagged = differences.map((difference) => {
+    const explanation = explainDifference(difference, context);
+    const limitation =
+      explanation.limitation &&
+      findFingerprintLimitation(explanation.limitation)
+        ? explanation.limitation
+        : null;
+    return {
+      path: difference.path,
+      expected: difference.reference ?? null,
+      actual: difference.candidate ?? null,
+      limitation,
+      requested: explanation.requested === true,
+    };
+  });
+  return {
+    differences: tagged,
+    unlisted: tagged.filter((entry) => !entry.limitation && !entry.requested),
+  };
+}
+
+/**
+ * Read the browser's own view of itself from chrome://version in a new tab,
+ * so the page under measurement is left where it was.
+ *
+ * @param {Object} page - A Playwright or Puppeteer page of the browser
+ * @returns {Promise<{commandLine: string, version: string, executablePath: string}>}
+ */
+export async function readBrowserVersionPage(page) {
+  const opener =
+    typeof page.context === 'function' ? page.context() : page.browser();
+  const versionPage = await opener.newPage();
+  try {
+    await versionPage.goto('chrome://version');
+    return await versionPage.evaluate(() => {
+      const text = (id) =>
+        (document.getElementById(id)?.textContent ?? '').trim();
+      return {
+        commandLine: text('command_line'),
+        version: text('version'),
+        executablePath: text('executable_path'),
+      };
+    });
+  } finally {
+    await versionPage.close().catch(() => {});
+  }
+}
+
+async function captureCandidate(session, server, readVersionPage) {
+  const token = randomUUID();
+  await session.page.goto(server.url(token), { waitUntil: 'load' });
+  const report = await server.waitForReport(token);
+  const versionPage = await readVersionPage(session.page);
+  return { report, versionPage };
+}
+
+function normalizeWhitespace(text) {
+  return String(text ?? '')
+    .replace(/\s+/gu, ' ')
+    .trim();
+}
+
+function requestedArgsFor(session, options) {
+  const requested = [...(options.args ?? []), ...(options.extraArgs ?? [])];
+  const launchedArgs = session.args ?? [];
+  if ((options.restrictions ?? []).length > 0) {
+    requested.push(
+      ...launchedArgs.filter(
+        (arg) =>
+          !arg.startsWith('--user-data-dir') &&
+          !arg.startsWith('--remote-debugging-port')
+      )
+    );
+  }
+  return requested;
+}
+
+/**
+ * Measure a launched (or about-to-be-launched) browser against the same
+ * binary started by hand.
+ *
+ * @param {Object} [options] - Launch options for {@link launchBrowser} (engine,
+ *   channel, executablePath, headless, launch, restrictions, args, ...)
+ * @param {Object} [options.session] - Measure this already-launched session
+ *   (the result of `launchBrowser`/`launchRealBrowser`) instead of launching
+ * @param {boolean} [options.attached=false] - The session was started by
+ *   somebody else and only connected to
+ * @param {Object} [dependencies] - Test seams
+ * @returns {Promise<Object>} The parity report described in docs/cli-and-bridge.md
+ */
+export async function measureParity(options = {}, dependencies = {}) {
+  const {
+    session: providedSession,
+    attached = false,
+    headless = false,
+    ...launchOptions
+  } = options;
+  const {
+    launchBrowser = (await import('./launcher.js')).launchBrowser,
+    resolveLaunchExecutable = (await import('./launcher.js'))
+      .resolveLaunchExecutable,
+    startServer = startProbeServer,
+    readProbe = readProbeSource,
+    captureReference = captureReferenceReport,
+    readVersionPage = readBrowserVersionPage,
+    readReferenceVersion = readReferenceVersionPage,
+  } = dependencies;
+
+  const engine = launchOptions.engine ?? 'playwright';
+  const executablePath =
+    providedSession?.executablePath ??
+    (await resolveLaunchExecutable({
+      engine,
+      channel: launchOptions.channel,
+      executablePath: launchOptions.executablePath,
+    }));
+  const server = await startServer(await readProbe());
+  try {
+    const reference = await captureReference({
+      executablePath,
+      server,
+      token: randomUUID(),
+      headless,
+    });
+    // The browser appends switches of its own (`--ozone-platform=...`, and
+    // several more headless), so the reference command line is what the same
+    // binary reports for the argv a person types, not that argv.
+    const referenceVersionPage = await readReferenceVersion({
+      executablePath,
+      headless,
+    });
+    const session =
+      providedSession ??
+      (await launchBrowser({
+        ...launchOptions,
+        engine,
+        executablePath,
+        headless,
+      }));
+    let candidate;
+    try {
+      candidate = await captureCandidate(session, server, readVersionPage);
+    } finally {
+      if (!providedSession) {
+        await session.browser.close();
+      }
+    }
+    const launch = session.launch ?? launchOptions.launch ?? 'real';
+    const commandLine = compareCommandLines(
+      referenceVersionPage.commandLine,
+      candidate.versionPage.commandLine
+    );
+    const { differences, unlisted } = classifyDifferences(
+      [
+        ...commandLineDifferences(commandLine),
+        ...diffReports(reference, candidate.report),
+      ],
+      {
+        launch,
+        attached,
+        extraSwitches: commandLine.extra,
+        requestedArgs: requestedArgsFor(session, { ...options, headless }),
+      }
+    );
+    return {
+      browser: {
+        executablePath,
+        version: normalizeWhitespace(candidate.versionPage.version),
+        engine,
+        launch,
+        headless,
+      },
+      commandLine: {
+        launched: candidate.versionPage.commandLine,
+        reference: referenceVersionPage.commandLine,
+        ...commandLine,
+      },
+      differences,
+      unlisted,
+      ok: unlisted.length === 0,
+    };
+  } finally {
+    await server.close();
+  }
+}

package/src/browser/profile-directory.js

@@ -0,0 +1,102 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Chrome skips its first-run experience when this file exists in the user
+ * data directory; it is what Chrome itself writes after the first run.
+ * Writing it keeps `--no-first-run` off the command line (issue #103), and it
+ * is required for a headful launch at all: without it the first-run dialog
+ * holds startup and the DevTools endpoint never appears (measured with Chrome
+ * 153, experiments/issue-105/headful-first-run.mjs).
+ */
+export const FIRST_RUN_SENTINEL = 'First Run';
+
+/** Chrome's profile-wide settings file, next to the profile directories. */
+export const LOCAL_STATE_FILE = 'Local State';
+
+/**
+ * Local State written into a brand-new user data directory.
+ *
+ * With only the First Run sentinel, Chrome treats a new directory like a
+ * browser that was just updated and opens a "What's new" tab next to the New
+ * Tab page, a moment after startup (measured with Chrome 153,
+ * experiments/issue-105/whats-new-local-state.mjs). That second tab takes the
+ * foreground after the engine has attached, so the tab being driven would
+ * report `document.hidden === true`. Chrome records the milestone it last
+ * showed What's New for in `browser.last_whats_new_version` and skips the tab
+ * when it is not older than the running version; a milestone no release has
+ * reached keeps the tab closed without asking the binary for its version.
+ *
+ * Microsoft Edge ignores both and opens its own first-run tab,
+ * `edge://welcome-edge/`, which takes the foreground the same way; it is
+ * skipped once Edge has recorded `fre.has_user_seen_fre` (measured with Edge
+ * 153, experiments/issue-103/edge-first-run.sh). Chrome ignores the key.
+ */
+export const INITIAL_LOCAL_STATE = Object.freeze({
+  browser: Object.freeze({ last_whats_new_version: 9999 }),
+  fre: Object.freeze({ has_user_seen_fre: true }),
+});
+
+/** Prefix of the fresh profiles Browser Commander creates and deletes. */
+export const TEMPORARY_PROFILE_PREFIX = 'browser-commander-profile-';
+
+/**
+ * Make sure a user data directory exists and has the First Run sentinel.
+ *
+ * An existing sentinel is left alone, so a profile Chrome already used keeps
+ * its timestamp, and Local State is only written when Chrome has not written
+ * one yet.
+ *
+ * @param {string} userDataDir
+ * @returns {Promise<string>} The same directory
+ */
+export async function prepareUserDataDir(userDataDir) {
+  await mkdir(userDataDir, { recursive: true });
+  await writeFile(path.join(userDataDir, FIRST_RUN_SENTINEL), '', {
+    flag: 'a',
+  });
+  try {
+    await writeFile(
+      path.join(userDataDir, LOCAL_STATE_FILE),
+      JSON.stringify(INITIAL_LOCAL_STATE),
+      { flag: 'wx' }
+    );
+  } catch (error) {
+    if (error.code !== 'EEXIST') {
+      throw error;
+    }
+  }
+  return userDataDir;
+}
+
+/**
+ * Create a fresh, empty profile for one launch.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.parent=os.tmpdir()] - Directory to create it in
+ * @returns {Promise<string>} Path of the new user data directory
+ */
+export async function createTemporaryUserDataDir({
+  parent = os.tmpdir(),
+} = {}) {
+  const userDataDir = await mkdtemp(
+    path.join(parent, TEMPORARY_PROFILE_PREFIX)
+  );
+  return await prepareUserDataDir(userDataDir);
+}
+
+/**
+ * Delete a temporary profile. Chrome can still be flushing files for a moment
+ * after its process exits, so removal is retried.
+ *
+ * @param {string} userDataDir
+ */
+export async function removeUserDataDir(userDataDir) {
+  await rm(userDataDir, {
+    recursive: true,
+    force: true,
+    maxRetries: 5,
+    retryDelay: 200,
+  });
+}