browser-commander 0.32.1 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.33.0
+
+### Minor Changes
+
+- 60fcdc4: Launches without `channel` or `executablePath` start Chrome for Testing (the one Playwright or Puppeteer downloaded, else the newest build in its download cache; Selenium tries the Playwright and Puppeteer caches, then Selenium Manager) instead of the installed Google Chrome, which is used only on request and never as a silent fallback (#179). A Chrome for Testing launch gets the new `chrome-for-testing` restriction preset by default: `no-chrome-for-testing-infobar` (`--test-type=gpu`) and `mock-keychain` (`--use-mock-keychain`); `defaultRestrictions` changes it. New exports: `isChromeForTesting`, `defaultRestrictionsFor`, `CHROME_FOR_TESTING_RESTRICTIONS`.
+
+  Trace checkpoint screenshots and default screenshots of pages without a fixed viewport use CDP `Page.captureScreenshot` without a clip, so a headful window resized during a capture keeps its real size (#180).
+
 ## 0.32.1
 
 ### Patch Changes

package/README.md

@@ -390,8 +390,8 @@ see [trace and session hardening](https://github.com/link-foundation/browser-com
 ```javascript
 const { browser, page, close } = await launchBrowser({
   engine: 'playwright', // 'playwright' or 'puppeteer'
-  launch: 'real', // 'real' (start the installed browser, attach) or 'engine'
-  channel: 'chrome', // or executablePath; defaults to the installed Chrome
+  launch: 'real', // 'real' (start the browser itself, attach) or 'engine'
+  channel: 'chrome', // or executablePath; default: Chrome for Testing
   headless: false, // Run in headless mode
   userDataDir: undefined, // Keep a profile; default is a fresh temporary one
   restrictions: [], // Opt-in restrictions such as 'no-extensions', 'no-sync'
@@ -410,6 +410,47 @@ browser and deletes a temporary profile. The result also carries `launch`,
 `userDataDir`, `temporaryProfile` and the exact `args` the browser was started
 with.
 
+#### Chrome for Testing by default
+
+Without `channel` or `executablePath`, a launch starts Chrome for Testing - the
+one Playwright or Puppeteer downloaded, or else another build in its download
+cache (`ms-playwright`, moved by `PLAYWRIGHT_BROWSERS_PATH`; `~/.cache/puppeteer`,
+moved by `PUPPETEER_CACHE_DIR`), newest first; Selenium tries both caches, then
+Selenium Manager's - never your own Google Chrome. Chrome for Testing is an app of
+its own (`com.google.chrome.for.testing` on macOS), so the Dock icon, new tabs
+and links opened from other apps keep going to your Chrome. Without it the
+launch fails and names the install command (`npx playwright install chromium`,
+`npx puppeteer browsers install chrome`) and `channel: 'chrome'`, which starts
+the installed Google Chrome instead. It is never a silent fallback.
+
+A Chrome for Testing launch gets the `chrome-for-testing` restriction preset
+before your own `restrictions`: `no-chrome-for-testing-infobar`
+(`--test-type=gpu`, the only value that hides the "Chrome for Testing is only
+for automated testing" bar) and `mock-keychain` (`--use-mock-keychain`, no
+keychain prompt at each start). Other browsers get nothing. `defaultRestrictions`
+replaces that choice (`[]` opts out) and the result reports what was applied:
+
+```javascript
+import { isChromeForTesting, launchBrowser } from 'browser-commander';
+
+const { defaultRestrictions, close } = await launchBrowser({});
+console.log(defaultRestrictions); // ['no-chrome-for-testing-infobar', 'mock-keychain']
+await close();
+
+// Keep the infobar, or start Google Chrome on purpose:
+await launchBrowser({ defaultRestrictions: [] });
+await launchBrowser({ channel: 'chrome' });
+isChromeForTesting(
+  '/home/me/.cache/ms-playwright/chromium-1248/chrome-linux64/chrome'
+); // true
+```
+
+`launchRealBrowser()` and `launchWebDriver()` take the same
+`defaultRestrictions`. With the mock keychain, Chrome for Testing cannot decrypt
+cookies another Chrome wrote into a copied profile; move logins with
+`readBrowserCookies()` or `storageState`, which set cookies through the
+browser's cookie API instead.
+
 The `args` option allows passing custom Chrome arguments, which is useful for headless server environments (Docker, CI/CD) that require flags like `--no-sandbox`.
 
 The `storageState` option accepts a Playwright-compatible JSON path or object.
@@ -439,11 +480,13 @@ Playwright accepts `timeout` and Puppeteer accepts `protocolTimeout`.
 
 ### launchRealBrowser(options)
 
-Start an installed browser and connect through `connectBrowser()`. Use
+Start a browser and connect through `connectBrowser()`. Without `channel` or
+`executablePath` it starts Chrome for Testing, as `launchBrowser()` does; use
 `channel` (`chrome`, `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge`,
 `msedge-beta`, `msedge-dev`, `msedge-canary`, `brave`, or `chromium`) or an
-explicit `executablePath`. Without `userDataDir` it creates a fresh temporary
-profile that `close()` deletes; it rejects known default browser-profile paths,
+explicit `executablePath` for an installed browser. Without `userDataDir` it
+creates a fresh temporary profile that `close()` deletes; it rejects known
+default browser-profile paths,
 protects its remote-debugging switches, reserves a loopback port (or uses
 `remoteDebuggingPort`, never `0`), and returns the spawned `browserProcess`,
 `cdpEndpoint`, `remoteDebuggingPort`, `executablePath`, `userDataDir`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "description": "Universal browser automation library that supports Playwright, Puppeteer, and Selenium with a unified API",
   "main": "src/index.js",
   "bin": {

package/src/browser/chrome-for-testing-cache.js

@@ -0,0 +1,198 @@
+import { readdirSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Finding Chrome for Testing in the download caches (issue #179).
+ *
+ * The engine's own `executablePath()` names one exact build; when that build
+ * is not installed, a launch still starts another Chrome for Testing the
+ * Playwright, Puppeteer or Selenium Manager caches hold, newest version
+ * first. Mirrors `CacheLocations` in `rust/src/browser/chrome_for_testing.rs`.
+ */
+
+/** The caches each engine finds Chrome for Testing in, in order. */
+export const ENGINE_CACHES = Object.freeze({
+  playwright: ['playwright'],
+  puppeteer: ['puppeteer'],
+  selenium: ['playwright', 'puppeteer', 'selenium'],
+});
+
+// name: archive and Selenium cache platform; puppeteer: Puppeteer's prefix.
+const PLATFORMS = {
+  'linux-x64': { name: 'linux64', puppeteer: 'linux' },
+  'darwin-x64': { name: 'mac-x64', puppeteer: 'mac' },
+  'darwin-arm64': { name: 'mac-arm64', puppeteer: 'mac_arm' },
+  'win32-x64': { name: 'win64', puppeteer: 'win64' },
+  'win32-ia32': { name: 'win32', puppeteer: 'win32' },
+};
+
+/**
+ * Where the caches are on this machine, or `undefined` where Chrome for
+ * Testing is not built for the platform.
+ *
+ * @param {Object} [machine]
+ * @param {string} [machine.platform] - `process.platform`
+ * @param {string} [machine.arch] - `process.arch`
+ * @param {string} [machine.home] - The home directory
+ * @param {Object} [machine.env] - The environment variables
+ */
+export function cacheLocations({
+  platform = process.platform,
+  arch = process.arch,
+  home = os.homedir(),
+  env = process.env,
+} = {}) {
+  const known = PLATFORMS[platformKey(platform, arch)];
+  return known ? { platform, ...known, home, env } : undefined;
+}
+
+function platformKey(platform, arch) {
+  if (platform === 'darwin') {
+    return arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64';
+  }
+  if (platform === 'win32') {
+    return arch === 'ia32' ? 'win32-ia32' : 'win32-x64';
+  }
+  return `${platform}-${arch}`;
+}
+
+function variable(locations, name) {
+  return locations.env[name] || undefined;
+}
+
+function homePath(locations, ...relative) {
+  return locations.home ? path.join(locations.home, ...relative) : undefined;
+}
+
+const ROOTS = {
+  playwright(locations) {
+    const root = locations.env.PLAYWRIGHT_BROWSERS_PATH;
+    if (root) {
+      // `0` keeps the browsers inside node_modules, where only the
+      // Playwright package itself knows the path.
+      return root === '0' ? undefined : root;
+    }
+    if (locations.platform === 'win32') {
+      const local = variable(locations, 'LOCALAPPDATA');
+      return local && path.join(local, 'ms-playwright');
+    }
+    if (locations.platform === 'darwin') {
+      return homePath(locations, 'Library', 'Caches', 'ms-playwright');
+    }
+    const cache = variable(locations, 'XDG_CACHE_HOME');
+    return cache
+      ? path.join(cache, 'ms-playwright')
+      : homePath(locations, '.cache', 'ms-playwright');
+  },
+  puppeteer: (locations) =>
+    variable(locations, 'PUPPETEER_CACHE_DIR') ??
+    homePath(locations, '.cache', 'puppeteer'),
+  selenium: (locations) =>
+    variable(locations, 'SE_CACHE_PATH') ??
+    homePath(locations, '.cache', 'selenium'),
+};
+
+/** The binary inside an unpacked Chrome for Testing directory. */
+function binary(locations) {
+  if (locations.platform === 'darwin') {
+    return path.join(
+      'Google Chrome for Testing.app',
+      'Contents',
+      'MacOS',
+      'Google Chrome for Testing'
+    );
+  }
+  return locations.platform === 'win32' ? 'chrome.exe' : 'chrome';
+}
+
+/** A dotted version (`131.0.6778.204`) or revision (`1248`) as numbers. */
+function versionKey(text) {
+  return text !== undefined && /^\d+(\.\d+)*$/u.test(text)
+    ? text.split('.').map(Number)
+    : undefined;
+}
+
+function compareVersions(left, right) {
+  for (let index = 0; index < Math.max(left.length, right.length); index++) {
+    const difference = (left[index] ?? -1) - (right[index] ?? -1);
+    if (difference !== 0) {
+      return difference;
+    }
+  }
+  return 0;
+}
+
+function isDirectory(file) {
+  try {
+    return statSync(file).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** The directories in `root` whose name `key` parses, newest first. */
+function newestFirst(root, key) {
+  let names;
+  try {
+    names = readdirSync(root);
+  } catch {
+    return [];
+  }
+  return names
+    .map((name) => ({ version: key(name), directory: path.join(root, name) }))
+    .filter(({ version, directory }) => version && isDirectory(directory))
+    .sort((left, right) => compareVersions(right.version, left.version))
+    .map(({ directory }) => directory);
+}
+
+const withPrefix = (prefix) => (name) =>
+  name.startsWith(prefix) ? versionKey(name.slice(prefix.length)) : undefined;
+
+/**
+ * The Chrome for Testing binaries `cache` may hold, newest version first.
+ * The paths are candidates: the caller checks they exist.
+ *
+ * @param {'playwright'|'puppeteer'|'selenium'} cache
+ * @param {Object} locations - From {@link cacheLocations}
+ * @returns {string[]}
+ */
+export function chromeForTestingCandidates(cache, locations) {
+  const root = ROOTS[cache](locations);
+  if (!root) {
+    return [];
+  }
+  const archive = `chrome-${locations.name}`;
+  const file = binary(locations);
+  if (cache === 'selenium') {
+    return newestFirst(
+      path.join(root, 'chrome', locations.name),
+      versionKey
+    ).map((directory) => path.join(directory, file));
+  }
+  const directories =
+    cache === 'playwright'
+      ? newestFirst(root, withPrefix('chromium-'))
+      : newestFirst(
+          path.join(root, 'chrome'),
+          withPrefix(`${locations.puppeteer}-`)
+        );
+  return directories.map((directory) => path.join(directory, archive, file));
+}
+
+/**
+ * The Chrome for Testing candidates in the caches `engine` uses, in order.
+ *
+ * @param {string} engine
+ * @param {Object} [machine] - See {@link cacheLocations}
+ * @returns {string[]}
+ */
+export function cachedChromeForTesting(engine, machine) {
+  const locations = cacheLocations(machine);
+  if (!locations) {
+    return [];
+  }
+  return (ENGINE_CACHES[engine] ?? []).flatMap((cache) =>
+    chromeForTestingCandidates(cache, locations)
+  );
+}

package/src/browser/launch-executable.js

@@ -0,0 +1,203 @@
+import { constants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { cachedChromeForTesting } from './chrome-for-testing-cache.js';
+import { LAUNCH_RESTRICTION_PRESETS } from './restrictions.js';
+import { resolveSystemBrowserExecutable } from './system-browser.js';
+
+/**
+ * Which browser binary an automation launch starts (issue #179).
+ *
+ * Without `channel` or `executablePath` a launch starts Chrome for Testing,
+ * the browser Playwright and Puppeteer download. It is an application of its
+ * own (`com.google.chrome.for.testing` on macOS), so the user's Google Chrome
+ * - its Dock icon, its new tabs, the links other apps open - never goes to the
+ * automation window. The installed Google Chrome is used only on request.
+ */
+
+/** Load the browser launcher of each engine that downloads a browser. */
+export const ENGINE_BROWSERS = Object.freeze({
+  playwright: async () => (await import('playwright')).chromium,
+  puppeteer: async () => (await import('puppeteer')).default,
+});
+
+// Selenium has no browser of its own; it starts the one Playwright or
+// Puppeteer downloaded, then the one Selenium Manager keeps.
+const BUNDLED_BROWSER_ENGINES = {
+  playwright: ['playwright'],
+  puppeteer: ['puppeteer'],
+  selenium: ['playwright', 'puppeteer'],
+};
+
+const PLAYWRIGHT_INSTALL = 'npx playwright install chromium';
+const PUPPETEER_INSTALL = 'npx puppeteer browsers install chrome';
+const INSTALL_COMMANDS = {
+  playwright: [PLAYWRIGHT_INSTALL],
+  puppeteer: [PUPPETEER_INSTALL],
+  selenium: [
+    PLAYWRIGHT_INSTALL,
+    PUPPETEER_INSTALL,
+    'selenium-manager --browser chrome --force-browser-download',
+  ],
+};
+
+// Chrome for Testing archives unpack to chrome-<platform>; the macOS app is
+// "Google Chrome for Testing.app". Playwright's older own Chromium builds
+// (chrome-linux, chrome-win, Chromium.app) are not Chrome for Testing.
+const CHROME_FOR_TESTING_DIRECTORIES = new Set([
+  'chrome-linux64',
+  'chrome-win64',
+  'chrome-win32',
+  'chrome-mac-x64',
+  'chrome-mac-arm64',
+]);
+const SELENIUM_CACHE_PLATFORMS = new Set([
+  'linux64',
+  'win64',
+  'win32',
+  'mac-x64',
+  'mac-arm64',
+]);
+
+/** The restrictions every Chrome for Testing launch gets by default. */
+export const CHROME_FOR_TESTING_RESTRICTIONS =
+  LAUNCH_RESTRICTION_PRESETS['chrome-for-testing'];
+
+/**
+ * Whether an executable is a Chrome for Testing build, judged by its install
+ * path: Playwright, Puppeteer, `@puppeteer/browsers` and Selenium Manager all
+ * keep it under a Chrome for Testing archive directory.
+ *
+ * @param {string} [executablePath]
+ * @returns {boolean}
+ */
+export function isChromeForTesting(executablePath) {
+  if (typeof executablePath !== 'string') {
+    return false;
+  }
+  const segments = executablePath.toLowerCase().split(/[\\/]+/u);
+  if (
+    segments.some(
+      (segment) =>
+        segment.includes('chrome for testing') ||
+        CHROME_FOR_TESTING_DIRECTORIES.has(segment)
+    )
+  ) {
+    return true;
+  }
+  // Selenium Manager: ~/.cache/selenium/chrome/<platform>/<version>/chrome
+  const selenium = segments.lastIndexOf('selenium');
+  return (
+    selenium >= 0 &&
+    segments[selenium + 1] === 'chrome' &&
+    SELENIUM_CACHE_PLATFORMS.has(segments[selenium + 2])
+  );
+}
+
+/**
+ * The restrictions a launch of `executablePath` gets unless the caller sets
+ * `defaultRestrictions`: the `chrome-for-testing` preset for Chrome for
+ * Testing, nothing for any other browser.
+ *
+ * @param {string} executablePath
+ * @param {string[]} [requested] - The caller's `defaultRestrictions`
+ * @returns {string[]}
+ */
+export function defaultRestrictionsFor(executablePath, requested) {
+  if (requested !== undefined) {
+    return requested;
+  }
+  return isChromeForTesting(executablePath)
+    ? [...CHROME_FOR_TESTING_RESTRICTIONS]
+    : [];
+}
+
+async function isExecutable(file) {
+  try {
+    await access(file, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The Chrome for Testing Selenium Manager keeps in `~/.cache/selenium`,
+ * downloaded when missing. `--force-browser-download` stops it from picking
+ * the installed Google Chrome instead.
+ *
+ * @returns {Promise<string|undefined>}
+ */
+export async function seleniumManagerChromeForTesting() {
+  // Imported here: webdriver.js imports this module.
+  const { seleniumManagerPath } = await import('./webdriver.js');
+  const { runCommand } = await import('../utilities/subprocess.js');
+  const { stdout, code } = await runCommand(
+    seleniumManagerPath(),
+    ['--browser', 'chrome', '--force-browser-download', '--output', 'json'],
+    { check: false }
+  );
+  return code === 0 ? JSON.parse(stdout)?.result?.browser_path : undefined;
+}
+
+async function existingExecutable(find) {
+  const executable = await Promise.resolve()
+    .then(find)
+    .catch(() => undefined);
+  return executable && (await isExecutable(executable))
+    ? executable
+    : undefined;
+}
+
+/**
+ * Pick the browser binary for a launch.
+ *
+ * An explicit `executablePath` or `channel` is honoured as given. Without
+ * either, the engine's downloaded Chrome for Testing is started, then any
+ * other build in its download cache, newest first; Selenium uses Playwright's,
+ * then Puppeteer's, then the cached ones, then Selenium Manager's. The
+ * installed Google Chrome is never a silent fallback: without Chrome for
+ * Testing the launch fails and says how to install it or how to ask for
+ * Google Chrome.
+ */
+export async function resolveLaunchExecutable(
+  { engine, channel, executablePath },
+  {
+    resolveSystem = resolveSystemBrowserExecutable,
+    loadEngineModule,
+    seleniumManagerBrowser = seleniumManagerChromeForTesting,
+    cachedBrowsers = cachedChromeForTesting,
+  } = {}
+) {
+  if (executablePath !== undefined || channel !== undefined) {
+    return await resolveSystem({
+      channel: channel ?? 'chrome',
+      executablePath,
+    });
+  }
+  const engines = BUNDLED_BROWSER_ENGINES[engine] ?? [];
+  const loaders = loadEngineModule
+    ? [loadEngineModule]
+    : engines.map((name) => ENGINE_BROWSERS[name]);
+  const finders = loaders.map(
+    (load) => async () => (await load()).executablePath()
+  );
+  const cached = await Promise.resolve()
+    .then(() => cachedBrowsers(engine))
+    .catch(() => []);
+  finders.push(...cached.map((executable) => () => executable));
+  if (engine === 'selenium') {
+    finders.push(seleniumManagerBrowser);
+  }
+  for (const find of finders) {
+    const executable = await existingExecutable(find);
+    if (executable) {
+      return executable;
+    }
+  }
+  const install = (INSTALL_COMMANDS[engine] ?? [])
+    .map((command) => `\`${command}\``)
+    .join(' or ');
+  throw new Error(
+    `Chrome for Testing is not installed for ${engine}: run ${install}, or pass channel: 'chrome' to start the installed Google Chrome`
+  );
+}

package/src/browser/launch-restrictions.json

@@ -32,9 +32,14 @@
     },
     {
       "id": "mock-keychain",
-      "description": "Use a mock macOS Keychain. Real-profile data cannot be decrypted or migrated.",
+      "description": "Use a mock macOS Keychain. Real-profile data cannot be decrypted or migrated. Added by default for Chrome for Testing, which otherwise asks for its keychain entry at each start.",
       "args": ["--use-mock-keychain"]
     },
+    {
+      "id": "no-chrome-for-testing-infobar",
+      "description": "Hide the \"Chrome for Testing is only for automated testing\" bar; Chromium skips it only for --test-type=gpu, which also skips the unsupported-flag and other startup infobars. Added by default for Chrome for Testing.",
+      "args": ["--test-type=gpu"]
+    },
     {
       "id": "no-extensions",
       "description": "Disable extensions, component extensions with background pages and default apps.",
@@ -167,6 +172,7 @@
       "no-google-services",
       "no-translate"
     ],
+    "chrome-for-testing": ["no-chrome-for-testing-infobar", "mock-keychain"],
     "quiet-ui": [
       "no-first-run",
       "no-default-browser-check",