browser-commander 0.10.0 → 0.12.0

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/elements/content.js

@@ -2,6 +2,61 @@ import { isNavigationError } from '../core/navigation-safety.js';
 import { getLocatorOrElement } from './locators.js';
 import { createEngineAdapter } from '../core/engine-adapter.js';
 
+/**
+ * Get the full HTML of the current page
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Browser page object
+ * @param {string} options.engine - Engine type ('playwright' or 'puppeteer')
+ * @param {Object} options.adapter - Engine adapter (optional, will be created if not provided)
+ * @returns {Promise<string|null>} - Serialized page HTML, or null during navigation
+ */
+export async function content(options = {}) {
+  const { page, engine, adapter: providedAdapter } = options;
+
+  try {
+    const adapter = providedAdapter || createEngineAdapter(page, engine);
+    return await adapter.getPageContent();
+  } catch (error) {
+    if (isNavigationError(error)) {
+      console.log('⚠️  Navigation detected during content, returning null');
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Get rendered text from an element, defaulting to the document body
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Browser page object
+ * @param {string} options.engine - Engine type ('playwright' or 'puppeteer')
+ * @param {string|Object} [options.selector='body'] - CSS selector or element
+ * @param {Object} options.adapter - Engine adapter (optional, will be created if not provided)
+ * @returns {Promise<string|null>} - Rendered text, or null if unavailable
+ */
+export async function innerText(options = {}) {
+  const { page, engine, selector = 'body', adapter: providedAdapter } = options;
+
+  try {
+    const adapter = providedAdapter || createEngineAdapter(page, engine);
+    const locatorOrElement = await getLocatorOrElement({
+      page,
+      engine,
+      selector,
+    });
+    if (!locatorOrElement) {
+      return null;
+    }
+    return await adapter.getInnerText(locatorOrElement);
+  } catch (error) {
+    if (isNavigationError(error)) {
+      console.log('⚠️  Navigation detected during innerText, returning null');
+      return null;
+    }
+    throw error;
+  }
+}
+
 /**
  * Get text content
  * @param {Object} options - Configuration options

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,
@@ -78,6 +80,8 @@ export {
 export { isVisible, isEnabled, count } from './elements/visibility.js';
 
 export {
+  content,
+  innerText,
   textContent,
   inputValue,
   getAttribute,

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

@@ -44,6 +44,7 @@ export function createMockPlaywrightPage(options = {}) {
       },
       focus: async () => {},
       textContent: async () => elementData.textContent,
+      innerText: async () => elementData.innerText ?? elementData.textContent,
       inputValue: async () => elementData.value,
       getAttribute: async (name) => elementData[name] || null,
       isVisible: async () => elementData.visible,
@@ -56,6 +57,7 @@ export function createMockPlaywrightPage(options = {}) {
         const mockEl = {
           tagName: 'DIV',
           textContent: elementData.textContent,
+          innerText: elementData.innerText ?? elementData.textContent,
           value: elementData.value,
           className: elementData.className,
           disabled: !elementData.enabled,
@@ -88,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),
@@ -105,6 +108,7 @@ export function createMockPlaywrightPage(options = {}) {
       return locs.map((l) => l.evaluate(fn, ...args));
     },
     locator: locatorMock,
+    content: async () => '<html><body>Mock page</body></html>',
     // Playwright's page.evaluate() only accepts a single argument (not spread)
     // This is the key difference from Puppeteer
     evaluate: async (fn, arg) => {
@@ -193,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) => {
@@ -213,6 +218,8 @@ export function createMockPuppeteerPage(options = {}) {
       const mockEl = {
         tagName: 'DIV',
         textContent: elementData.textContent || 'Mock text',
+        innerText:
+          elementData.innerText ?? elementData.textContent ?? 'Mock text',
         value: elementData.value || '',
         className: elementData.className || 'mock-class',
         disabled: !elementData.enabled,
@@ -252,6 +259,7 @@ export function createMockPuppeteerPage(options = {}) {
           const mockEl = {
             tagName: 'DIV',
             textContent: 'Mock text',
+            innerText: 'Mock text',
             value: '',
             className: 'mock-class',
             disabled: false,
@@ -280,6 +288,7 @@ export function createMockPuppeteerPage(options = {}) {
         return fn;
       }
     },
+    content: async () => '<html><body>Mock page</body></html>',
     mainFrame: () => ({
       url: () => url,
     }),
@@ -434,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'
@@ -129,6 +133,14 @@ describe('bindings', () => {
         typeof bindings.textContent === 'function',
         'textContent should be a function'
       );
+      assert.ok(
+        typeof bindings.content === 'function',
+        'content should be a function'
+      );
+      assert.ok(
+        typeof bindings.innerText === 'function',
+        'innerText should be a function'
+      );
       assert.ok(
         typeof bindings.inputValue === 'function',
         'inputValue should be a function'
@@ -204,6 +216,62 @@ describe('bindings', () => {
       assert.strictEqual(url, 'https://example.com');
     });
 
+    it('should expose page content with no arguments', async () => {
+      const page = createMockPlaywrightPage();
+      const bindings = createBoundFunctions({
+        page,
+        engine: 'playwright',
+        log: createMockLogger(),
+      });
+
+      assert.strictEqual(
+        await bindings.content(),
+        '<html><body>Mock page</body></html>'
+      );
+    });
+
+    it('should expose innerText with a selector or the body by default', async () => {
+      const page = createMockPlaywrightPage({
+        elements: {
+          body: { innerText: 'Body text', count: 1 },
+          main: { innerText: 'Main text', count: 1 },
+        },
+      });
+      const bindings = createBoundFunctions({
+        page,
+        engine: 'playwright',
+        log: createMockLogger(),
+      });
+
+      assert.strictEqual(await bindings.innerText(), 'Body text');
+      assert.strictEqual(await bindings.innerText('main'), 'Main text');
+    });
+
+    it('should evaluate a function with positional arguments', async () => {
+      const page = createMockPlaywrightPage();
+      const bindings = createBoundFunctions({
+        page,
+        engine: 'playwright',
+        log: createMockLogger(),
+      });
+
+      assert.strictEqual(await bindings.evaluate((a, b) => a + b, 2, 3), 5);
+    });
+
+    it('should preserve the evaluate options-object API', async () => {
+      const page = createMockPlaywrightPage();
+      const bindings = createBoundFunctions({
+        page,
+        engine: 'playwright',
+        log: createMockLogger(),
+      });
+
+      assert.strictEqual(
+        await bindings.evaluate({ fn: (a, b) => a + b, args: [2, 3] }),
+        5
+      );
+    });
+
     it('should pre-bind log to functions', async () => {
       const page = createMockPlaywrightPage();
       const log = createMockLogger({ collectLogs: true });

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: '' }));
+    });
+  });
+});