browser-commander 0.10.0 → 0.11.0

package/CHANGELOG.md

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

@@ -360,6 +360,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/package.json

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

package/src/bindings.js

@@ -30,6 +30,8 @@ import {
 } from './elements/selectors.js';
 import { isVisible, isEnabled, count } from './elements/visibility.js';
 import {
+  content,
+  innerText,
   textContent,
   inputValue,
   getAttribute,
@@ -85,7 +87,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 = {}) =>
@@ -158,6 +166,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 });
@@ -302,6 +320,8 @@ export function createBoundFunctions(options = {}) {
     isVisible: isVisibleWrapped,
     isEnabled: isEnabledWrapped,
     count: countBound,
+    content: contentBound,
+    innerText: innerTextBound,
     textContent: textContentWrapped,
     inputValue: inputValueWrapped,
     locator: locatorBound,

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();
   }

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

@@ -78,6 +78,8 @@ export {
 export { isVisible, isEnabled, count } from './elements/visibility.js';
 
 export {
+  content,
+  innerText,
   textContent,
   inputValue,
   getAttribute,

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,
@@ -105,6 +107,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) => {
@@ -213,6 +216,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 +257,7 @@ export function createMockPuppeteerPage(options = {}) {
           const mockEl = {
             tagName: 'DIV',
             textContent: 'Mock text',
+            innerText: 'Mock text',
             value: '',
             className: 'mock-class',
             disabled: false,
@@ -280,6 +286,7 @@ export function createMockPuppeteerPage(options = {}) {
         return fn;
       }
     },
+    content: async () => '<html><body>Mock page</body></html>',
     mainFrame: () => ({
       url: () => url,
     }),

package/tests/unit/bindings.test.js

@@ -129,6 +129,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 +212,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/elements/content.test.js

@@ -1,6 +1,8 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
 import {
+  content,
+  innerText,
   textContent,
   inputValue,
   getAttribute,
@@ -14,6 +16,106 @@ import {
 } from '../../helpers/mocks.js';
 
 describe('content', () => {
+  describe('content', () => {
+    for (const [engine, createPage] of [
+      ['playwright', createMockPlaywrightPage],
+      ['puppeteer', createMockPuppeteerPage],
+    ]) {
+      it(`should return the full page HTML for ${engine}`, async () => {
+        const page = createPage();
+        page.content = async () =>
+          '<!doctype html><html><body>Hello</body></html>';
+
+        const html = await content({ page, engine });
+
+        assert.strictEqual(
+          html,
+          '<!doctype html><html><body>Hello</body></html>'
+        );
+      });
+    }
+
+    it('should return null on navigation errors', async () => {
+      const page = createMockPlaywrightPage();
+      page.content = async () => {
+        throw new Error('Execution context was destroyed');
+      };
+
+      assert.strictEqual(await content({ page, engine: 'playwright' }), null);
+    });
+  });
+
+  describe('innerText', () => {
+    it('should return rendered text for Playwright', async () => {
+      const page = createMockPlaywrightPage({
+        elements: { main: { innerText: 'Rendered text', count: 1 } },
+      });
+
+      const text = await innerText({
+        page,
+        engine: 'playwright',
+        selector: 'main',
+      });
+
+      assert.strictEqual(text, 'Rendered text');
+    });
+
+    it('should return rendered text for Puppeteer', async () => {
+      const page = createMockPuppeteerPage({
+        elements: { main: { innerText: 'Rendered text', count: 1 } },
+      });
+      page.evaluate = async () => 'Rendered text';
+
+      const text = await innerText({
+        page,
+        engine: 'puppeteer',
+        selector: 'main',
+      });
+
+      assert.strictEqual(text, 'Rendered text');
+    });
+
+    it('should default to the document body', async () => {
+      const page = createMockPlaywrightPage({
+        elements: { body: { innerText: 'Page text', count: 1 } },
+      });
+
+      assert.strictEqual(
+        await innerText({ page, engine: 'playwright' }),
+        'Page text'
+      );
+    });
+
+    it('should return null when the element is not found', async () => {
+      const page = createMockPuppeteerPage({
+        elements: { main: { count: 0 } },
+      });
+
+      assert.strictEqual(
+        await innerText({ page, engine: 'puppeteer', selector: 'main' }),
+        null
+      );
+    });
+
+    it('should return null on navigation errors', async () => {
+      const page = createMockPlaywrightPage();
+      page.locator = () => ({
+        count: async () => 1,
+        first() {
+          return this;
+        },
+        innerText: async () => {
+          throw new Error('Execution context was destroyed');
+        },
+      });
+
+      assert.strictEqual(
+        await innerText({ page, engine: 'playwright', selector: 'main' }),
+        null
+      );
+    });
+  });
+
   describe('textContent', () => {
     it('should throw when selector is not provided', async () => {
       const page = createMockPlaywrightPage();