browser-commander 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.13.0
+
+### Minor Changes
+
+- 46d0049: Add CDP attachment through `connectBrowser()` for Playwright and Puppeteer, plus `launchAndConnectRealBrowser()` for starting an installed Chrome-family browser with a dedicated automation profile.
+
+## 0.12.0
+
+### Minor Changes
+
+- Add `commander.setContent()` for safely loading in-memory HTML through the managed navigation lifecycle.
+
+  Add portable cookie and localStorage restoration through `launchBrowser({ storageState })` and the `saveStorageState()` helper for Playwright and Puppeteer.
+
+  Avoid intermittent Node 24 test-runner transport failures on macOS by running test files without child-process isolation.
+
 ## 0.11.0
 
 ### Minor Changes

package/README.md

@@ -82,6 +82,12 @@ commander.pageTrigger({
 // 4. Navigate - action auto-starts when page is ready
 await commander.goto({ url: 'https://example.com' });
 
+// Or safely replace the document with in-memory HTML
+await commander.setContent({
+  html: '<h1>Hi</h1>',
+  waitUntil: 'networkidle',
+});
+
 // 5. Cleanup
 await commander.destroy();
 await browser.close();
@@ -100,6 +106,57 @@ const { browser, page } = await launchBrowser({
 });
 ```
 
+Attach to a Chrome-family browser that is already listening for CDP connections:
+
+```javascript
+import { connectBrowser, makeBrowserCommander } from 'browser-commander';
+
+const { browser, page } = await connectBrowser({
+  engine: 'playwright', // or 'puppeteer'
+  cdpEndpoint: 'http://127.0.0.1:9222',
+});
+const commander = makeBrowserCommander({ page });
+```
+
+`launchAndConnectRealBrowser()` can find and start a genuine installed Chrome,
+Edge, Brave, or Chromium with a loopback CDP endpoint and then attach to it. It
+always uses a dedicated profile; Chrome 136 and newer do not honor remote
+debugging switches for the default profile. See the
+[Chrome remote-debugging security change](https://developer.chrome.com/blog/remote-debugging-port).
+
+```javascript
+import { launchAndConnectRealBrowser } from 'browser-commander';
+
+const connection = await launchAndConnectRealBrowser({
+  engine: 'puppeteer',
+  channel: 'chrome',
+  userDataDir: '/tmp/my-automation-profile',
+  seedCookies: [
+    { name: 'session', value: 'saved', url: 'https://example.com' },
+  ],
+});
+await connection.browser.close();
+```
+
+Cookie seeding copies only cookies you explicitly provide; the helper does not
+read, decrypt, or expose cookies from a browser's default profile.
+
+Reuse a saved authenticated session by passing Playwright-compatible storage
+state as a JSON file path or object. Cookies and localStorage are restored for
+both engines:
+
+```javascript
+import { launchBrowser, saveStorageState } from 'browser-commander';
+
+const { browser, page } = await launchBrowser({
+  engine: 'playwright',
+  storageState: './gmail-state.json',
+});
+
+// Save the current session for a later launch.
+await saveStorageState(page, './gmail-state.json');
+```
+
 ## Browser Commander Tests
 
 `browser-commander/tests` adds browser fixtures and scheduling helpers on top of
@@ -271,11 +328,58 @@ const { browser, page } = await launchBrowser({
   slowMo: 150, // Slow down operations (ms)
   verbose: false, // Enable debug logging
   args: ['--no-sandbox', '--disable-setuid-sandbox'], // Custom Chrome args to append
+  storageState: './session-state.json', // Saved cookies and localStorage, as a path or object
 });
 ```
 
 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.
+Each engine restores its cookies and origin-specific localStorage before
+navigation, including when Playwright uses a persistent context.
+
+### connectBrowser(options)
+
+Connect to an existing Chrome-family browser over an HTTP or WebSocket CDP
+endpoint. Exactly one of `cdpEndpoint` and `wsEndpoint` is required. The raw
+`browser` and `page` work with both the underlying engine API and
+`makeBrowserCommander({ page })`.
+
+```javascript
+const { browser, page } = await connectBrowser({
+  engine: 'playwright',
+  wsEndpoint: 'ws://127.0.0.1:9222/devtools/browser/<id>',
+  timeout: 30_000,
+  seedCookies: [
+    { name: 'session', value: 'saved', url: 'https://example.com' },
+  ],
+});
+```
+
+Playwright accepts `timeout` and Puppeteer accepts `protocolTimeout`.
+`storageState` can also seed Playwright-compatible cookies and localStorage.
+
+### launchAndConnectRealBrowser(options)
+
+Start an installed browser and connect through `connectBrowser()`. Use
+`channel` (`chrome`, `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge`,
+`msedge-beta`, `msedge-dev`, `msedge-canary`, `brave`, or `chromium`) or an
+explicit `executablePath`. The helper defaults to
+a managed directory under `~/.browser-commander/real-browser/`, rejects known
+default browser-profile paths, protects its remote-debugging arguments, and
+returns the spawned `browserProcess`, resolved `cdpEndpoint`, executable path,
+and profile path alongside `{ browser, page }`.
+
+### saveStorageState(page, filePath)
+
+Save the current cookies and localStorage in Playwright's portable storage
+state format. The helper supports pages from either engine and also returns the
+saved object:
+
+```javascript
+const state = await saveStorageState(page, './session-state.json');
+```
+
 The `colorScheme` option allows setting the initial color scheme (`'light'`, `'dark'`, or `'no-preference'`) at launch time for screenshot services and testing tools:
 
 ```javascript

package/examples/pdf-generation.js

@@ -1,8 +1,8 @@
 /**
  * Example: PDF generation via browser-commander
  *
- * This example shows how to use the unified page.pdf() method
- * instead of the old workaround: `const rawPage = page._page || page`.
+ * This example shows how to load in-memory HTML and generate a PDF through the
+ * unified commander API.
  *
  * Supports both Playwright and Puppeteer engines.
  *
@@ -45,8 +45,11 @@ async function generatePdf() {
   try {
     const commander = makeBrowserCommander({ page, verbose: false });
 
-    // Navigate to a page
-    await page.goto('https://example.com');
+    // Load HTML assembled in memory using the managed navigation lifecycle.
+    await commander.setContent({
+      html: '<main><h1>Browser Commander</h1><p>Generated in memory.</p></main>',
+      waitUntil: 'load',
+    });
 
     // Generate PDF using the unified API (no workarounds needed!)
     const pdfBuffer = await commander.pdf({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",

package/scripts/run-tests.mjs

@@ -137,9 +137,27 @@ export function resolveTestFiles(targets, cwd = process.cwd()) {
   return uniqueFiles.map((file) => relative(cwd, file));
 }
 
-export function buildNodeTestArgs(options, testFiles) {
+function supportsTestIsolation(nodeVersion) {
+  const majorVersion = Number.parseInt(nodeVersion.split('.')[0], 10);
+  return Number.isInteger(majorVersion) && majorVersion >= 24;
+}
+
+export function buildNodeTestArgs(
+  options,
+  testFiles,
+  nodeVersion = process.versions.node
+) {
   const args = ['--test'];
 
+  // Node's default process isolation serializes each test file's results over
+  // a child-process channel. Node 24 on macOS can intermittently corrupt that
+  // stream (ERR_TEST_FAILURE: "Unable to deserialize cloned data"). Running
+  // supported runtimes in-process removes that transport while keeping the
+  // Node 20-compatible fallback for consumers on the minimum engine version.
+  if (supportsTestIsolation(nodeVersion)) {
+    args.push('--test-isolation=none');
+  }
+
   if (options.coverage) {
     args.push('--experimental-test-coverage');
   }

package/src/README.md

@@ -417,6 +417,19 @@ await commander.goto({
 });
 ```
 
+### commander.setContent(options)
+
+Load an in-memory HTML document while preserving the same page-trigger cleanup
+and readiness guarantees as `goto()`:
+
+```javascript
+await commander.setContent({
+  html: '<h1>Hi</h1>',
+  waitUntil: 'networkidle', // Playwright/Puppeteer option
+  timeout: 60000,
+});
+```
+
 ### commander.clickButton(options)
 
 ```javascript

package/src/bindings.js

@@ -8,6 +8,7 @@ import { getUrl, unfocusAddressBar } from './utilities/url.js';
 import {
   waitForUrlStabilization,
   goto,
+  setContent,
   waitForNavigation,
   waitForPageReady,
   waitAfterAction,
@@ -115,6 +116,12 @@ export function createBoundFunctions(options = {}) {
       waitForUrlStabilization: waitForUrlStabilizationBound,
       navigationManager,
     });
+  const setContentBound = (opts) =>
+    setContent({
+      ...opts,
+      page,
+      navigationManager,
+    });
   const waitForNavigationBound = (opts) =>
     waitForNavigation({
       ...opts,
@@ -312,6 +319,7 @@ export function createBoundFunctions(options = {}) {
     querySelectorAll: querySelectorAllBound,
     waitForUrlStabilization: waitForUrlStabilizationBound,
     goto: gotoBound,
+    setContent: setContentBound,
     getUrl: getUrlBound,
     waitForNavigation: waitForNavigationBound,
     waitForPageReady: waitForPageReadyBound,

package/src/browser/connector.js

@@ -0,0 +1,163 @@
+import {
+  loadStorageState,
+  restorePlaywrightStorageState,
+  restorePuppeteerStorageState,
+} from './storage-state.js';
+
+function validateConnectionOptions({ engine, cdpEndpoint, wsEndpoint }) {
+  if (!['playwright', 'puppeteer'].includes(engine)) {
+    throw new Error(
+      `Invalid engine: ${engine}. Expected 'playwright' or 'puppeteer'`
+    );
+  }
+
+  if (Boolean(cdpEndpoint) === Boolean(wsEndpoint)) {
+    throw new Error(
+      'connectBrowser requires exactly one of cdpEndpoint or wsEndpoint'
+    );
+  }
+}
+
+function addDefinedOptions(options, values) {
+  for (const [key, value] of Object.entries(values)) {
+    if (value !== undefined) {
+      options[key] = value;
+    }
+  }
+  return options;
+}
+
+function buildPlaywrightConnectOptions({ slowMo, timeout, headers }) {
+  return addDefinedOptions({}, { slowMo, timeout, headers });
+}
+
+function buildPuppeteerConnectOptions({
+  cdpEndpoint,
+  wsEndpoint,
+  slowMo,
+  protocolTimeout,
+  headers,
+}) {
+  return addDefinedOptions(
+    {
+      ...(cdpEndpoint
+        ? { browserURL: cdpEndpoint }
+        : { browserWSEndpoint: wsEndpoint }),
+      defaultViewport: null,
+    },
+    { slowMo, protocolTimeout, headers }
+  );
+}
+
+async function prepareStorageState({ storageState, seedCookies }) {
+  if (seedCookies !== undefined && !Array.isArray(seedCookies)) {
+    throw new TypeError('seedCookies must be an array');
+  }
+
+  const resolvedStorageState = await loadStorageState(storageState);
+  if (!resolvedStorageState && seedCookies === undefined) {
+    return undefined;
+  }
+
+  return {
+    ...(resolvedStorageState ?? {}),
+    cookies: [...(resolvedStorageState?.cookies ?? []), ...(seedCookies ?? [])],
+  };
+}
+
+async function connectPlaywright({ options, loadPlaywright, storageState }) {
+  const { chromium } = await loadPlaywright();
+  const endpoint = options.cdpEndpoint ?? options.wsEndpoint;
+  const browser = await chromium.connectOverCDP(
+    endpoint,
+    buildPlaywrightConnectOptions(options)
+  );
+  const context = browser.contexts()[0];
+  if (!context) {
+    throw new Error('Connected Playwright browser has no default context');
+  }
+  const page = context.pages()[0] ?? (await context.newPage());
+
+  await restorePlaywrightStorageState({ context, storageState });
+  return { browser, page };
+}
+
+async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
+  const puppeteerModule = await loadPuppeteer();
+  const puppeteer = puppeteerModule.default ?? puppeteerModule;
+  const browser = await puppeteer.connect(
+    buildPuppeteerConnectOptions(options)
+  );
+  const pages = await browser.pages();
+  const page = pages[0] ?? (await browser.newPage());
+
+  await restorePuppeteerStorageState({ page, storageState });
+  return { browser, page };
+}
+
+/**
+ * Attach to an already-running Chromium-family browser over CDP.
+ *
+ * @param {Object} options - Connection options
+ * @param {'playwright'|'puppeteer'} [options.engine='playwright'] - Automation engine
+ * @param {string} [options.cdpEndpoint] - HTTP DevTools endpoint, such as http://127.0.0.1:9222
+ * @param {string} [options.wsEndpoint] - DevTools browser WebSocket endpoint
+ * @param {number} [options.slowMo] - Delay engine operations by this many milliseconds
+ * @param {number} [options.timeout] - Playwright connection timeout in milliseconds
+ * @param {number} [options.protocolTimeout] - Puppeteer CDP call timeout in milliseconds
+ * @param {Object<string,string>} [options.headers] - Additional connection headers
+ * @param {Object[]|string|Object} [options.storageState] - Playwright-compatible state path or object
+ * @param {Object[]} [options.seedCookies] - Cookies to seed after connecting
+ * @param {boolean} [options.verbose=false] - Enable connection logging
+ * @returns {Promise<{browser: Object, page: Object}>} Raw browser and page handles
+ */
+export async function connectBrowser(options = {}) {
+  return await connectBrowserWithDependencies(options);
+}
+
+/**
+ * Dependency-injected implementation used by the public connector and tests.
+ *
+ * @param {Object} options - See {@link connectBrowser}
+ * @param {Object} dependencies - Optional engine module loaders
+ * @returns {Promise<{browser: Object, page: Object}>} Raw browser and page handles
+ */
+export async function connectBrowserWithDependencies(
+  options = {},
+  dependencies = {}
+) {
+  const normalizedOptions = {
+    engine: 'playwright',
+    verbose: false,
+    ...options,
+  };
+  validateConnectionOptions(normalizedOptions);
+
+  const storageState = await prepareStorageState(normalizedOptions);
+  const { engine, verbose } = normalizedOptions;
+  if (verbose) {
+    console.log(`Connecting to browser with ${engine} engine...`);
+  }
+
+  const result =
+    engine === 'playwright'
+      ? await connectPlaywright({
+          options: normalizedOptions,
+          loadPlaywright:
+            dependencies.loadPlaywright ?? (() => import('playwright')),
+          storageState,
+        })
+      : await connectPuppeteer({
+          options: normalizedOptions,
+          loadPuppeteer:
+            dependencies.loadPuppeteer ?? (() => import('puppeteer')),
+          storageState,
+        });
+
+  if (verbose) {
+    console.log(`Connected to browser with ${engine} engine`);
+  }
+  return result;
+}
+
+export { buildPlaywrightConnectOptions, buildPuppeteerConnectOptions };

package/src/browser/launcher.js

@@ -7,6 +7,11 @@ import {
   buildPlaywrightLaunchOptions,
   buildPuppeteerLaunchOptions,
 } from './launch-options.js';
+import {
+  loadStorageState,
+  restorePlaywrightStorageState,
+  restorePuppeteerStorageState,
+} from './storage-state.js';
 
 /**
  * Launch browser with default configuration
@@ -20,6 +25,7 @@ import {
  * @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', or 'msedge'
  * @param {string} [options.executablePath] - Explicit path to a Chrome or Chromium executable
+ * @param {string|Object} [options.storageState] - Playwright-compatible storage state path or object
  * @returns {Promise<Object>} - Object with browser and page
  */
 export async function launchBrowser(options = {}) {
@@ -33,6 +39,7 @@ export async function launchBrowser(options = {}) {
     colorScheme,
     channel,
     executablePath,
+    storageState,
   } = options;
 
   // Combine default CHROME_ARGS with custom args
@@ -44,6 +51,8 @@ export async function launchBrowser(options = {}) {
     );
   }
 
+  const resolvedStorageState = await loadStorageState(storageState);
+
   // Set environment variables to suppress warnings
   process.env.GOOGLE_API_KEY = 'no';
   process.env.GOOGLE_DEFAULT_CLIENT_ID = 'no';
@@ -74,6 +83,10 @@ export async function launchBrowser(options = {}) {
       contextOptions
     );
     page = browser.pages()[0];
+    await restorePlaywrightStorageState({
+      context: browser,
+      storageState: resolvedStorageState,
+    });
   } else {
     const puppeteer = await import('puppeteer');
     browser = await puppeteer.default.launch(
@@ -87,6 +100,10 @@ export async function launchBrowser(options = {}) {
     );
     const pages = await browser.pages();
     page = pages[0];
+    await restorePuppeteerStorageState({
+      page,
+      storageState: resolvedStorageState,
+    });
   }
 
   if (verbose) {

package/src/browser/navigation.js

@@ -348,6 +348,64 @@ export async function goto(options = {}) {
   }
 }
 
+/**
+ * Replace the current document with an in-memory HTML string.
+ * When NavigationManager is available, this uses the same managed lifecycle as
+ * goto so active page triggers are stopped before the document is replaced.
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Browser page object
+ * @param {Object} options.navigationManager - NavigationManager instance (preferred)
+ * @param {string} options.html - HTML to load
+ * @param {string} options.waitUntil - Wait until condition (default: 'load')
+ * @param {number} options.timeout - Content loading timeout in ms (default: 60000)
+ * @returns {Promise<Object>} Content loading result
+ */
+export async function setContent(options = {}) {
+  const {
+    page,
+    navigationManager,
+    html,
+    waitUntil = 'load',
+    timeout = 60000,
+  } = options;
+
+  if (typeof html !== 'string') {
+    throw new Error('html is required in options');
+  }
+
+  try {
+    let loaded;
+    if (navigationManager) {
+      loaded = await navigationManager.setContent({
+        html,
+        waitUntil,
+        timeout,
+      });
+    } else {
+      await page.setContent(html, { waitUntil, timeout });
+      loaded = true;
+    }
+
+    return loaded
+      ? { loaded: true, actualUrl: page.url() }
+      : {
+          loaded: false,
+          actualUrl: page.url(),
+          reason: 'content loading stopped/interrupted',
+        };
+  } catch (error) {
+    if (isNavigationError(error) || isActionStoppedError(error)) {
+      return {
+        loaded: false,
+        actualUrl: page.url(),
+        reason: 'content loading stopped/interrupted',
+      };
+    }
+    throw error;
+  }
+}
+
 /**
  * Wait for navigation
  * @param {Object} options - Configuration options