browser-commander 0.5.4 → 0.7.0

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,7 +147,10 @@ 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) => {},
     },
   };
 }
@@ -304,7 +307,10 @@ 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) => {},
     },
   };
 

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

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

@@ -0,0 +1,176 @@
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { emulateMedia } from '../../../src/browser/media.js';
+
+describe('emulateMedia', () => {
+  describe('input validation', () => {
+    it('should throw if page is not provided', async () => {
+      await assert.rejects(
+        () => emulateMedia({ engine: 'playwright', colorScheme: 'dark' }),
+        /page is required/
+      );
+    });
+
+    it('should throw if engine is not provided', async () => {
+      const mockPage = {};
+      await assert.rejects(
+        () => emulateMedia({ page: mockPage, colorScheme: 'dark' }),
+        /engine is required/
+      );
+    });
+
+    it('should throw for invalid colorScheme', async () => {
+      const mockPage = {};
+      await assert.rejects(
+        () =>
+          emulateMedia({
+            page: mockPage,
+            engine: 'playwright',
+            colorScheme: 'invalid',
+          }),
+        /Invalid colorScheme/
+      );
+    });
+
+    it('should throw for unsupported engine', async () => {
+      const mockPage = {};
+      await assert.rejects(
+        () =>
+          emulateMedia({
+            page: mockPage,
+            engine: 'selenium',
+            colorScheme: 'dark',
+          }),
+        /Unsupported engine/
+      );
+    });
+  });
+
+  describe('Playwright engine', () => {
+    let capturedMediaOptions;
+    let mockPage;
+
+    beforeEach(() => {
+      capturedMediaOptions = null;
+      mockPage = {
+        emulateMedia: async (options) => {
+          capturedMediaOptions = options;
+        },
+      };
+    });
+
+    it('should call page.emulateMedia with colorScheme: dark', async () => {
+      await emulateMedia({
+        page: mockPage,
+        engine: 'playwright',
+        colorScheme: 'dark',
+      });
+      assert.deepStrictEqual(capturedMediaOptions, { colorScheme: 'dark' });
+    });
+
+    it('should call page.emulateMedia with colorScheme: light', async () => {
+      await emulateMedia({
+        page: mockPage,
+        engine: 'playwright',
+        colorScheme: 'light',
+      });
+      assert.deepStrictEqual(capturedMediaOptions, { colorScheme: 'light' });
+    });
+
+    it('should call page.emulateMedia with colorScheme: no-preference', async () => {
+      await emulateMedia({
+        page: mockPage,
+        engine: 'playwright',
+        colorScheme: 'no-preference',
+      });
+      assert.deepStrictEqual(capturedMediaOptions, {
+        colorScheme: 'no-preference',
+      });
+    });
+
+    it('should call page.emulateMedia with colorScheme: null to reset', async () => {
+      await emulateMedia({
+        page: mockPage,
+        engine: 'playwright',
+        colorScheme: null,
+      });
+      assert.deepStrictEqual(capturedMediaOptions, { colorScheme: null });
+    });
+
+    it('should call page.emulateMedia with empty options when no colorScheme given', async () => {
+      await emulateMedia({
+        page: mockPage,
+        engine: 'playwright',
+      });
+      assert.deepStrictEqual(capturedMediaOptions, {});
+    });
+  });
+
+  describe('Puppeteer engine', () => {
+    let capturedFeatures;
+    let mockPage;
+
+    beforeEach(() => {
+      capturedFeatures = null;
+      mockPage = {
+        emulateMediaFeatures: async (features) => {
+          capturedFeatures = features;
+        },
+      };
+    });
+
+    it('should call page.emulateMediaFeatures with dark colorScheme', async () => {
+      await emulateMedia({
+        page: mockPage,
+        engine: 'puppeteer',
+        colorScheme: 'dark',
+      });
+      assert.deepStrictEqual(capturedFeatures, [
+        { name: 'prefers-color-scheme', value: 'dark' },
+      ]);
+    });
+
+    it('should call page.emulateMediaFeatures with light colorScheme', async () => {
+      await emulateMedia({
+        page: mockPage,
+        engine: 'puppeteer',
+        colorScheme: 'light',
+      });
+      assert.deepStrictEqual(capturedFeatures, [
+        { name: 'prefers-color-scheme', value: 'light' },
+      ]);
+    });
+
+    it('should call page.emulateMediaFeatures with no-preference colorScheme', async () => {
+      await emulateMedia({
+        page: mockPage,
+        engine: 'puppeteer',
+        colorScheme: 'no-preference',
+      });
+      assert.deepStrictEqual(capturedFeatures, [
+        { name: 'prefers-color-scheme', value: 'no-preference' },
+      ]);
+    });
+
+    it('should reset by passing empty string when colorScheme is null', async () => {
+      await emulateMedia({
+        page: mockPage,
+        engine: 'puppeteer',
+        colorScheme: null,
+      });
+      assert.deepStrictEqual(capturedFeatures, [
+        { name: 'prefers-color-scheme', value: '' },
+      ]);
+    });
+
+    it('should reset by passing empty string when colorScheme is undefined', async () => {
+      await emulateMedia({
+        page: mockPage,
+        engine: 'puppeteer',
+      });
+      assert.deepStrictEqual(capturedFeatures, [
+        { name: 'prefers-color-scheme', value: '' },
+      ]);
+    });
+  });
+});