browser-commander 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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

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

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.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,
@@ -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/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/navigation-manager.js

@@ -11,6 +11,47 @@
 import { isNavigationError } from './navigation-safety.js';
 import { TIMING } from './constants.js';
 
+async function setManagedContent(options = {}) {
+  const {
+    page,
+    log,
+    html,
+    waitUntil = 'load',
+    timeout = 60000,
+    currentUrl,
+    triggerNavigationStart,
+    updateCurrentUrl,
+    waitForPageReady,
+    completeNavigation,
+  } = options;
+
+  if (typeof html !== 'string') {
+    throw new Error('html is required in options');
+  }
+
+  log.debug(() => '🚀 Loading in-memory HTML content');
+
+  try {
+    // Treat document replacement as a controlled navigation so active page
+    // triggers stop before the old document is discarded.
+    await triggerNavigationStart({ url: currentUrl, isExternal: false });
+    await page.setContent(html, { waitUntil, timeout });
+
+    // setContent normally preserves the URL, but inline scripts can navigate.
+    updateCurrentUrl();
+    await waitForPageReady({ timeout, reason: 'after setContent' });
+    return true;
+  } catch (error) {
+    // Do not leave the manager in its loading state when setContent fails.
+    completeNavigation();
+    if (isNavigationError(error)) {
+      log.debug(() => '⚠️  Content loading was interrupted, recovering...');
+      return false;
+    }
+    throw error;
+  }
+}
+
 /**
  * Create a NavigationManager instance for a page
  * @param {Object} options - Configuration options
@@ -341,6 +382,18 @@ export function createNavigationManager(options = {}) {
     }
   }
 
+  const setContent = (opts = {}) =>
+    setManagedContent({
+      page,
+      log,
+      ...opts,
+      currentUrl,
+      triggerNavigationStart,
+      updateCurrentUrl: () => (currentUrl = page.url()),
+      waitForPageReady,
+      completeNavigation,
+    });
+
   /**
    * Wait for any pending navigation to complete
    * @param {Object} options - Configuration options
@@ -373,27 +426,6 @@ export function createNavigationManager(options = {}) {
     return await navigationPromise;
   }
 
-  /**
-   * Check if we're currently navigating
-   */
-  function isCurrentlyNavigating() {
-    return isNavigating;
-  }
-
-  /**
-   * Get current URL
-   */
-  function getCurrentUrl() {
-    return currentUrl;
-  }
-
-  /**
-   * Get current session ID
-   */
-  function getSessionId() {
-    return sessionId;
-  }
-
   /**
    * Get the current abort signal
    * Use this to check if operations should be aborted due to navigation
@@ -476,13 +508,14 @@ export function createNavigationManager(options = {}) {
   return {
     // Navigation
     navigate,
+    setContent,
     waitForNavigation,
     waitForPageReady,
 
     // State
-    isNavigating: isCurrentlyNavigating,
-    getCurrentUrl,
-    getSessionId,
+    isNavigating: () => isNavigating,
+    getCurrentUrl: () => currentUrl,
+    getSessionId: () => sessionId,
 
     // Abort handling - use these to stop operations when navigation occurs
     getAbortSignal,

package/src/exports.js

@@ -43,10 +43,12 @@ export {
 
 // Re-export browser management
 export { launchBrowser } from './browser/launcher.js';
+export { saveStorageState } from './browser/storage-state.js';
 export { emulateMedia } from './browser/media.js';
 export {
   waitForUrlStabilization,
   goto,
+  setContent,
   waitForNavigation,
   waitForPageReady,
   waitAfterAction,

package/tests/e2e/playwright.e2e.test.js

@@ -522,5 +522,24 @@ describe(
         // Test passes if no error is thrown
       });
     });
+
+    describe('In-memory Content', () => {
+      it('should load HTML through commander.setContent', async () => {
+        if (!commander) {
+          return;
+        }
+
+        const result = await commander.setContent({
+          html: '<main><h1 data-testid="content-title">In memory</h1></main>',
+          waitUntil: 'load',
+        });
+        const title = await commander.textContent({
+          selector: '[data-testid="content-title"]',
+        });
+
+        assert.strictEqual(result.loaded, true);
+        assert.strictEqual(title, 'In memory');
+      });
+    });
   }
 );

package/tests/e2e/puppeteer.e2e.test.js

@@ -476,4 +476,23 @@ describe('E2E Tests - Puppeteer Engine', { skip: !process.env.RUN_E2E }, () => {
       assert.strictEqual(modalClosed, false);
     });
   });
+
+  describe('In-memory Content', () => {
+    it('should load HTML through commander.setContent', async () => {
+      if (!commander) {
+        return;
+      }
+
+      const result = await commander.setContent({
+        html: '<main><h1 data-testid="content-title">In memory</h1></main>',
+        waitUntil: 'load',
+      });
+      const title = await commander.textContent({
+        selector: '[data-testid="content-title"]',
+      });
+
+      assert.strictEqual(result.loaded, true);
+      assert.strictEqual(title, 'In memory');
+    });
+  });
 });

package/tests/helpers/mocks.js

@@ -90,6 +90,7 @@ export function createMockPlaywrightPage(options = {}) {
     _isPlaywrightPage: true,
     url: () => url,
     goto: async (targetUrl, opts = {}) => {},
+    setContent: async (html, opts = {}) => {},
     waitForNavigation: async (opts = {}) => {},
     waitForSelector: async (sel, opts = {}) => locatorMock(sel),
     $: async (sel) => locatorMock(sel),
@@ -196,6 +197,7 @@ export function createMockPuppeteerPage(options = {}) {
     _isPuppeteerPage: true,
     url: () => url,
     goto: async (targetUrl, opts = {}) => {},
+    setContent: async (html, opts = {}) => {},
     waitForNavigation: async (opts = {}) => {},
     waitForSelector: async (sel, opts = {}) => elementMock(sel),
     $: async (sel) => {
@@ -441,6 +443,7 @@ export function createMockNavigationManager(options = {}) {
       url = opts.url || url;
       return true;
     },
+    setContent: async (opts = {}) => true,
     waitForNavigation: async (opts = {}) => true,
     waitForPageReady: async (opts = {}) => true,
     isNavigating: () => navigating,

package/tests/unit/bindings.test.js

@@ -61,6 +61,10 @@ describe('bindings', () => {
         typeof bindings.goto === 'function',
         'goto should be a function'
       );
+      assert.ok(
+        typeof bindings.setContent === 'function',
+        'setContent should be a function'
+      );
       assert.ok(
         typeof bindings.getUrl === 'function',
         'getUrl should be a function'

package/tests/unit/browser/navigation.test.js

@@ -5,6 +5,7 @@ import {
   verifyNavigation,
   waitForUrlStabilization,
   goto,
+  setContent,
   waitForNavigation,
   waitForPageReady,
   waitAfterAction,
@@ -203,6 +204,66 @@ describe('navigation', () => {
     });
   });
 
+  describe('setContent', () => {
+    it('should throw when html is not provided', async () => {
+      const page = createMockPlaywrightPage();
+
+      await assert.rejects(() => setContent({ page }), /html is required/);
+    });
+
+    it('should load content using navigationManager', async () => {
+      const page = createMockPlaywrightPage();
+      const navigationManager = createMockNavigationManager();
+      let receivedOptions;
+      navigationManager.setContent = async (options) => {
+        receivedOptions = options;
+        return true;
+      };
+
+      const result = await setContent({
+        page,
+        navigationManager,
+        html: '<h1>Hi</h1>',
+        waitUntil: 'networkidle',
+        timeout: 5000,
+      });
+
+      assert.deepStrictEqual(receivedOptions, {
+        html: '<h1>Hi</h1>',
+        waitUntil: 'networkidle',
+        timeout: 5000,
+      });
+      assert.deepStrictEqual(result, {
+        loaded: true,
+        actualUrl: 'https://example.com',
+      });
+    });
+
+    it('should load content directly without navigationManager', async () => {
+      const page = createMockPlaywrightPage();
+      let receivedArguments;
+      page.setContent = async (...args) => {
+        receivedArguments = args;
+      };
+
+      const result = await setContent({
+        page,
+        html: '',
+        waitUntil: 'load',
+        timeout: 5000,
+      });
+
+      assert.deepStrictEqual(receivedArguments, [
+        '',
+        { waitUntil: 'load', timeout: 5000 },
+      ]);
+      assert.deepStrictEqual(result, {
+        loaded: true,
+        actualUrl: 'https://example.com',
+      });
+    });
+  });
+
   describe('waitForNavigation', () => {
     it('should delegate to navigationManager if available', async () => {
       const page = createMockPlaywrightPage();

package/tests/unit/browser/storage-state.test.js

@@ -0,0 +1,148 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import {
+  loadStorageState,
+  restorePlaywrightStorageState,
+  restorePuppeteerStorageState,
+  saveStorageState,
+} from '../../../src/browser/storage-state.js';
+import { saveStorageState as publicSaveStorageState } from '../../../src/index.js';
+
+describe('browser storage state', () => {
+  let temporaryDirectory;
+
+  afterEach(async () => {
+    if (temporaryDirectory) {
+      await rm(temporaryDirectory, { recursive: true, force: true });
+      temporaryDirectory = undefined;
+    }
+  });
+
+  it('loads storage state from a path and accepts an object unchanged', async () => {
+    temporaryDirectory = await mkdtemp(
+      path.join(os.tmpdir(), 'browser-commander-storage-state-')
+    );
+    const filePath = path.join(temporaryDirectory, 'state.json');
+    const state = {
+      cookies: [{ name: 'session', value: 'saved', domain: '.example.com' }],
+      origins: [],
+    };
+    await writeFile(filePath, JSON.stringify(state));
+
+    assert.deepEqual(await loadStorageState(filePath), state);
+    assert.equal(await loadStorageState(state), state);
+  });
+
+  it('rejects invalid storage state input', async () => {
+    await assert.rejects(
+      () => loadStorageState(null),
+      /storageState must be a file path or an object/
+    );
+  });
+
+  it('exports saveStorageState from the package API', () => {
+    assert.equal(publicSaveStorageState, saveStorageState);
+  });
+
+  it('restores Puppeteer cookies and localStorage before navigation', async () => {
+    const calls = [];
+    const state = {
+      cookies: [{ name: 'session', value: 'saved', domain: '.example.com' }],
+      origins: [
+        {
+          origin: 'https://example.com',
+          localStorage: [{ name: 'theme', value: 'dark' }],
+        },
+      ],
+    };
+    const page = {
+      setCookie: async (...cookies) => calls.push(['cookies', cookies]),
+      evaluateOnNewDocument: async (fn, value) =>
+        calls.push(['new-document', fn, value]),
+      evaluate: async (fn, value) => calls.push(['current-page', fn, value]),
+    };
+
+    await restorePuppeteerStorageState({ page, storageState: state });
+
+    assert.deepEqual(calls[0], ['cookies', state.cookies]);
+    assert.equal(calls[1][0], 'new-document');
+    assert.equal(calls[1][2], state.origins);
+    assert.equal(calls[2][0], 'current-page');
+    assert.equal(calls[2][2], state.origins);
+  });
+
+  it('restores Playwright cookies and localStorage before navigation', async () => {
+    const calls = [];
+    const state = {
+      cookies: [{ name: 'session', value: 'saved', domain: '.example.com' }],
+      origins: [
+        {
+          origin: 'https://example.com',
+          localStorage: [{ name: 'theme', value: 'dark' }],
+        },
+      ],
+    };
+    const page = {
+      evaluate: async (fn, value) => calls.push(['current-page', fn, value]),
+    };
+    const context = {
+      addCookies: async (cookies) => calls.push(['cookies', cookies]),
+      addInitScript: async (fn, value) =>
+        calls.push(['new-document', fn, value]),
+      pages: () => [page],
+    };
+
+    await restorePlaywrightStorageState({ context, storageState: state });
+
+    assert.deepEqual(calls[0], ['cookies', state.cookies]);
+    assert.equal(calls[1][0], 'new-document');
+    assert.equal(calls[1][2], state.origins);
+    assert.equal(calls[2][0], 'current-page');
+    assert.equal(calls[2][2], state.origins);
+  });
+
+  it('delegates Playwright saves to the page context', async () => {
+    const savedState = { cookies: [], origins: [] };
+    const calls = [];
+    const page = {
+      context: () => ({
+        storageState: async (options) => {
+          calls.push(options);
+          return savedState;
+        },
+      }),
+    };
+
+    assert.equal(await saveStorageState(page, '/tmp/state.json'), savedState);
+    assert.deepEqual(calls, [{ path: '/tmp/state.json' }]);
+  });
+
+  it('saves Puppeteer cookies and current-origin localStorage', async () => {
+    temporaryDirectory = await mkdtemp(
+      path.join(os.tmpdir(), 'browser-commander-storage-state-')
+    );
+    const filePath = path.join(temporaryDirectory, 'state.json');
+    const cookies = [
+      { name: 'session', value: 'saved', domain: '.example.com' },
+    ];
+    const localStorage = [{ name: 'theme', value: 'dark' }];
+    const page = {
+      browserContext: () => ({}),
+      cookies: async () => cookies,
+      url: () => 'https://example.com/inbox',
+      evaluate: async () => localStorage,
+    };
+
+    const state = await saveStorageState(page, filePath);
+
+    assert.deepEqual(state, {
+      cookies,
+      origins: [{ origin: 'https://example.com', localStorage }],
+    });
+    assert.deepEqual(JSON.parse(await readFile(filePath, 'utf8')), state);
+  });
+});

package/tests/unit/core/navigation-manager.test.js

@@ -0,0 +1,62 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { createNavigationManager } from '../../../src/core/navigation-manager.js';
+import {
+  createMockPlaywrightPage,
+  createMockLogger,
+} from '../../helpers/mocks.js';
+
+describe('navigation manager', () => {
+  describe('setContent', () => {
+    it('should apply the full managed navigation lifecycle', async () => {
+      const page = createMockPlaywrightPage();
+      const log = createMockLogger();
+      const calls = [];
+      page.setContent = async (...args) => calls.push(['setContent', ...args]);
+
+      const manager = createNavigationManager({
+        page,
+        engine: 'playwright',
+        log,
+      });
+      manager.configure({ redirectStabilizationTime: 0 });
+      manager.onSessionCleanup(() => calls.push(['cleanup']));
+      manager.on('onNavigationStart', () => calls.push(['navigationStart']));
+      manager.on('onPageReady', () => calls.push(['pageReady']));
+
+      const loaded = await manager.setContent({
+        html: '<h1>Hi</h1>',
+        waitUntil: 'networkidle',
+        timeout: 5000,
+      });
+
+      assert.strictEqual(loaded, true);
+      assert.strictEqual(manager.getSessionId(), 1);
+      assert.strictEqual(manager.isNavigating(), false);
+      assert.deepStrictEqual(calls, [
+        ['cleanup'],
+        ['navigationStart'],
+        [
+          'setContent',
+          '<h1>Hi</h1>',
+          { waitUntil: 'networkidle', timeout: 5000 },
+        ],
+        ['pageReady'],
+      ]);
+    });
+
+    it('should require html while accepting an empty string', async () => {
+      const page = createMockPlaywrightPage();
+      const log = createMockLogger();
+      const manager = createNavigationManager({
+        page,
+        engine: 'playwright',
+        log,
+      });
+      manager.configure({ redirectStabilizationTime: 0 });
+
+      await assert.rejects(() => manager.setContent(), /html is required/);
+      await assert.doesNotReject(() => manager.setContent({ html: '' }));
+    });
+  });
+});

package/tests/unit/scripts/ci-workflow-policy.test.js

@@ -0,0 +1,73 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { checkWorkflow } from '../../../../scripts/check-ci-workflows.mjs';
+
+function withWorkflow(content, callback) {
+  const directory = mkdtempSync(join(tmpdir(), 'browser-commander-ci-'));
+  const filePath = join(directory, 'workflow.yml');
+  writeFileSync(filePath, content);
+
+  try {
+    return callback(filePath);
+  } finally {
+    rmSync(directory, { force: true, recursive: true });
+  }
+}
+
+describe('CI workflow policy', () => {
+  it('accepts bounded job-scoped checks', () => {
+    const workflow = `name: Test
+on: push
+permissions:
+  contents: read
+env:
+  GIT_CONFIG_KEY_0: init.defaultBranch
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    concurrency:
+      group: \${{ github.workflow }}-\${{ github.ref }}-test
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@v6
+`;
+
+    withWorkflow(workflow, (filePath) => {
+      assert.equal(checkWorkflow(filePath), 0);
+    });
+  });
+
+  it('rejects workflow-wide cancellation and unbounded jobs', () => {
+    const workflow = `name: Test
+on: push
+concurrency:
+  group: test
+  cancel-in-progress: true
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - run: npm install
+      - run: echo "\${{ github.head_ref }}"
+      - uses: codecov/codecov-action@v6
+        with:
+          file: coverage.xml
+`;
+    const originalError = console.error;
+    console.error = () => {};
+
+    try {
+      withWorkflow(workflow, (filePath) => {
+        assert.equal(checkWorkflow(filePath), 7);
+      });
+    } finally {
+      console.error = originalError;
+    }
+  });
+});

package/tests/unit/scripts/npm-release-helpers.test.js

@@ -127,12 +127,25 @@ describe('test runner helper', () => {
       reporter: 'spec',
       targets: ['tests/unit'],
     });
-    assert.deepEqual(buildNodeTestArgs(options, ['tests/unit/a.test.js']), [
-      '--test',
-      '--experimental-test-coverage',
-      '--test-reporter',
-      'spec',
-      'tests/unit/a.test.js',
-    ]);
+    assert.deepEqual(
+      buildNodeTestArgs(options, ['tests/unit/a.test.js'], '24.18.0'),
+      [
+        '--test',
+        '--test-isolation=none',
+        '--experimental-test-coverage',
+        '--test-reporter',
+        'spec',
+        'tests/unit/a.test.js',
+      ]
+    );
+  });
+
+  it('keeps process isolation on Node versions without isolation controls', () => {
+    const options = parseTestRunnerArgs(['tests/unit']);
+
+    assert.deepEqual(
+      buildNodeTestArgs(options, ['tests/unit/a.test.js'], '20.20.2'),
+      ['--test', 'tests/unit/a.test.js']
+    );
   });
 });