browser-commander 0.32.1 → 0.33.0

package/src/browser/launcher.js

@@ -1,4 +1,3 @@
-import { access } from 'node:fs/promises';
 import { launchFailure } from './launch-diagnostics.js';
 import {
   installSessionPersistence,
@@ -20,9 +19,13 @@ import {
   configureUserDataDir,
   removeUserDataDir,
 } from './profile-directory.js';
+import {
+  ENGINE_BROWSERS,
+  defaultRestrictionsFor,
+  resolveLaunchExecutable,
+} from './launch-executable.js';
 import { launchRealBrowser } from './real-browser.js';
 import { resolveRestrictions } from './restrictions.js';
-import { resolveSystemBrowserExecutable } from './system-browser.js';
 import { applyFingerprint } from '../fingerprint/apply.js';
 import { attachDownloads } from '../downloads/attach.js';
 import { launchWebDriver } from './webdriver.js';
@@ -36,14 +39,11 @@ import {
 } from './storage-state.js';
 import { interruptionMode } from '../utilities/subprocess.js';
 
+export { resolveLaunchExecutable };
+
 /** How `launchBrowser` starts the browser (issue #103). */
 export const LAUNCH_MODES = Object.freeze(['real', 'engine']);
 
-const loadEngine = {
-  playwright: async () => (await import('playwright')).chromium,
-  puppeteer: async () => (await import('puppeteer')).default,
-};
-
 function validateLaunchMode({ engine, launch, attach }) {
   assertSupportedEngine(engine);
   if (!LAUNCH_MODES.includes(launch)) {
@@ -58,48 +58,6 @@ function validateLaunchMode({ engine, launch, attach }) {
   }
 }
 
-async function isExecutable(file) {
-  try {
-    await access(file);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Pick the browser binary for a real launch.
- *
- * An explicit `executablePath` or `channel` is honoured as given. Without
- * either, the installed Google Chrome is preferred - it is the browser a
- * person would start - and the engine's own downloaded Chromium is the
- * fallback, so a machine with only `npx playwright install` still works. The
- * binary is spawned by Browser Commander either way, with the same clean
- * command line.
- */
-export async function resolveLaunchExecutable(
-  { engine, channel, executablePath },
-  { resolveSystem = resolveSystemBrowserExecutable, loadEngineModule } = {}
-) {
-  if (executablePath !== undefined || channel !== undefined) {
-    return await resolveSystem({
-      channel: channel ?? 'chrome',
-      executablePath,
-    });
-  }
-  try {
-    return await resolveSystem({ channel: 'chrome' });
-  } catch (error) {
-    const bundled = await (loadEngineModule ?? loadEngine[engine])()
-      .then((module) => module.executablePath())
-      .catch(() => undefined);
-    if (bundled && (await isExecutable(bundled))) {
-      return bundled;
-    }
-    throw error;
-  }
-}
-
 async function launchReal(options, dependencies) {
   const {
     engine,
@@ -144,14 +102,47 @@ async function launchReal(options, dependencies) {
   return { browser, page, close, connectedBrowser, ...meta };
 }
 
+// The Chrome for Testing an engine launch starts on its own, or the one a
+// Selenium launch is pointed at; undefined for any installed browser.
+async function engineExecutable(
+  { engine, browser = 'chrome', channel, executablePath },
+  engineModule,
+  dependencies
+) {
+  if (executablePath !== undefined || channel !== undefined) {
+    return executablePath;
+  }
+  if (engine === 'selenium') {
+    // Without Chrome for Testing this fails rather than let the driver pick
+    // the installed Google Chrome (issue #179).
+    return browser === 'chrome'
+      ? await resolveLaunchExecutable({ engine }, dependencies)
+      : undefined;
+  }
+  return await Promise.resolve()
+    .then(() => engineModule.executablePath?.())
+    .catch(() => undefined);
+}
+
 async function launchWithEngine(options, dependencies) {
   if (options.engine === 'selenium') {
+    // launchWebDriver adds the defaults of the browser it resolves.
+    const executablePath = await engineExecutable(options, null, dependencies);
     const launched = await (dependencies.launchWebDriver ?? launchWebDriver)({
       ...options,
+      ...(executablePath ? { executablePath } : {}),
       args: [...options.args, ...options.extraArgs],
     });
     return { ...launched, browser: launched.driver };
   }
+  const engineModule = await (
+    dependencies.loadEngineModule ?? ENGINE_BROWSERS[options.engine]
+  )();
+  const defaultRestrictions = defaultRestrictionsFor(
+    await engineExecutable(options, engineModule, dependencies),
+    options.defaultRestrictions
+  );
+  const restrictions = [...defaultRestrictions, ...options.restrictions];
   const {
     engine,
     userDataDir: requestedUserDataDir,
@@ -160,7 +151,6 @@ async function launchWithEngine(options, dependencies) {
     args,
     extraArgs,
     ignoreDefaultArgs,
-    restrictions,
     env,
     colorScheme,
     channel,
@@ -195,9 +185,6 @@ async function launchWithEngine(options, dependencies) {
     },
     localState: options.localState,
   });
-  const engineModule = await (
-    dependencies.loadEngineModule ?? loadEngine[engine]
-  )();
   const selection = { channel, executablePath };
 
   let browser;
@@ -263,6 +250,7 @@ async function launchWithEngine(options, dependencies) {
     userDataDir,
     temporaryProfile,
     args: chrome.args,
+    defaultRestrictions,
   };
 }
 
@@ -285,13 +273,20 @@ async function unfocusAddressBar(page, verbose, settleMs = 500) {
 /**
  * Launch a browser.
  *
- * By default (`launch: 'real'`) Browser Commander starts the installed Chrome
- * itself, exactly like a person who wants to attach a debugger would:
+ * By default (`launch: 'real'`) Browser Commander starts Chrome itself,
+ * exactly like a person who wants to attach a debugger would:
  * `--user-data-dir=<fresh temporary profile> --remote-debugging-port=<reserved
  * port>` and nothing else, then attaches the engine over CDP (issues #101 and
  * #103). The profile is deleted on close. Every restriction the library used
  * to add silently is an explicit opt-in through `restrictions`.
  *
+ * The browser is the engine's Chrome for Testing, an application of its own,
+ * so the user's Google Chrome is never taken over; `channel: 'chrome'` asks
+ * for the installed Google Chrome. Chrome for Testing gets the
+ * `chrome-for-testing` restrictions (`--test-type=gpu`, the only switch that
+ * hides its "only for automated testing" bar, and `--use-mock-keychain`)
+ * unless `defaultRestrictions` says otherwise (issue #179).
+ *
  * `launch: 'engine'` keeps the Playwright/Puppeteer-launched browser for CI
  * and headless use; the switches those engines add are listed in
  * limitations.json (`engine-launch-switches`).
@@ -304,12 +299,13 @@ async function unfocusAddressBar(page, verbose, settleMs = 500) {
  * @param {number} [options.slowMo=0] - Slow down operations by ms
  * @param {boolean} [options.verbose=false] - Enable verbose logging
  * @param {string[]} [options.restrictions] - Opt-in restrictions from launch-restrictions.json, such as 'no-extensions' or the 'legacy-defaults' preset
+ * @param {string[]} [options.defaultRestrictions] - Restrictions that replace the executable's defaults (the 'chrome-for-testing' preset for Chrome for Testing, none otherwise); [] turns them off
  * @param {string[]} [options.args] - Additional Chrome arguments
  * @param {string[]} [options.extraArgs] - Additional Chrome arguments appended after args
  * @param {boolean|string[]} [options.ignoreDefaultArgs] - Engine default switches to omit, or true for all ('engine' launch only)
  * @param {Object<string,string>} [options.env] - Extra environment for the browser process only
  * @param {string|null} [options.colorScheme] - Emulate color scheme: 'light', 'dark', 'no-preference', or null to reset
- * @param {string} [options.channel] - Installed browser channel, such as 'chrome', 'chrome-beta', 'msedge', 'brave' or 'chromium'
+ * @param {string} [options.channel] - Installed browser channel, such as 'chrome', 'chrome-beta', 'msedge', 'brave' or 'chromium'; without it (and without executablePath) the engine's Chrome for Testing is started
  * @param {string} [options.executablePath] - Explicit path to a Chrome or Chromium executable
  * @param {number} [options.remoteDebuggingPort] - Fixed CDP port for the real launch; a free one is reserved when omitted
  * @param {string|Object} [options.storageState] - Playwright-compatible storage state path or object
@@ -317,7 +313,7 @@ async function unfocusAddressBar(page, verbose, settleMs = 500) {
  * @param {boolean} [options.automationParity=true] - Keep navigator.webdriver false where a launch switch would turn it on (headless or engine launches)
  * @param {boolean|Object} [options.downloads] - Manage downloads: true for defaults, or {directory, persist, conflict}. The directory may be an absolute path, 'user-downloads' or 'temporary'.
  * @param {boolean|Object} [options.debug=false] - Opt-in recording: true, {output}, or {directory, retain, maxDurationMs, limits} for managed storage
- * @returns {Promise<{browser: Object, page: Object, downloads: (Object|null), close: function(): Promise<void>, launch: string, userDataDir: string, temporaryProfile: boolean, args: Array<string>}>} Browser (a BrowserContext for Playwright), page, download manager and launch metadata
+ * @returns {Promise<{browser: Object, page: Object, downloads: (Object|null), close: function(): Promise<void>, launch: string, userDataDir: string, temporaryProfile: boolean, args: Array<string>, defaultRestrictions: Array<string>}>} Browser (a BrowserContext for Playwright), page, download manager and launch metadata
  */
 export async function launchBrowser(options = {}) {
   return await launchBrowserWithDependencies(options);
@@ -368,6 +364,23 @@ export async function launchBrowserWithDependencies(
   }
 }
 
+function validateSeleniumLaunch({
+  launch,
+  browser,
+  colorScheme,
+  fingerprint,
+  downloads,
+}) {
+  if (colorScheme !== undefined || fingerprint !== undefined || downloads) {
+    throw new Error(
+      'selenium does not support CDP emulation, fingerprint overrides or managed downloads (webdriver-no-cdp-emulation)'
+    );
+  }
+  if (launch === 'real' && browser === 'firefox') {
+    throw new Error("selenium Firefox requires launch: 'engine'");
+  }
+}
+
 async function launchNonSafariBrowser(options, dependencies) {
   const {
     engine = 'playwright',
@@ -388,16 +401,16 @@ async function launchNonSafariBrowser(options, dependencies) {
   } = options;
   validateLaunchMode({ engine, launch, attach: rest.attach });
   if (engine === 'selenium') {
-    if (colorScheme !== undefined || fingerprint !== undefined || downloads) {
-      throw new Error(
-        'selenium does not support CDP emulation, fingerprint overrides or managed downloads (webdriver-no-cdp-emulation)'
-      );
-    }
-    if (launch === 'real' && rest.browser === 'firefox') {
-      throw new Error("selenium Firefox requires launch: 'engine'");
-    }
+    validateSeleniumLaunch({
+      launch,
+      colorScheme,
+      fingerprint,
+      downloads,
+      ...rest,
+    });
   }
   // Validate arguments before anything is started or written to disk.
+  resolveRestrictions(rest.defaultRestrictions ?? []);
   resolveChromeArgs({
     args,
     extraArgs,

package/src/browser/parity.js

@@ -317,7 +317,12 @@ function normalizeWhitespace(text) {
 function requestedArgsFor(session, options) {
   const requested = [...(options.args ?? []), ...(options.extraArgs ?? [])];
   const launchedArgs = session.args ?? [];
-  if ((options.restrictions ?? []).length > 0) {
+  // Chrome for Testing's default restrictions are requested too (issue #179).
+  const restrictions = [
+    ...(session.defaultRestrictions ?? []),
+    ...(options.restrictions ?? []),
+  ];
+  if (restrictions.length > 0) {
     requested.push(
       ...launchedArgs.filter(
         (arg) =>

package/src/browser/real-browser.js

@@ -48,6 +48,10 @@ import {
   knownDefaultUserDataDirs,
   resolveSystemBrowserExecutable,
 } from './system-browser.js';
+import {
+  defaultRestrictionsFor,
+  resolveLaunchExecutable,
+} from './launch-executable.js';
 
 /**
  * Switches the launcher owns. Letting a caller pass them would break the
@@ -375,22 +379,25 @@ function driverInterruption(engine, interruption) {
 }
 
 /**
- * Spawn a genuine installed Chrome-family browser with a dedicated profile,
- * wait for its loopback CDP endpoint, and attach through {@link connectBrowser}.
+ * Spawn a Chrome-family browser with a dedicated profile, wait for its
+ * loopback CDP endpoint, and attach through {@link connectBrowser}.
  *
  * The command line is `--user-data-dir=<dir> --remote-debugging-port=<port>`
  * and nothing else unless asked for, so the session is as close to a
  * hand-started browser as CDP allows and `navigator.webdriver` is false.
+ * Without `channel`, `executablePath` or `attach` the engine's Chrome for
+ * Testing is started, with the `chrome-for-testing` restrictions (issue #179).
  *
  * @param {Object} options - Launch and connection options
  * @param {'playwright'|'puppeteer'} [options.engine='playwright'] - Automation engine
- * @param {string} [options.channel='chrome'] - Installed Chrome-family channel
+ * @param {string} [options.channel] - Installed Chrome-family channel, such as 'chrome' for the installed Google Chrome; it also names the browser a snapshot or migration belongs to (default 'chrome')
  * @param {string} [options.executablePath] - Explicit installed browser executable
  * @param {string} [options.userDataDir] - Persistent dedicated profile. When omitted a fresh temporary profile is created and deleted on close.
  * @param {number} [options.remoteDebuggingPort] - Fixed loopback CDP port. When omitted a free port is reserved (and re-reserved on a port race). Zero is refused because it sets navigator.webdriver.
  * @param {number} [options.portAttempts=3] - Launch attempts when a reserved port is lost to a race
  * @param {boolean} [options.headless=false] - Run the installed browser headlessly
  * @param {string[]} [options.restrictions] - Opt-in restrictions from launch-restrictions.json, such as 'no-extensions'
+ * @param {string[]} [options.defaultRestrictions] - Restrictions that replace the executable's defaults: the 'chrome-for-testing' preset for Chrome for Testing, none for any other browser. Pass [] to start Chrome for Testing without them.
  * @param {string[]} [options.args] - Additional browser arguments
  * @param {string[]} [options.extraArgs] - Additional browser arguments appended after args
  * @param {boolean} [options.defaultBrowserCheck=false] - Allow the disposable browser to ask to become the default
@@ -404,7 +411,7 @@ function driverInterruption(engine, interruption) {
  * @param {{browser: string, profile: (string|undefined), userDataDir: (string|undefined), include: (Array<string>|undefined), domains: (Array<string>|undefined)}} [options.migrateFrom] - Migrate a real browser profile into the dedicated profile before launch; on-disk data is written before the browser starts and cookies are seeded over CDP after connecting
  * @param {{mode: 'snapshot', browser: (string|undefined), profile: (string|undefined), userDataDir: (string|undefined)}} [options.attach] - Launch on a read-only snapshot of a real profile (issue #102, addendum): `snapshotUserDataDir()` copies it into a temporary user data directory, which is deleted on close. `browser` defaults to the channel's browser and `profile` to Default. Mutually exclusive with `migrateFrom` and `userDataDir`.
  * @param {boolean} [options.verbose=false] - Show browser and connection logs
- * @returns {Promise<{browser: Object, page: Object, downloads: (Object|null), close: function(): Promise<void>, browserProcess: Object, cdpEndpoint: string, remoteDebuggingPort: number, executablePath: string, userDataDir: string, temporaryProfile: boolean, args: Array<string>, migration: (Object|undefined), attach: ({mode: 'snapshot', snapshot: Object, differences: Array<{aspect: string, description: string}>}|undefined)}>} Connected handles and process metadata (with a `migration` report when `migrateFrom` was given and an `attach` entry when `attach` was given)
+ * @returns {Promise<{browser: Object, page: Object, downloads: (Object|null), close: function(): Promise<void>, browserProcess: Object, cdpEndpoint: string, remoteDebuggingPort: number, executablePath: string, userDataDir: string, temporaryProfile: boolean, args: Array<string>, defaultRestrictions: Array<string>, migration: (Object|undefined), attach: ({mode: 'snapshot', snapshot: Object, differences: Array<{aspect: string, description: string}>}|undefined)}>} Connected handles and process metadata (with a `migration` report when `migrateFrom` was given and an `attach` entry when `attach` was given)
  */
 export async function launchAndConnectRealBrowser(options = {}) {
   return await launchAndConnectRealBrowserWithDependencies(options);
@@ -662,6 +669,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
     portAttempts = 3,
     headless = false,
     restrictions = [],
+    defaultRestrictions: requestedDefaultRestrictions,
     args = [],
     extraArgs = [],
     ignoreDefaultArgs: _ignoredLegacyDefaults,
@@ -699,14 +707,17 @@ export async function launchAndConnectRealBrowserWithDependencies(
     attach,
     migrateFrom,
   });
+  resolveRestrictions(requestedDefaultRestrictions ?? []);
 
+  // Without a channel, executablePath or attach the engine's Chrome for
+  // Testing is started, never the user's Google Chrome (issue #179).
   const resolveExecutable =
-    dependencies.resolveExecutable ?? resolveSystemBrowserExecutable;
-  const launchChannel = attach?.browser ?? channel;
+    dependencies.resolveExecutable ??
+    ((request) => resolveLaunchExecutable({ engine, ...request }));
   const executablePath = await Promise.resolve()
     .then(() =>
       resolveExecutable({
-        channel: launchChannel,
+        channel: attach?.browser ?? options.channel,
         executablePath: requestedExecutablePath,
       })
     )
@@ -718,6 +729,14 @@ export async function launchAndConnectRealBrowserWithDependencies(
         executablePath: requestedExecutablePath,
       });
     });
+  // Chrome for Testing gets its infobar hidden and a mock keychain unless the
+  // caller sets defaultRestrictions; the snapshot keystore warning, the
+  // environment and the profile preferences all see them.
+  const defaultRestrictions = defaultRestrictionsFor(
+    executablePath,
+    requestedDefaultRestrictions
+  );
+  argOptions.restrictions = [...defaultRestrictions, ...restrictions];
 
   const temporaryProfile = !requestedUserDataDir;
   const { userDataDir, snapshotLaunch } = await prepareProfile({
@@ -728,7 +747,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
     snapshot: dependencies.snapshotUserDataDir,
     firstRun,
   });
-  const childEnv = browserEnvironment(restrictions, env);
+  const childEnv = browserEnvironment(argOptions.restrictions, env);
 
   const { migration, migratedCookies } = await runPreLaunchMigration({
     migrateFrom,
@@ -745,7 +764,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
     configureUserDataDir(userDataDir, {
       defaultBrowserCheck,
       preferences: {
-        ...resolveRestrictions(restrictions).preferences,
+        ...resolveRestrictions(argOptions.restrictions).preferences,
         ...preferences,
       },
       localState,
@@ -814,6 +833,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
         userDataDir,
         temporaryProfile,
         args: launched.browserArgs,
+        defaultRestrictions,
         ...(migration ? { migration } : {}),
         ...(snapshotLaunch ? { attach: snapshotLaunch.attach } : {}),
       },

package/src/browser/webdriver.js

@@ -42,6 +42,7 @@ import {
 } from './profile-directory.js';
 import { buildRealBrowserArgs } from './real-browser.js';
 import { resolveRestrictions } from './restrictions.js';
+import { defaultRestrictionsFor } from './launch-executable.js';
 import { findBrowserSource } from './browser-sources.js';
 import {
   isSafariChannel,
@@ -480,13 +481,14 @@ async function teardown({
  * @param {boolean} [options.bidi=false] - Enable WebDriver BiDi (events, preload scripts, full-page screenshots)
  * @param {string[]} [options.args] - Extra browser arguments
  * @param {string[]} [options.restrictions] - Chrome launch restrictions (launch-restrictions.json)
+ * @param {string[]} [options.defaultRestrictions] - Restrictions that replace the browser's defaults (the 'chrome-for-testing' preset for Chrome for Testing, none otherwise); [] turns them off
  * @param {boolean} [options.automationParity=true] - Keep navigator.webdriver false in headless Chrome
  * @param {Object<string,string>} [options.env] - Extra environment for the driver and browser
  * @param {number} [options.startupTimeout=30000]
  * @param {boolean} [options.verbose=false] - Mirror the driver server's output
  * @param {'managed'|'caller'} [options.interruption='managed'] - Who handles Ctrl+C for the driver server and the browser under it; see `startProcess`
  * @param {Object} [dependencies] - Injected selenium modules, runCommand, startProcess, fetch, reservePort, environment, platform (tests)
- * @returns {Promise<{driver: Object, page: Object, close: function(): Promise<void>, serverUrl: string, driverProcess: Object, driverPath: string, driverSource: string, browser: string, userDataDir: string, temporaryProfile: boolean, args: Array<string>, bidi: boolean}>}
+ * @returns {Promise<{driver: Object, page: Object, close: function(): Promise<void>, serverUrl: string, driverProcess: Object, driverPath: string, driverSource: string, browser: string, userDataDir: string, temporaryProfile: boolean, args: Array<string>, bidi: boolean, defaultRestrictions: Array<string>}>}
  */
 export async function launchWebDriver(options = {}, dependencies = {}) {
   if (!isSafariChannel(options.browser ?? 'chrome')) {
@@ -550,6 +552,17 @@ function withDriverContext(error, { serverUrl, exitCode, output }) {
   );
 }
 
+// Chrome for Testing - the engines' download or Selenium Manager's - gets its
+// default restrictions like any other launch of it (issue #179).
+function launchDefaultRestrictions(
+  { browser = 'chrome', debuggerAddress, defaultRestrictions },
+  browserPath
+) {
+  return browser === 'chrome' && !debuggerAddress
+    ? defaultRestrictionsFor(browserPath, defaultRestrictions)
+    : [];
+}
+
 async function launchWebDriverOnce(options, dependencies) {
   const {
     browser = 'chrome',
@@ -593,12 +606,17 @@ async function launchWebDriverOnce(options, dependencies) {
     executablePath,
   });
 
+  const defaultRestrictions = launchDefaultRestrictions(
+    options,
+    resolved.browserPath
+  );
+  const launchRestrictions = [...defaultRestrictions, ...restrictions];
   const temporaryProfile = !safari && !debuggerAddress && !requestedUserDataDir;
   const userDataDir =
     safari || debuggerAddress
       ? undefined
       : await resolveProfile(browser, requestedUserDataDir);
-  const childEnv = driverEnvironment(restrictions, env);
+  const childEnv = driverEnvironment(launchRestrictions, env);
 
   let driverProcess;
   let driver;
@@ -636,7 +654,7 @@ async function launchWebDriverOnce(options, dependencies) {
       remoteDebuggingPort:
         browser === 'chrome' ? await reservePort() : undefined,
       headless,
-      restrictions,
+      restrictions: launchRestrictions,
       disableFeatures,
       args,
       automationParity,
@@ -675,6 +693,7 @@ async function launchWebDriverOnce(options, dependencies) {
       temporaryProfile,
       args: built.args,
       bidi,
+      defaultRestrictions,
     };
   } catch (error) {
     const exitCode = driverProcess?.exitCode;

package/src/capture/screenshot.js

@@ -10,6 +10,7 @@ import { captureStableViewport, validateStableViewport } from './viewport.js';
  * @property {string} [path]
  * @property {boolean} [fullPage]
  * @property {boolean} [stableViewport] Capture only the existing view without visual styling.
+ *   Default captures already do so without a fixed viewport; false keeps the engine capture.
  * @property {string} [selector]
  * @property {Object} [element]
  * @property {{x:number,y:number,width:number,height:number}} [clip]
@@ -61,7 +62,7 @@ export async function screenshot(options = {}) {
   if (options.waitForFonts) {
     await page.evaluate(() => document.fonts.ready.then(() => true));
   }
-  if (options.stableViewport) {
+  if (capturesView(options, engine, css)) {
     if (engine === 'playwright') {
       native.scale = scale;
       native.caret = 'initial';
@@ -123,6 +124,20 @@ export async function screenshot(options = {}) {
   }
 }
 
+/**
+ * A default capture of a page without a fixed viewport takes the view as it
+ * is: a clipped engine capture can leave a resized window stuck (issue #180).
+ */
+function capturesView(options, engine, css) {
+  const { selector, element, clip, fullPage, omitBackground } = options;
+  return (
+    options.stableViewport ??
+    (['playwright', 'puppeteer'].includes(engine) &&
+      ![selector, element, clip, fullPage, omitBackground, css].some(Boolean) &&
+      (options.scale ?? 'device') === 'device')
+  );
+}
+
 async function finishScreenshot(
   bytes,
   { page, engine, scale, format, quality, output }

package/src/capture/viewport.js

@@ -28,7 +28,8 @@ export async function captureStableViewport(page, engine, native) {
   }
   let session;
   if (
-    (engine === 'playwright' && typeof page.context === 'function') ||
+    (engine === 'playwright' &&
+      typeof page.context?.()?.newCDPSession === 'function') ||
     (engine === 'puppeteer' &&
       (typeof page.createCDPSession === 'function' ||
         typeof page.target === 'function'))

package/src/exports.js

@@ -104,6 +104,10 @@ export {
   LAUNCH_MODES,
   resolveLaunchExecutable,
 } from './browser/launcher.js';
+export {
+  CHROME_FOR_TESTING_RESTRICTIONS,
+  isChromeForTesting,
+} from './browser/launch-executable.js';
 export {
   LAUNCH_RESTRICTIONS,
   LAUNCH_RESTRICTION_PRESETS,

package/src/traces/recorder.js

@@ -21,6 +21,7 @@ import { startTraceDrain } from './drain-timer.js';
 import { attachRecorderObservers } from './observers.js';
 import { attachNetwork, validateNetworkOptions } from './network.js';
 import { startRecording } from '../capture/recording.js';
+import { captureStableViewport } from '../capture/viewport.js';
 import { normalizePrivacyOptions, redactValue } from './redaction.js';
 import path from 'node:path';
 import {
@@ -47,6 +48,17 @@ const DEFAULT_DOM_OPTIONS = Object.freeze({
   openShadowRoots: true,
 });
 
+/** The CDP-capable engine a bare page belongs to, or null for any other page. */
+function pageEngine(page) {
+  if (typeof page.context === 'function') {
+    return 'playwright';
+  }
+  return typeof page.createCDPSession === 'function' ||
+    typeof page.target === 'function'
+    ? 'puppeteer'
+    : null;
+}
+
 function normalizeMode(mode) {
   const values = Object.values(TRACE_MODE);
   if (!values.includes(mode)) {
@@ -275,12 +287,16 @@ export async function startTrace(options = {}) {
       return null;
     }
     try {
+      // A clipped engine capture can leave a resized headful window drawn at
+      // its old size (issue #180); without a fixed viewport, capture the view.
       const shot = await withDeadline(
-        page.screenshot({ type: 'png' }),
+        captureStableViewport(page, engine ?? pageEngine(page), {
+          type: 'png',
+        }),
         captureTimeoutMs,
         'trace screenshot'
       );
-      return Buffer.isBuffer(shot) ? shot : Buffer.from(shot);
+      return shot.bytes;
     } catch (error) {
       await bundle.drop({
         reason: TRACE_DROP_REASON.CAPTURE_FAILED,

package/tests/e2e/startup-readiness.e2e.test.js

@@ -44,6 +44,7 @@ it(
   async () => {
     const sibling = await launchBrowser({
       debug: false,
+      channel: 'chrome',
       headless: true,
       ...CHROME_LAUNCH_OPTIONS,
     });
@@ -58,6 +59,7 @@ it(
             launchAndConnectRealBrowserWithDependencies(
               {
                 debug: false,
+                channel: 'chrome',
                 headless: true,
                 persistSessionCookies: suppliedProfile,
                 ...(suppliedProfile ? { userDataDir: root } : {}),