browser-commander 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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
+
+- 8ef86eb: Add page HTML, rendered text, and positional page evaluation APIs to commander instances.
+
 ## 0.10.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,22 @@ const { browser, page } = await launchBrowser({
 });
 ```
 
+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 +293,26 @@ 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.
+
+### 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
@@ -360,6 +397,27 @@ await commander.fillTextArea({
 });
 ```
 
+### Page Content Extraction
+
+Read the current page without reaching through to the engine-specific page API:
+
+```javascript
+const html = await commander.content();
+const pageText = await commander.innerText(); // document.body
+const mainText = await commander.innerText('main');
+const title = await commander.evaluate(() => document.title);
+const total = await commander.evaluate((a, b) => a + b, 2, 3);
+```
+
+The existing options-object form of `evaluate` remains supported:
+
+```javascript
+const total = await commander.evaluate({
+  fn: (a, b) => a + b,
+  args: [2, 3],
+});
+```
+
 ### Keyboard Interactions
 
 ```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.10.0",
+  "version": "0.12.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,
@@ -30,6 +31,8 @@ import {
 } from './elements/selectors.js';
 import { isVisible, isEnabled, count } from './elements/visibility.js';
 import {
+  content,
+  innerText,
   textContent,
   inputValue,
   getAttribute,
@@ -85,7 +88,13 @@ export function createBoundFunctions(options = {}) {
       : null;
     return wait({ ...opts, log, abortSignal: opts.abortSignal || abortSignal });
   };
-  const evaluateBound = (opts) => evaluate({ ...opts, page, engine });
+  const evaluateBound = (fnOrOptions, ...args) => {
+    const opts =
+      typeof fnOrOptions === 'function'
+        ? { fn: fnOrOptions, args }
+        : fnOrOptions;
+    return evaluate({ ...opts, page, engine });
+  };
   const safeEvaluateBound = (opts) => safeEvaluate({ ...opts, page, engine });
   const getUrlBound = () => getUrl({ page });
   const unfocusAddressBarBound = (opts = {}) =>
@@ -107,6 +116,12 @@ export function createBoundFunctions(options = {}) {
       waitForUrlStabilization: waitForUrlStabilizationBound,
       navigationManager,
     });
+  const setContentBound = (opts) =>
+    setContent({
+      ...opts,
+      page,
+      navigationManager,
+    });
   const waitForNavigationBound = (opts) =>
     waitForNavigation({
       ...opts,
@@ -158,6 +173,16 @@ export function createBoundFunctions(options = {}) {
   const countBound = (opts) => count({ ...opts, page, engine });
 
   // Bound content
+  const contentBound = (opts = {}) => content({ ...opts, page, engine });
+  const innerTextBound = (selectorOrOptions = 'body') => {
+    const opts =
+      typeof selectorOrOptions === 'object' &&
+      selectorOrOptions !== null &&
+      Object.hasOwn(selectorOrOptions, 'selector')
+        ? selectorOrOptions
+        : { selector: selectorOrOptions };
+    return innerText({ ...opts, page, engine });
+  };
   const textContentBound = (opts) => textContent({ ...opts, page, engine });
   const inputValueBound = (opts) => inputValue({ ...opts, page, engine });
   const getAttributeBound = (opts) => getAttribute({ ...opts, page, engine });
@@ -294,6 +319,7 @@ export function createBoundFunctions(options = {}) {
     querySelectorAll: querySelectorAllBound,
     waitForUrlStabilization: waitForUrlStabilizationBound,
     goto: gotoBound,
+    setContent: setContentBound,
     getUrl: getUrlBound,
     waitForNavigation: waitForNavigationBound,
     waitForPageReady: waitForPageReadyBound,
@@ -302,6 +328,8 @@ export function createBoundFunctions(options = {}) {
     isVisible: isVisibleWrapped,
     isEnabled: isEnabledWrapped,
     count: countBound,
+    content: contentBound,
+    innerText: innerTextBound,
     textContent: textContentWrapped,
     inputValue: inputValueWrapped,
     locator: locatorBound,

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

package/src/browser/storage-state.js

@@ -0,0 +1,133 @@
+import { readFile, writeFile } from 'node:fs/promises';
+
+/**
+ * Load a Playwright-compatible storage state from a JSON path or object.
+ * @param {string|Object|undefined} storageState - State path or parsed state
+ * @returns {Promise<Object|undefined>} Parsed state
+ */
+export async function loadStorageState(storageState) {
+  if (storageState === undefined) {
+    return undefined;
+  }
+  if (typeof storageState === 'string') {
+    return JSON.parse(await readFile(storageState, 'utf8'));
+  }
+  if (storageState && typeof storageState === 'object') {
+    return storageState;
+  }
+  throw new TypeError('storageState must be a file path or an object');
+}
+
+function restoreOriginLocalStorage(origins) {
+  const originState = origins.find(
+    ({ origin }) => origin === globalThis.location.origin
+  );
+  if (!originState) {
+    return;
+  }
+  for (const { name, value } of originState.localStorage ?? []) {
+    globalThis.localStorage.setItem(name, value);
+  }
+}
+
+/**
+ * Apply Playwright-compatible storage state to a Puppeteer page.
+ * @param {Object} options - Restore options
+ * @param {Object} options.page - Puppeteer page
+ * @param {Object|undefined} options.storageState - Parsed storage state
+ * @returns {Promise<void>}
+ */
+export async function restorePuppeteerStorageState({ page, storageState }) {
+  if (!storageState) {
+    return;
+  }
+
+  const cookies = storageState.cookies ?? [];
+  if (cookies.length > 0) {
+    await page.setCookie(...cookies);
+  }
+
+  const origins = storageState.origins ?? [];
+  if (origins.length > 0) {
+    await page.evaluateOnNewDocument(restoreOriginLocalStorage, origins);
+    await page.evaluate(restoreOriginLocalStorage, origins);
+  }
+}
+
+/**
+ * Apply storage state to a Playwright persistent browser context.
+ * @param {Object} options - Restore options
+ * @param {Object} options.context - Playwright browser context
+ * @param {Object|undefined} options.storageState - Parsed storage state
+ * @returns {Promise<void>}
+ */
+export async function restorePlaywrightStorageState({ context, storageState }) {
+  if (!storageState) {
+    return;
+  }
+
+  const cookies = storageState.cookies ?? [];
+  if (cookies.length > 0) {
+    await context.addCookies(cookies);
+  }
+
+  const origins = storageState.origins ?? [];
+  if (origins.length > 0) {
+    await context.addInitScript(restoreOriginLocalStorage, origins);
+    await Promise.all(
+      context
+        .pages()
+        .map((page) => page.evaluate(restoreOriginLocalStorage, origins))
+    );
+  }
+}
+
+function readCurrentLocalStorage() {
+  return Array.from({ length: globalThis.localStorage.length }, (_, index) => {
+    const name = globalThis.localStorage.key(index);
+    return { name, value: globalThis.localStorage.getItem(name) };
+  });
+}
+
+async function collectPuppeteerStorageState(page) {
+  const cookies = await page.cookies();
+  const pageUrl = page.url();
+  const origin = new URL(pageUrl).origin;
+  const origins = [];
+
+  if (origin !== 'null') {
+    origins.push({
+      origin,
+      localStorage: await page.evaluate(readCurrentLocalStorage),
+    });
+  }
+
+  return { cookies, origins };
+}
+
+/**
+ * Save a page's cookies and localStorage in Playwright's storage-state format.
+ * @param {Object} page - Playwright or Puppeteer page
+ * @param {string} [filePath] - Optional JSON output path
+ * @returns {Promise<Object>} Saved storage state
+ */
+export async function saveStorageState(page, filePath) {
+  const context = typeof page.context === 'function' ? page.context() : null;
+  if (typeof context?.storageState === 'function') {
+    return context.storageState(filePath ? { path: filePath } : undefined);
+  }
+
+  if (
+    typeof page.cookies !== 'function' ||
+    typeof page.evaluate !== 'function' ||
+    typeof page.url !== 'function'
+  ) {
+    throw new TypeError('page must be a Playwright or Puppeteer page');
+  }
+
+  const storageState = await collectPuppeteerStorageState(page);
+  if (filePath) {
+    await writeFile(filePath, `${JSON.stringify(storageState, null, 2)}\n`);
+  }
+  return storageState;
+}

package/src/core/engine-adapter.js

@@ -120,6 +120,15 @@ export class EngineAdapter {
     return notImplemented('getTextContent');
   }
 
+  /**
+   * Get rendered text from an element
+   * @param {Object} locatorOrElement - Locator or element
+   * @returns {Promise<string>} - Rendered text
+   */
+  getInnerText(_locatorOrElement) {
+    return notImplemented('getInnerText');
+  }
+
   /**
    * Get input value
    * @param {Object} locatorOrElement - Locator or element
@@ -236,6 +245,14 @@ export class EngineAdapter {
     return notImplemented('evaluateOnPage');
   }
 
+  /**
+   * Get the full HTML of the current page
+   * @returns {Promise<string>} - Serialized page HTML
+   */
+  getPageContent() {
+    return notImplemented('getPageContent');
+  }
+
   /**
    * Get the main frame
    * @returns {Object} - Main frame
@@ -325,6 +342,10 @@ export class PlaywrightAdapter extends EngineAdapter {
     return await locatorOrElement.textContent();
   }
 
+  async getInnerText(locatorOrElement) {
+    return await locatorOrElement.innerText();
+  }
+
   async getInputValue(locatorOrElement) {
     return await locatorOrElement.inputValue();
   }
@@ -401,6 +422,10 @@ export class PlaywrightAdapter extends EngineAdapter {
     }
   }
 
+  async getPageContent() {
+    return await this.page.content();
+  }
+
   getMainFrame() {
     return this.page.mainFrame();
   }
@@ -469,6 +494,10 @@ export class PuppeteerAdapter extends EngineAdapter {
     return await this.page.evaluate((el) => el.textContent, locatorOrElement);
   }
 
+  async getInnerText(locatorOrElement) {
+    return await this.page.evaluate((el) => el.innerText, locatorOrElement);
+  }
+
   async getInputValue(locatorOrElement) {
     return await this.page.evaluate((el) => el.value, locatorOrElement);
   }
@@ -541,6 +570,10 @@ export class PuppeteerAdapter extends EngineAdapter {
     return await this.page.evaluate(fn, ...args);
   }
 
+  async getPageContent() {
+    return await this.page.content();
+  }
+
   getMainFrame() {
     return this.page.mainFrame();
   }