browser-commander 0.7.0 → 0.8.0

package/CHANGELOG.md

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

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.7.0",
+  "version": "0.8.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

@@ -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/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/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();