browser-commander 0.7.0 → 0.8.1

package/.prettierignore

@@ -1,6 +1,7 @@
 node_modules
 coverage
 dist
+docs-api
 *.min.js
 package-lock.json
 .eslintcache

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.8.1
+
+### Patch Changes
+
+- ffc59e6: Add generated JSDoc API documentation support for the JavaScript package.
+
+## 0.8.0
+
+### Minor Changes
+
+- a681a87: Add unified `page.pdf(options)` method to `EngineAdapter`, `PlaywrightAdapter`, and `PuppeteerAdapter`, eliminating the need for users to access raw page objects via the `page._page || page` workaround. The `pdf()` method is also exposed on the `BrowserCommander` facade via `commander.pdf({ pdfOptions })`.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -18,6 +18,16 @@ npm install playwright
 npm install puppeteer
 ```
 
+## Documentation
+
+Generate the JavaScript API reference locally with:
+
+```bash
+npm run docs:api
+```
+
+The repository Documentation workflow also combines this JSDoc output with Rust `cargo doc` output for GitHub Pages publishing from `main`.
+
 ## Core Concept: Page State Machine
 
 Browser Commander manages the browser as a state machine with two states:
@@ -290,6 +300,24 @@ await commander.fillTextArea({
 });
 ```
 
+### Keyboard Interactions
+
+```javascript
+import { pressKey, typeText, keyDown, keyUp } from 'browser-commander';
+
+// Press a single key
+await pressKey({ page, engine: 'playwright', key: 'Escape' });
+await pressKey({ page, engine: 'playwright', key: 'Enter' });
+await pressKey({ page, engine: 'playwright', key: 'Tab' });
+
+// Type text
+await typeText({ page, engine: 'playwright', text: 'Hello World' });
+
+// Hold and release modifier keys
+await keyDown({ page, engine: 'playwright', key: 'Control' });
+await keyUp({ page, engine: 'playwright', key: 'Control' });
+```
+
 ### commander.destroy()
 
 ```javascript

package/eslint.config.js

@@ -118,6 +118,7 @@ export default [
       'node_modules/**',
       'coverage/**',
       'dist/**',
+      'docs-api/**',
       '*.min.js',
       '.eslintcache',
     ],

package/examples/pdf-generation.js

@@ -0,0 +1,76 @@
+/**
+ * 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`.
+ *
+ * Supports both Playwright and Puppeteer engines.
+ *
+ * Usage (Playwright):
+ *   node examples/pdf-generation.js playwright
+ *
+ * Usage (Puppeteer):
+ *   node examples/pdf-generation.js puppeteer
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { makeBrowserCommander } from '../src/factory.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const engine = process.argv[2] || 'playwright';
+
+async function generatePdf() {
+  let browser;
+  let page;
+
+  if (engine === 'playwright') {
+    const { chromium } = await import('playwright');
+    browser = await chromium.launch({ headless: true });
+    const context = await browser.newContext();
+    page = await context.newPage();
+  } else if (engine === 'puppeteer') {
+    const puppeteer = await import('puppeteer');
+    browser = await puppeteer.launch({ headless: true });
+    page = await browser.newPage();
+  } else {
+    console.error(
+      `Unknown engine: ${engine}. Use 'playwright' or 'puppeteer'.`
+    );
+    process.exit(1);
+  }
+
+  try {
+    const commander = makeBrowserCommander({ page, verbose: false });
+
+    // Navigate to a page
+    await page.goto('https://example.com');
+
+    // Generate PDF using the unified API (no workarounds needed!)
+    const pdfBuffer = await commander.pdf({
+      pdfOptions: {
+        format: 'A4',
+        printBackground: true,
+        margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' },
+      },
+    });
+
+    const outputPath = path.join(__dirname, 'output.pdf');
+    fs.writeFileSync(outputPath, pdfBuffer);
+
+    console.log(
+      `PDF generated successfully: ${outputPath} (${pdfBuffer.length} bytes)`
+    );
+
+    await commander.destroy();
+  } finally {
+    await browser.close();
+  }
+}
+
+generatePdf().catch((error) => {
+  console.error('Error:', error.message);
+  process.exit(1);
+});

package/jsdoc.json

@@ -0,0 +1,11 @@
+{
+  "source": {
+    "include": ["src"],
+    "includePattern": ".+\\.js$"
+  },
+  "opts": {
+    "destination": "docs-api",
+    "readme": "README.md",
+    "recurse": true
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",
@@ -19,6 +19,7 @@
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "docs:api": "jsdoc -c jsdoc.json",
     "check:duplication": "jscpd .",
     "check": "npm run lint && npm run format:check && npm run check:duplication",
     "prepare": "husky || true",
@@ -69,6 +70,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "husky": "^9.1.7",
+    "jsdoc": "^4.0.4",
     "jscpd": "^4.0.5",
     "lint-staged": "^16.2.6",
     "playwright": "^1.56.1",

package/src/bindings.js

@@ -53,6 +53,7 @@ import {
   checkAndClearFlag,
   findToggleButton,
 } from './high-level/universal-logic.js';
+import { pdf } from './browser/pdf.js';
 import { pressKey, typeText, keyDown, keyUp } from './interactions/keyboard.js';
 
 /**
@@ -215,6 +216,9 @@ export function createBoundFunctions(options = {}) {
       findByText: findByTextBound,
     });
 
+  // Bound pdf generation
+  const pdfBound = (opts = {}) => pdf({ ...opts, page, engine });
+
   // Bound keyboard
   const pressKeyBound = (opts) => pressKey({ ...opts, page, engine });
   const typeTextBound = (opts) => typeText({ ...opts, page, engine });
@@ -307,6 +311,9 @@ export function createBoundFunctions(options = {}) {
     checkAndClearFlag: checkAndClearFlagBound,
     findToggleButton: findToggleButtonBound,
 
+    // PDF generation
+    pdf: pdfBound,
+
     // Page-level keyboard interaction
     // Usage: await commander.keyboard.press('Escape')
     keyboard: {

package/src/browser/navigation.js

@@ -220,7 +220,7 @@ export async function waitForUrlStabilization(options = {}) {
  * @param {boolean} options.verify - Whether to verify the navigation (default: true)
  * @param {Function} options.verifyFn - Custom verification function (optional)
  * @param {number} options.verificationTimeout - Verification timeout in ms (default: TIMING.VERIFICATION_TIMEOUT)
- * @returns {Promise<{navigated: boolean, verified: boolean, actualUrl?: string, reason?: string}>}
+ * @returns {Promise<Object>} Navigation result.
  */
 export async function goto(options = {}) {
   const {

package/src/browser/pdf.js

@@ -0,0 +1,31 @@
+/**
+ * PDF generation support
+ *
+ * Wraps Playwright/Puppeteer's page.pdf() method behind a unified interface.
+ * Both engines expose identical options: format, printBackground, margin, etc.
+ *
+ * Note: PDF generation only works in Chromium headless mode.
+ * Playwright Firefox and WebKit do not support page.pdf().
+ */
+
+import { createEngineAdapter } from '../core/engine-adapter.js';
+
+/**
+ * Generate a PDF of the current page
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Playwright or Puppeteer page object
+ * @param {string} options.engine - Engine type ('playwright' or 'puppeteer')
+ * @param {Object} options.pdfOptions - PDF generation options passed to the engine
+ * @param {string} [options.pdfOptions.format] - Paper format (e.g. 'A4', 'Letter')
+ * @param {boolean} [options.pdfOptions.printBackground] - Print background graphics
+ * @param {Object} [options.pdfOptions.margin] - Page margins { top, right, bottom, left }
+ * @param {string} [options.pdfOptions.path] - File path to save the PDF (optional)
+ * @param {string} [options.pdfOptions.scale] - Scale of the webpage rendering (0.1–2)
+ * @returns {Promise<Buffer>} - PDF as a Buffer
+ */
+export async function pdf(options = {}) {
+  const { page, engine, pdfOptions = {} } = options;
+  const adapter = createEngineAdapter(page, engine);
+  return await adapter.pdf(pdfOptions);
+}

package/src/core/engine-adapter.js

@@ -237,6 +237,15 @@ export class EngineAdapter {
   getMainFrame() {
     throw new Error('getMainFrame() must be implemented by subclass');
   }
+
+  /**
+   * Generate a PDF of the current page
+   * @param {Object} options - PDF options (format, printBackground, margin, etc.)
+   * @returns {Promise<Buffer>} - PDF buffer
+   */
+  async pdf(options = {}) {
+    throw new Error('pdf() must be implemented by subclass');
+  }
 }
 
 /**
@@ -389,6 +398,10 @@ export class PlaywrightAdapter extends EngineAdapter {
   getMainFrame() {
     return this.page.mainFrame();
   }
+
+  async pdf(options = {}) {
+    return await this.page.pdf(options);
+  }
 }
 
 /**
@@ -525,6 +538,10 @@ export class PuppeteerAdapter extends EngineAdapter {
   getMainFrame() {
     return this.page.mainFrame();
   }
+
+  async pdf(options = {}) {
+    return await this.page.pdf(options);
+  }
 }
 
 /**

package/src/exports.js

@@ -55,6 +55,8 @@ export {
   verifyNavigation,
 } from './browser/navigation.js';
 
+export { pdf } from './browser/pdf.js';
+
 // Re-export element operations
 export {
   createPlaywrightLocator,

package/src/interactions/click.js

@@ -173,7 +173,7 @@ export async function verifyClick(options = {}) {
  * @param {boolean} options.verify - Whether to verify the click operation (default: true)
  * @param {Function} options.verifyFn - Custom verification function (optional)
  * @param {Object} options.adapter - Engine adapter (optional, will be created if not provided)
- * @returns {Promise<{clicked: boolean, verified: boolean, reason?: string}>}
+ * @returns {Promise<Object>} Click result.
  */
 export async function clickElement(options = {}) {
   const {
@@ -352,7 +352,7 @@ async function prepareElement(options = {}) {
  * @param {boolean} options.noAutoScroll - Prevent Playwright's automatic scrolling
  * @param {boolean} options.verify - Whether to verify the click operation
  * @param {Function} options.verifyFn - Custom verification function (optional)
- * @returns {Promise<{clicked: boolean, verified: boolean, reason?: string, navigated: boolean}>}
+ * @returns {Promise<Object>} Click result.
  */
 async function executeClick(options = {}) {
   const {
@@ -567,7 +567,7 @@ async function handleNavigationAfterClick(options = {}) {
  * @param {number} options.timeout - Timeout in ms (default: TIMING.DEFAULT_TIMEOUT)
  * @param {boolean} options.verify - Whether to verify the click operation (default: true)
  * @param {Function} options.verifyFn - Custom verification function (optional)
- * @returns {Promise<{clicked: boolean, navigated: boolean, verified: boolean, reason?: string}>}
+ * @returns {Promise<Object>} Click result.
  *   - clicked: true if click was performed
  *   - navigated: true if click caused navigation
  *   - verified: true if click was verified (navigation counts as verification)

package/src/interactions/fill.js

@@ -146,7 +146,7 @@ export async function checkIfElementEmpty(options = {}) {
  * @param {number} options.verificationTimeout - Verification timeout in ms (default: TIMING.VERIFICATION_TIMEOUT)
  * @param {Function} options.log - Logger instance (optional)
  * @param {Object} options.adapter - Engine adapter (optional, will be created if not provided)
- * @returns {Promise<{filled: boolean, verified: boolean, actualValue?: string}>}
+ * @returns {Promise<Object>} Fill result.
  */
 export async function performFill(options = {}) {
   const {
@@ -240,7 +240,7 @@ export async function performFill(options = {}) {
  * @param {boolean} options.verify - Whether to verify the fill operation (default: true)
  * @param {Function} options.verifyFn - Custom verification function (optional, uses defaultFillVerification if not provided)
  * @param {number} options.verificationTimeout - Verification timeout in ms (default: TIMING.VERIFICATION_TIMEOUT)
- * @returns {Promise<{filled: boolean, verified: boolean, skipped: boolean, actualValue?: string}>}
+ * @returns {Promise<Object>} Fill result.
  *   - filled: true if fill operation was attempted
  *   - verified: true if fill was verified successfully (only meaningful if filled is true)
  *   - skipped: true if element already had content and checkEmpty was true

package/tests/helpers/mocks.js

@@ -152,6 +152,7 @@ export function createMockPlaywrightPage(options = {}) {
       down: async (key) => {},
       up: async (key) => {},
     },
+    pdf: async (opts = {}) => Buffer.from('%PDF-1.4 mock playwright'),
   };
 }
 
@@ -312,6 +313,7 @@ export function createMockPuppeteerPage(options = {}) {
       down: async (key) => {},
       up: async (key) => {},
     },
+    pdf: async (opts = {}) => Buffer.from('%PDF-1.4 mock puppeteer'),
   };
 
   return page;

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

@@ -0,0 +1,80 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { pdf } from '../../../src/browser/pdf.js';
+import {
+  createMockPlaywrightPage,
+  createMockPuppeteerPage,
+} from '../../helpers/mocks.js';
+
+describe('browser/pdf', () => {
+  describe('pdf() with Playwright engine', () => {
+    it('should return a Buffer', async () => {
+      const page = createMockPlaywrightPage();
+      const result = await pdf({ page, engine: 'playwright' });
+      assert.ok(result instanceof Buffer || result instanceof Uint8Array);
+    });
+
+    it('should pass pdf options to the underlying page', async () => {
+      const capturedOptions = {};
+      const page = createMockPlaywrightPage();
+      page.pdf = async (opts = {}) => {
+        Object.assign(capturedOptions, opts);
+        return Buffer.from('%PDF-1.4');
+      };
+
+      await pdf({
+        page,
+        engine: 'playwright',
+        pdfOptions: {
+          format: 'A4',
+          printBackground: true,
+          margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' },
+        },
+      });
+
+      assert.strictEqual(capturedOptions.format, 'A4');
+      assert.strictEqual(capturedOptions.printBackground, true);
+      assert.deepStrictEqual(capturedOptions.margin, {
+        top: '1cm',
+        right: '1cm',
+        bottom: '1cm',
+        left: '1cm',
+      });
+    });
+
+    it('should work with empty options', async () => {
+      const page = createMockPlaywrightPage();
+      const result = await pdf({ page, engine: 'playwright', pdfOptions: {} });
+      assert.ok(result);
+    });
+  });
+
+  describe('pdf() with Puppeteer engine', () => {
+    it('should return a Buffer', async () => {
+      const page = createMockPuppeteerPage();
+      const result = await pdf({ page, engine: 'puppeteer' });
+      assert.ok(result instanceof Buffer || result instanceof Uint8Array);
+    });
+
+    it('should pass pdf options to the underlying page', async () => {
+      const capturedOptions = {};
+      const page = createMockPuppeteerPage();
+      page.pdf = async (opts = {}) => {
+        Object.assign(capturedOptions, opts);
+        return Buffer.from('%PDF-1.4');
+      };
+
+      await pdf({
+        page,
+        engine: 'puppeteer',
+        pdfOptions: {
+          format: 'Letter',
+          printBackground: false,
+        },
+      });
+
+      assert.strictEqual(capturedOptions.format, 'Letter');
+      assert.strictEqual(capturedOptions.printBackground, false);
+    });
+  });
+});

package/tests/unit/core/engine-adapter.test.js

@@ -215,6 +215,27 @@ describe('engine-adapter', () => {
     });
   });
 
+  describe('pdf()', () => {
+    it('PlaywrightAdapter.pdf() should return a Buffer', async () => {
+      const page = createMockPlaywrightPage();
+      const adapter = new PlaywrightAdapter(page);
+      const result = await adapter.pdf({ format: 'A4', printBackground: true });
+      assert.ok(result instanceof Buffer || result instanceof Uint8Array);
+    });
+
+    it('PuppeteerAdapter.pdf() should return a Buffer', async () => {
+      const page = createMockPuppeteerPage();
+      const adapter = new PuppeteerAdapter(page);
+      const result = await adapter.pdf({ format: 'A4', printBackground: true });
+      assert.ok(result instanceof Buffer || result instanceof Uint8Array);
+    });
+
+    it('EngineAdapter base class pdf() should throw', async () => {
+      const adapter = new EngineAdapter({});
+      await assert.rejects(async () => adapter.pdf({}), /must be implemented/);
+    });
+  });
+
   describe('createEngineAdapter', () => {
     it('should create PlaywrightAdapter for playwright engine', () => {
       const page = createMockPlaywrightPage();