browser-commander 0.6.0 → 0.8.0

package/src/core/engine-adapter.js

@@ -176,6 +176,46 @@ export class EngineAdapter {
     throw new Error('focus() must be implemented by subclass');
   }
 
+  // ============================================================================
+  // Page-level Keyboard Operations
+  // ============================================================================
+
+  /**
+   * Press a key at the page level (e.g. 'Escape', 'Enter', 'Tab')
+   * @param {string} key - Key name (Playwright/Puppeteer key format)
+   * @returns {Promise<void>}
+   */
+  async keyboardPress(key) {
+    throw new Error('keyboardPress() must be implemented by subclass');
+  }
+
+  /**
+   * Type text at the page level (dispatches key events for each character)
+   * @param {string} text - Text to type
+   * @returns {Promise<void>}
+   */
+  async keyboardType(text) {
+    throw new Error('keyboardType() must be implemented by subclass');
+  }
+
+  /**
+   * Hold a key down at the page level
+   * @param {string} key - Key name
+   * @returns {Promise<void>}
+   */
+  async keyboardDown(key) {
+    throw new Error('keyboardDown() must be implemented by subclass');
+  }
+
+  /**
+   * Release a held key at the page level
+   * @param {string} key - Key name
+   * @returns {Promise<void>}
+   */
+  async keyboardUp(key) {
+    throw new Error('keyboardUp() must be implemented by subclass');
+  }
+
   // ============================================================================
   // Page-level Operations
   // ============================================================================
@@ -197,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');
+  }
 }
 
 /**
@@ -298,6 +347,26 @@ export class PlaywrightAdapter extends EngineAdapter {
     await locatorOrElement.focus();
   }
 
+  // ============================================================================
+  // Page-level Keyboard Operations
+  // ============================================================================
+
+  async keyboardPress(key) {
+    await this.page.keyboard.press(key);
+  }
+
+  async keyboardType(text) {
+    await this.page.keyboard.type(text);
+  }
+
+  async keyboardDown(key) {
+    await this.page.keyboard.down(key);
+  }
+
+  async keyboardUp(key) {
+    await this.page.keyboard.up(key);
+  }
+
   // ============================================================================
   // Page-level Operations
   // ============================================================================
@@ -329,6 +398,10 @@ export class PlaywrightAdapter extends EngineAdapter {
   getMainFrame() {
     return this.page.mainFrame();
   }
+
+  async pdf(options = {}) {
+    return await this.page.pdf(options);
+  }
 }
 
 /**
@@ -433,6 +506,26 @@ export class PuppeteerAdapter extends EngineAdapter {
     await locatorOrElement.focus();
   }
 
+  // ============================================================================
+  // Page-level Keyboard Operations
+  // ============================================================================
+
+  async keyboardPress(key) {
+    await this.page.keyboard.press(key);
+  }
+
+  async keyboardType(text) {
+    await this.page.keyboard.type(text);
+  }
+
+  async keyboardDown(key) {
+    await this.page.keyboard.down(key);
+  }
+
+  async keyboardUp(key) {
+    await this.page.keyboard.up(key);
+  }
+
   // ============================================================================
   // Page-level Operations
   // ============================================================================
@@ -445,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

@@ -20,6 +20,7 @@ export {
 export { createNetworkTracker } from './core/network-tracker.js';
 export { createNavigationManager } from './core/navigation-manager.js';
 export { createPageSessionFactory } from './core/page-session.js';
+export { createDialogManager } from './core/dialog-manager.js';
 
 // Re-export engine adapter
 export {
@@ -42,6 +43,7 @@ export {
 
 // Re-export browser management
 export { launchBrowser } from './browser/launcher.js';
+export { emulateMedia } from './browser/media.js';
 export {
   waitForUrlStabilization,
   goto,
@@ -53,6 +55,8 @@ export {
   verifyNavigation,
 } from './browser/navigation.js';
 
+export { pdf } from './browser/pdf.js';
+
 // Re-export element operations
 export {
   createPlaywrightLocator,
@@ -109,6 +113,8 @@ export {
   verifyFill,
 } from './interactions/fill.js';
 
+export { pressKey, typeText, keyDown, keyUp } from './interactions/keyboard.js';
+
 // Re-export utilities
 export { wait, evaluate, safeEvaluate } from './utilities/wait.js';
 export { getUrl, unfocusAddressBar } from './utilities/url.js';

package/src/factory.js

@@ -9,6 +9,7 @@ import { detectEngine } from './core/engine-detection.js';
 import { createNetworkTracker } from './core/network-tracker.js';
 import { createNavigationManager } from './core/navigation-manager.js';
 import { createPageSessionFactory } from './core/page-session.js';
+import { createDialogManager } from './core/dialog-manager.js';
 import {
   createPageTriggerManager,
   ActionStoppedError,
@@ -35,6 +36,7 @@ export function makeBrowserCommander(options = {}) {
     verbose = false,
     enableNetworkTracking = true,
     enableNavigationManager = true,
+    enableDialogManager = true,
   } = options;
 
   if (!page) {
@@ -61,6 +63,13 @@ export function makeBrowserCommander(options = {}) {
   let navigationManager = null;
   let sessionFactory = null;
 
+  // Create DialogManager if enabled
+  let dialogManager = null;
+  if (enableDialogManager) {
+    dialogManager = createDialogManager({ page, engine, log });
+    dialogManager.startListening();
+  }
+
   // PageTriggerManager (will be initialized after commander is created)
   let pageTriggerManager = null;
 
@@ -111,6 +120,9 @@ export function makeBrowserCommander(options = {}) {
     if (sessionFactory) {
       await sessionFactory.endAllSessions();
     }
+    if (dialogManager) {
+      dialogManager.stopListening();
+    }
   };
 
   // Build commander object
@@ -125,6 +137,7 @@ export function makeBrowserCommander(options = {}) {
     navigationManager,
     sessionFactory,
     pageTriggerManager,
+    dialogManager,
 
     // All bound functions
     ...boundFunctions,
@@ -172,6 +185,30 @@ export function makeBrowserCommander(options = {}) {
           throw new Error('pageTrigger requires enableNavigationManager: true');
         },
 
+    // Dialog event handling API
+    // Register a handler: commander.onDialog(async (dialog) => { await dialog.dismiss(); })
+    // dialog.type()     → 'alert' | 'confirm' | 'prompt' | 'beforeunload'
+    // dialog.message()  → The dialog message text
+    // dialog.accept(text?) → Accept/confirm (optional text for prompts)
+    // dialog.dismiss()  → Dismiss/cancel the dialog
+    onDialog: dialogManager
+      ? (fn) => dialogManager.onDialog(fn)
+      : () => {
+          throw new Error('onDialog requires enableDialogManager: true');
+        },
+    offDialog: dialogManager
+      ? (fn) => dialogManager.offDialog(fn)
+      : () => {
+          throw new Error('offDialog requires enableDialogManager: true');
+        },
+    clearDialogHandlers: dialogManager
+      ? () => dialogManager.clearDialogHandlers()
+      : () => {
+          throw new Error(
+            'clearDialogHandlers requires enableDialogManager: true'
+          );
+        },
+
     // URL condition helpers
     makeUrlCondition,
     allConditions,

package/src/interactions/keyboard.js

@@ -0,0 +1,91 @@
+import { createEngineAdapter } from '../core/engine-adapter.js';
+
+/**
+ * Press a key at the page level (e.g. 'Escape', 'Enter', 'Tab').
+ *
+ * Supported key names follow the Playwright/Puppeteer convention:
+ * https://playwright.dev/docs/api/class-keyboard#keyboard-press
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Browser page object
+ * @param {string} options.engine - Engine type ('playwright' or 'puppeteer')
+ * @param {string} options.key - Key to press (e.g. 'Escape', 'Enter', 'Tab', 'ArrowDown')
+ * @param {Object} [options.adapter] - Engine adapter (optional, created if not provided)
+ * @returns {Promise<void>}
+ */
+export async function pressKey(options = {}) {
+  const { page, engine, key, adapter: providedAdapter } = options;
+
+  if (!key) {
+    throw new Error('pressKey: key is required in options');
+  }
+
+  const adapter = providedAdapter || createEngineAdapter(page, engine);
+  await adapter.keyboardPress(key);
+}
+
+/**
+ * Type text at the page level (dispatches key events for each character).
+ * Unlike element-level fill/type, this sends keyboard events to whatever
+ * element is currently focused on the page.
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Browser page object
+ * @param {string} options.engine - Engine type ('playwright' or 'puppeteer')
+ * @param {string} options.text - Text to type
+ * @param {Object} [options.adapter] - Engine adapter (optional, created if not provided)
+ * @returns {Promise<void>}
+ */
+export async function typeText(options = {}) {
+  const { page, engine, text, adapter: providedAdapter } = options;
+
+  if (!text) {
+    throw new Error('typeText: text is required in options');
+  }
+
+  const adapter = providedAdapter || createEngineAdapter(page, engine);
+  await adapter.keyboardType(text);
+}
+
+/**
+ * Hold a key down at the page level.
+ * Must be paired with keyUp() to release the key.
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Browser page object
+ * @param {string} options.engine - Engine type ('playwright' or 'puppeteer')
+ * @param {string} options.key - Key to hold down
+ * @param {Object} [options.adapter] - Engine adapter (optional, created if not provided)
+ * @returns {Promise<void>}
+ */
+export async function keyDown(options = {}) {
+  const { page, engine, key, adapter: providedAdapter } = options;
+
+  if (!key) {
+    throw new Error('keyDown: key is required in options');
+  }
+
+  const adapter = providedAdapter || createEngineAdapter(page, engine);
+  await adapter.keyboardDown(key);
+}
+
+/**
+ * Release a held key at the page level.
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Browser page object
+ * @param {string} options.engine - Engine type ('playwright' or 'puppeteer')
+ * @param {string} options.key - Key to release
+ * @param {Object} [options.adapter] - Engine adapter (optional, created if not provided)
+ * @returns {Promise<void>}
+ */
+export async function keyUp(options = {}) {
+  const { page, engine, key, adapter: providedAdapter } = options;
+
+  if (!key) {
+    throw new Error('keyUp: key is required in options');
+  }
+
+  const adapter = providedAdapter || createEngineAdapter(page, engine);
+  await adapter.keyboardUp(key);
+}

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

@@ -438,5 +438,89 @@ describe(
         assert.ok(elements.length >= 4);
       });
     });
+
+    describe('Keyboard Interactions', () => {
+      it('should press Escape key to close modal', async () => {
+        if (!commander) {
+          return;
+        }
+
+        // Open modal
+        await commander.click({ selector: '[data-testid="btn-open-modal"]' });
+        await commander.wait({ ms: 100 });
+
+        // Verify modal is open
+        const modalOpen = await commander.isVisible({
+          selector: '[data-testid="modal"]',
+        });
+        assert.strictEqual(modalOpen, true);
+
+        // Close modal with Escape key
+        await commander.keyboard.press('Escape');
+        await commander.wait({ ms: 150 });
+
+        // Modal should be closed
+        const modalClosed = await commander.isVisible({
+          selector: '[data-testid="modal"]',
+        });
+        assert.strictEqual(modalClosed, false);
+      });
+
+      it('should type text at page level via keyboard.type', async () => {
+        if (!commander) {
+          return;
+        }
+
+        // Focus the name input
+        await commander.click({ selector: '[data-testid="input-name"]' });
+        await commander.wait({ ms: 50 });
+
+        // Clear and type via page-level keyboard
+        await page.fill('[data-testid="input-name"]', '');
+        await commander.keyboard.type('Keyboard Test');
+        await commander.wait({ ms: 50 });
+
+        const value = await commander.inputValue({
+          selector: '[data-testid="input-name"]',
+        });
+        assert.ok(value.includes('Keyboard Test'));
+      });
+
+      it('should support keyboard.press via pressKey flat function', async () => {
+        if (!commander) {
+          return;
+        }
+
+        // Open modal
+        await commander.click({ selector: '[data-testid="btn-open-modal"]' });
+        await commander.wait({ ms: 100 });
+
+        const modalOpen = await commander.isVisible({
+          selector: '[data-testid="modal"]',
+        });
+        assert.strictEqual(modalOpen, true);
+
+        // Close via flat pressKey
+        await commander.pressKey({ key: 'Escape' });
+        await commander.wait({ ms: 150 });
+
+        const modalClosed = await commander.isVisible({
+          selector: '[data-testid="modal"]',
+        });
+        assert.strictEqual(modalClosed, false);
+      });
+
+      it('should submit form via Enter key', async () => {
+        if (!commander) {
+          return;
+        }
+
+        // Focus submit button and press Enter
+        await page.focus('[data-testid="btn-increment"]');
+        await commander.keyboard.press('Enter');
+        await commander.wait({ ms: 100 });
+        // Test passes if no error is thrown
+      });
+    });
   }
 );

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

@@ -405,4 +405,75 @@ describe('E2E Tests - Puppeteer Engine', { skip: !process.env.RUN_E2E }, () => {
       assert.ok(elapsed >= 90, `Expected at least 90ms, got ${elapsed}`);
     });
   });
+
+  describe('Keyboard Interactions', () => {
+    it('should press Escape key to close modal', async () => {
+      if (!commander) {
+        return;
+      }
+
+      // Open modal
+      await commander.click({ selector: '[data-testid="btn-open-modal"]' });
+      await commander.wait({ ms: 100 });
+
+      // Verify modal is open
+      const modalOpen = await commander.isVisible({
+        selector: '[data-testid="modal"]',
+      });
+      assert.strictEqual(modalOpen, true);
+
+      // Close modal with Escape key
+      await commander.keyboard.press('Escape');
+      await commander.wait({ ms: 150 });
+
+      // Modal should be closed
+      const modalClosed = await commander.isVisible({
+        selector: '[data-testid="modal"]',
+      });
+      assert.strictEqual(modalClosed, false);
+    });
+
+    it('should type text at page level via keyboard.type', async () => {
+      if (!commander) {
+        return;
+      }
+
+      // Focus the name input
+      await commander.click({ selector: '[data-testid="input-name"]' });
+      await commander.wait({ ms: 50 });
+
+      // Type via page-level keyboard
+      await commander.keyboard.type('Keyboard Test');
+      await commander.wait({ ms: 50 });
+
+      const value = await commander.inputValue({
+        selector: '[data-testid="input-name"]',
+      });
+      assert.ok(value.includes('Keyboard Test'));
+    });
+
+    it('should support pressKey flat function', async () => {
+      if (!commander) {
+        return;
+      }
+
+      // Open modal
+      await commander.click({ selector: '[data-testid="btn-open-modal"]' });
+      await commander.wait({ ms: 100 });
+
+      const modalOpen = await commander.isVisible({
+        selector: '[data-testid="modal"]',
+      });
+      assert.strictEqual(modalOpen, true);
+
+      // Close via flat pressKey
+      await commander.pressKey({ key: 'Escape' });
+      await commander.wait({ ms: 150 });
+
+      const modalClosed = await commander.isVisible({
+        selector: '[data-testid="modal"]',
+      });
+      assert.strictEqual(modalClosed, false);
+    });
+  });
 });

package/tests/helpers/mocks.js

@@ -147,8 +147,12 @@ export function createMockPlaywrightPage(options = {}) {
     click: async (sel, opts = {}) => {},
     type: async (sel, text, opts = {}) => {},
     keyboard: {
+      press: async (key) => {},
       type: async (text) => {},
+      down: async (key) => {},
+      up: async (key) => {},
     },
+    pdf: async (opts = {}) => Buffer.from('%PDF-1.4 mock playwright'),
   };
 }
 
@@ -304,8 +308,12 @@ export function createMockPuppeteerPage(options = {}) {
     click: async (sel, opts = {}) => {},
     type: async (sel, text, opts = {}) => {},
     keyboard: {
+      press: async (key) => {},
       type: async (text) => {},
+      down: async (key) => {},
+      up: async (key) => {},
     },
+    pdf: async (opts = {}) => Buffer.from('%PDF-1.4 mock puppeteer'),
   };
 
   return page;

package/tests/unit/bindings.test.js

@@ -139,6 +139,46 @@ describe('bindings', () => {
         typeof bindings.evaluate === 'function',
         'evaluate should be a function'
       );
+
+      // Keyboard - flat functions
+      assert.ok(
+        typeof bindings.pressKey === 'function',
+        'pressKey should be a function'
+      );
+      assert.ok(
+        typeof bindings.typeText === 'function',
+        'typeText should be a function'
+      );
+      assert.ok(
+        typeof bindings.keyDown === 'function',
+        'keyDown should be a function'
+      );
+      assert.ok(
+        typeof bindings.keyUp === 'function',
+        'keyUp should be a function'
+      );
+
+      // Keyboard - object API
+      assert.ok(
+        bindings.keyboard && typeof bindings.keyboard === 'object',
+        'keyboard should be an object'
+      );
+      assert.ok(
+        typeof bindings.keyboard.press === 'function',
+        'keyboard.press should be a function'
+      );
+      assert.ok(
+        typeof bindings.keyboard.type === 'function',
+        'keyboard.type should be a function'
+      );
+      assert.ok(
+        typeof bindings.keyboard.down === 'function',
+        'keyboard.down should be a function'
+      );
+      assert.ok(
+        typeof bindings.keyboard.up === 'function',
+        'keyboard.up should be a function'
+      );
     });
 
     it('should pre-bind page and engine to functions', async () => {
@@ -200,6 +240,38 @@ describe('bindings', () => {
       assert.ok(bindings);
     });
 
+    it('should invoke keyboard.press via bound keyboard object', async () => {
+      const pressedKeys = [];
+      const page = createMockPlaywrightPage();
+      page.keyboard.press = async (key) => pressedKeys.push(key);
+      const log = createMockLogger();
+
+      const bindings = createBoundFunctions({
+        page,
+        engine: 'playwright',
+        log,
+      });
+
+      await bindings.keyboard.press('Escape');
+      assert.deepStrictEqual(pressedKeys, ['Escape']);
+    });
+
+    it('should invoke keyboard.type via bound keyboard object', async () => {
+      const typedTexts = [];
+      const page = createMockPlaywrightPage();
+      page.keyboard.type = async (text) => typedTexts.push(text);
+      const log = createMockLogger();
+
+      const bindings = createBoundFunctions({
+        page,
+        engine: 'playwright',
+        log,
+      });
+
+      await bindings.keyboard.type('hello world');
+      assert.deepStrictEqual(typedTexts, ['hello world']);
+    });
+
     it('should integrate with networkTracker when provided', () => {
       const page = createMockPlaywrightPage();
       const log = createMockLogger();