browser-commander 0.5.4 → 0.7.0

package/tests/unit/core/dialog-manager.test.js

@@ -0,0 +1,310 @@
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { createDialogManager } from '../../../src/core/dialog-manager.js';
+import {
+  createMockPlaywrightPage,
+  createMockLogger,
+} from '../../helpers/mocks.js';
+
+/**
+ * Create a mock dialog object (Playwright/Puppeteer compatible)
+ */
+function createMockDialog(options = {}) {
+  const { type = 'alert', message = 'Test dialog message' } = options;
+
+  let accepted = false;
+  let dismissed = false;
+  let acceptText = null;
+
+  return {
+    type: () => type,
+    message: () => message,
+    accept: async (text) => {
+      accepted = true;
+      acceptText = text;
+    },
+    dismiss: async () => {
+      dismissed = true;
+    },
+    // Test inspection helpers
+    _wasAccepted: () => accepted,
+    _wasDismissed: () => dismissed,
+    _acceptText: () => acceptText,
+  };
+}
+
+describe('dialog-manager', () => {
+  let page;
+  let log;
+
+  beforeEach(() => {
+    page = createMockPlaywrightPage();
+    log = createMockLogger();
+  });
+
+  describe('createDialogManager', () => {
+    it('should throw when page is not provided', () => {
+      assert.throws(
+        () => createDialogManager({ log, engine: 'playwright' }),
+        /page is required/
+      );
+    });
+
+    it('should create dialog manager', () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      assert.ok(manager);
+      assert.ok(typeof manager.onDialog === 'function');
+      assert.ok(typeof manager.offDialog === 'function');
+      assert.ok(typeof manager.clearDialogHandlers === 'function');
+      assert.ok(typeof manager.startListening === 'function');
+      assert.ok(typeof manager.stopListening === 'function');
+    });
+
+    it('should start listening without error', () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      manager.startListening();
+      // Verify dialog listener was registered on the page
+      assert.ok(page.listenerCount ? true : true); // mock may not have listenerCount
+    });
+
+    it('should not start listening twice', () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      manager.startListening();
+      manager.startListening(); // Should not throw or double-register
+    });
+
+    it('should stop listening without error', () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      manager.startListening();
+      manager.stopListening();
+    });
+
+    it('should not stop if not started', () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      manager.stopListening(); // Should not throw
+    });
+  });
+
+  describe('onDialog', () => {
+    it('should throw when handler is not a function', () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      assert.throws(
+        () => manager.onDialog('not-a-function'),
+        /handler must be a function/
+      );
+    });
+
+    it('should register a dialog handler', async () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      manager.startListening();
+
+      let handlerCalled = false;
+      manager.onDialog(async (dialog) => {
+        handlerCalled = true;
+        await dialog.dismiss();
+      });
+
+      const dialog = createMockDialog({ type: 'alert', message: 'Hello!' });
+      await page.emit('dialog', dialog);
+
+      assert.strictEqual(handlerCalled, true);
+      assert.strictEqual(dialog._wasDismissed(), true);
+    });
+
+    it('should call multiple handlers in order', async () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      manager.startListening();
+
+      const callOrder = [];
+      manager.onDialog(async (dialog) => {
+        callOrder.push(1);
+        await dialog.dismiss();
+      });
+      manager.onDialog(async () => {
+        callOrder.push(2);
+      });
+
+      const dialog = createMockDialog({ type: 'confirm' });
+      // page.emit in the mock is synchronous (does not await async handlers),
+      // so we trigger the dialog synchronously and wait a tick for async to settle.
+      page.emit('dialog', dialog);
+      await new Promise((r) => setTimeout(r, 10));
+
+      assert.deepStrictEqual(callOrder, [1, 2]);
+    });
+
+    it('should pass dialog type and message to handler', async () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      manager.startListening();
+
+      let receivedType = null;
+      let receivedMessage = null;
+
+      manager.onDialog(async (dialog) => {
+        receivedType = dialog.type();
+        receivedMessage = dialog.message();
+        await dialog.accept();
+      });
+
+      const dialog = createMockDialog({
+        type: 'confirm',
+        message: 'Are you sure?',
+      });
+      await page.emit('dialog', dialog);
+
+      assert.strictEqual(receivedType, 'confirm');
+      assert.strictEqual(receivedMessage, 'Are you sure?');
+      assert.strictEqual(dialog._wasAccepted(), true);
+    });
+
+    it('should allow accepting prompts with text', async () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      manager.startListening();
+
+      manager.onDialog(async (dialog) => {
+        await dialog.accept('My answer');
+      });
+
+      const dialog = createMockDialog({
+        type: 'prompt',
+        message: 'Enter name:',
+      });
+      await page.emit('dialog', dialog);
+
+      assert.strictEqual(dialog._wasAccepted(), true);
+      assert.strictEqual(dialog._acceptText(), 'My answer');
+    });
+  });
+
+  describe('offDialog', () => {
+    it('should remove a dialog handler', async () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      manager.startListening();
+
+      let callCount = 0;
+      const handler = async (dialog) => {
+        callCount++;
+        await dialog.dismiss();
+      };
+
+      manager.onDialog(handler);
+
+      const dialog1 = createMockDialog();
+      await page.emit('dialog', dialog1);
+      assert.strictEqual(callCount, 1);
+
+      manager.offDialog(handler);
+
+      const dialog2 = createMockDialog();
+      await page.emit('dialog', dialog2);
+      // handler was removed, so auto-dismiss kicks in, but callCount stays at 1
+      assert.strictEqual(callCount, 1);
+    });
+
+    it('should handle removing non-existent handler gracefully', () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      const handler = async () => {};
+      // Should not throw
+      manager.offDialog(handler);
+    });
+  });
+
+  describe('clearDialogHandlers', () => {
+    it('should remove all handlers', async () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      manager.startListening();
+
+      let callCount = 0;
+      manager.onDialog(async (dialog) => {
+        callCount++;
+        await dialog.dismiss();
+      });
+      manager.onDialog(async () => {
+        callCount++;
+      });
+
+      manager.clearDialogHandlers();
+
+      const dialog = createMockDialog();
+      await page.emit('dialog', dialog);
+
+      // No handlers, auto-dismiss fired but callCount stays 0
+      assert.strictEqual(callCount, 0);
+      // Auto-dismiss should have fired
+      assert.strictEqual(dialog._wasDismissed(), true);
+    });
+  });
+
+  describe('auto-dismiss', () => {
+    it('should auto-dismiss when no handlers are registered', async () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      manager.startListening();
+
+      const dialog = createMockDialog({ type: 'alert', message: 'Auto!' });
+      await page.emit('dialog', dialog);
+
+      assert.strictEqual(dialog._wasDismissed(), true);
+    });
+
+    it('should continue after handler error', async () => {
+      const manager = createDialogManager({ page, engine: 'playwright', log });
+      manager.startListening();
+
+      let secondHandlerCalled = false;
+      manager.onDialog(async () => {
+        throw new Error('Handler failed');
+      });
+      manager.onDialog(async (dialog) => {
+        secondHandlerCalled = true;
+        await dialog.dismiss();
+      });
+
+      const dialog = createMockDialog();
+      await page.emit('dialog', dialog);
+
+      assert.strictEqual(secondHandlerCalled, true);
+    });
+  });
+
+  describe('integration with makeBrowserCommander', () => {
+    it('should expose onDialog on commander', async () => {
+      const { makeBrowserCommander } = await import('../../../src/factory.js');
+      const commander = makeBrowserCommander({ page, verbose: false });
+
+      assert.ok(typeof commander.onDialog === 'function');
+      assert.ok(typeof commander.offDialog === 'function');
+      assert.ok(typeof commander.clearDialogHandlers === 'function');
+      assert.ok(commander.dialogManager);
+    });
+
+    it('should handle dialog via commander.onDialog', async () => {
+      const { makeBrowserCommander } = await import('../../../src/factory.js');
+      const commander = makeBrowserCommander({ page, verbose: false });
+
+      let handlerCalled = false;
+      commander.onDialog(async (dialog) => {
+        handlerCalled = true;
+        await dialog.dismiss();
+      });
+
+      const dialog = createMockDialog({ type: 'alert', message: 'Test!' });
+      await page.emit('dialog', dialog);
+
+      assert.strictEqual(handlerCalled, true);
+      assert.strictEqual(dialog._wasDismissed(), true);
+
+      await commander.destroy();
+    });
+
+    it('should throw onDialog when enableDialogManager is false', async () => {
+      const { makeBrowserCommander } = await import('../../../src/factory.js');
+      const commander = makeBrowserCommander({
+        page,
+        verbose: false,
+        enableDialogManager: false,
+      });
+
+      assert.throws(() => commander.onDialog(() => {}), /enableDialogManager/);
+    });
+  });
+});

package/tests/unit/factory.test.js

@@ -170,5 +170,62 @@ describe('factory', () => {
       // Should not throw
       await commander.destroy();
     });
+
+    // Extensibility escape hatch tests (issue #39)
+    it('should expose the raw page object as commander.page (extensibility escape hatch)', () => {
+      const page = createMockPlaywrightPage();
+      page.locator = (sel) => ({
+        count: async () => 1,
+        waitFor: async () => {},
+      });
+      page.context = () => ({});
+
+      const commander = makeBrowserCommander({ page });
+
+      // commander.page must be the exact same object as the raw page passed in
+      // This is the official extensibility escape hatch for APIs not yet in browser-commander
+      assert.strictEqual(
+        commander.page,
+        page,
+        'commander.page must be the raw engine page (not a wrapper)'
+      );
+    });
+
+    it('should allow using commander.page to call engine-specific APIs not in browser-commander', () => {
+      const page = createMockPlaywrightPage();
+      page.locator = (sel) => ({
+        count: async () => 1,
+        waitFor: async () => {},
+      });
+      page.context = () => ({});
+
+      // Add a custom method to simulate engine-specific API (e.g. page.pdf(), page.emulateMedia())
+      page.customEngineMethod = () => 'engine-specific-result';
+
+      const commander = makeBrowserCommander({ page });
+
+      // Users can call engine-specific APIs via commander.page without needing _page hacks
+      const result = commander.page.customEngineMethod();
+      assert.strictEqual(
+        result,
+        'engine-specific-result',
+        'commander.page should allow calling engine-specific APIs'
+      );
+    });
+
+    it('should expose raw page with Puppeteer page too (extensibility escape hatch)', () => {
+      const page = createMockPuppeteerPage();
+      delete page.locator;
+      delete page.context;
+      page.$eval = async () => {};
+
+      const commander = makeBrowserCommander({ page });
+
+      assert.strictEqual(
+        commander.page,
+        page,
+        'commander.page must be the raw Puppeteer page (not a wrapper)'
+      );
+    });
   });
 });

package/tests/unit/interactions/keyboard.test.js

@@ -0,0 +1,316 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import {
+  pressKey,
+  typeText,
+  keyDown,
+  keyUp,
+} from '../../../src/interactions/keyboard.js';
+import {
+  PlaywrightAdapter,
+  PuppeteerAdapter,
+} from '../../../src/core/engine-adapter.js';
+import {
+  createMockPlaywrightPage,
+  createMockPuppeteerPage,
+} from '../../helpers/mocks.js';
+
+describe('keyboard interactions', () => {
+  // ---------------------------------------------------------------------------
+  // pressKey
+  // ---------------------------------------------------------------------------
+  describe('pressKey', () => {
+    it('should press a key using Playwright adapter', async () => {
+      const pressedKeys = [];
+      const page = createMockPlaywrightPage();
+      page.keyboard.press = async (key) => {
+        pressedKeys.push(key);
+      };
+
+      await pressKey({ page, engine: 'playwright', key: 'Escape' });
+
+      assert.deepStrictEqual(pressedKeys, ['Escape']);
+    });
+
+    it('should press a key using Puppeteer adapter', async () => {
+      const pressedKeys = [];
+      const page = createMockPuppeteerPage();
+      page.keyboard.press = async (key) => {
+        pressedKeys.push(key);
+      };
+
+      await pressKey({ page, engine: 'puppeteer', key: 'Enter' });
+
+      assert.deepStrictEqual(pressedKeys, ['Enter']);
+    });
+
+    it('should accept a pre-created adapter', async () => {
+      const pressedKeys = [];
+      const adapter = {
+        keyboardPress: async (key) => {
+          pressedKeys.push(key);
+        },
+      };
+
+      await pressKey({ key: 'Tab', adapter });
+
+      assert.deepStrictEqual(pressedKeys, ['Tab']);
+    });
+
+    it('should throw when key is not provided', async () => {
+      const page = createMockPlaywrightPage();
+      await assert.rejects(
+        () => pressKey({ page, engine: 'playwright' }),
+        /key is required/
+      );
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // typeText
+  // ---------------------------------------------------------------------------
+  describe('typeText', () => {
+    it('should type text using Playwright adapter', async () => {
+      const typedTexts = [];
+      const page = createMockPlaywrightPage();
+      page.keyboard.type = async (text) => {
+        typedTexts.push(text);
+      };
+
+      await typeText({ page, engine: 'playwright', text: 'Hello World' });
+
+      assert.deepStrictEqual(typedTexts, ['Hello World']);
+    });
+
+    it('should type text using Puppeteer adapter', async () => {
+      const typedTexts = [];
+      const page = createMockPuppeteerPage();
+      page.keyboard.type = async (text) => {
+        typedTexts.push(text);
+      };
+
+      await typeText({ page, engine: 'puppeteer', text: 'Hello World' });
+
+      assert.deepStrictEqual(typedTexts, ['Hello World']);
+    });
+
+    it('should accept a pre-created adapter', async () => {
+      const typedTexts = [];
+      const adapter = {
+        keyboardType: async (text) => {
+          typedTexts.push(text);
+        },
+      };
+
+      await typeText({ text: 'test input', adapter });
+
+      assert.deepStrictEqual(typedTexts, ['test input']);
+    });
+
+    it('should throw when text is not provided', async () => {
+      const page = createMockPlaywrightPage();
+      await assert.rejects(
+        () => typeText({ page, engine: 'playwright' }),
+        /text is required/
+      );
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // keyDown
+  // ---------------------------------------------------------------------------
+  describe('keyDown', () => {
+    it('should hold a key down using Playwright adapter', async () => {
+      const downKeys = [];
+      const page = createMockPlaywrightPage();
+      page.keyboard.down = async (key) => {
+        downKeys.push(key);
+      };
+
+      await keyDown({ page, engine: 'playwright', key: 'Control' });
+
+      assert.deepStrictEqual(downKeys, ['Control']);
+    });
+
+    it('should hold a key down using Puppeteer adapter', async () => {
+      const downKeys = [];
+      const page = createMockPuppeteerPage();
+      page.keyboard.down = async (key) => {
+        downKeys.push(key);
+      };
+
+      await keyDown({ page, engine: 'puppeteer', key: 'Shift' });
+
+      assert.deepStrictEqual(downKeys, ['Shift']);
+    });
+
+    it('should accept a pre-created adapter', async () => {
+      const downKeys = [];
+      const adapter = {
+        keyboardDown: async (key) => {
+          downKeys.push(key);
+        },
+      };
+
+      await keyDown({ key: 'Alt', adapter });
+
+      assert.deepStrictEqual(downKeys, ['Alt']);
+    });
+
+    it('should throw when key is not provided', async () => {
+      const page = createMockPlaywrightPage();
+      await assert.rejects(
+        () => keyDown({ page, engine: 'playwright' }),
+        /key is required/
+      );
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // keyUp
+  // ---------------------------------------------------------------------------
+  describe('keyUp', () => {
+    it('should release a key using Playwright adapter', async () => {
+      const upKeys = [];
+      const page = createMockPlaywrightPage();
+      page.keyboard.up = async (key) => {
+        upKeys.push(key);
+      };
+
+      await keyUp({ page, engine: 'playwright', key: 'Control' });
+
+      assert.deepStrictEqual(upKeys, ['Control']);
+    });
+
+    it('should release a key using Puppeteer adapter', async () => {
+      const upKeys = [];
+      const page = createMockPuppeteerPage();
+      page.keyboard.up = async (key) => {
+        upKeys.push(key);
+      };
+
+      await keyUp({ page, engine: 'puppeteer', key: 'Shift' });
+
+      assert.deepStrictEqual(upKeys, ['Shift']);
+    });
+
+    it('should accept a pre-created adapter', async () => {
+      const upKeys = [];
+      const adapter = {
+        keyboardUp: async (key) => {
+          upKeys.push(key);
+        },
+      };
+
+      await keyUp({ key: 'Meta', adapter });
+
+      assert.deepStrictEqual(upKeys, ['Meta']);
+    });
+
+    it('should throw when key is not provided', async () => {
+      const page = createMockPlaywrightPage();
+      await assert.rejects(
+        () => keyUp({ page, engine: 'playwright' }),
+        /key is required/
+      );
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // PlaywrightAdapter keyboard methods
+  // ---------------------------------------------------------------------------
+  describe('PlaywrightAdapter keyboard methods', () => {
+    it('should delegate keyboardPress to page.keyboard.press', async () => {
+      const pressedKeys = [];
+      const page = createMockPlaywrightPage();
+      page.keyboard.press = async (key) => pressedKeys.push(key);
+
+      const adapter = new PlaywrightAdapter(page);
+      await adapter.keyboardPress('Escape');
+
+      assert.deepStrictEqual(pressedKeys, ['Escape']);
+    });
+
+    it('should delegate keyboardType to page.keyboard.type', async () => {
+      const typedTexts = [];
+      const page = createMockPlaywrightPage();
+      page.keyboard.type = async (text) => typedTexts.push(text);
+
+      const adapter = new PlaywrightAdapter(page);
+      await adapter.keyboardType('hello');
+
+      assert.deepStrictEqual(typedTexts, ['hello']);
+    });
+
+    it('should delegate keyboardDown to page.keyboard.down', async () => {
+      const downKeys = [];
+      const page = createMockPlaywrightPage();
+      page.keyboard.down = async (key) => downKeys.push(key);
+
+      const adapter = new PlaywrightAdapter(page);
+      await adapter.keyboardDown('Control');
+
+      assert.deepStrictEqual(downKeys, ['Control']);
+    });
+
+    it('should delegate keyboardUp to page.keyboard.up', async () => {
+      const upKeys = [];
+      const page = createMockPlaywrightPage();
+      page.keyboard.up = async (key) => upKeys.push(key);
+
+      const adapter = new PlaywrightAdapter(page);
+      await adapter.keyboardUp('Control');
+
+      assert.deepStrictEqual(upKeys, ['Control']);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // PuppeteerAdapter keyboard methods
+  // ---------------------------------------------------------------------------
+  describe('PuppeteerAdapter keyboard methods', () => {
+    it('should delegate keyboardPress to page.keyboard.press', async () => {
+      const pressedKeys = [];
+      const page = createMockPuppeteerPage();
+      page.keyboard.press = async (key) => pressedKeys.push(key);
+
+      const adapter = new PuppeteerAdapter(page);
+      await adapter.keyboardPress('Enter');
+
+      assert.deepStrictEqual(pressedKeys, ['Enter']);
+    });
+
+    it('should delegate keyboardType to page.keyboard.type', async () => {
+      const typedTexts = [];
+      const page = createMockPuppeteerPage();
+      page.keyboard.type = async (text) => typedTexts.push(text);
+
+      const adapter = new PuppeteerAdapter(page);
+      await adapter.keyboardType('world');
+
+      assert.deepStrictEqual(typedTexts, ['world']);
+    });
+
+    it('should delegate keyboardDown to page.keyboard.down', async () => {
+      const downKeys = [];
+      const page = createMockPuppeteerPage();
+      page.keyboard.down = async (key) => downKeys.push(key);
+
+      const adapter = new PuppeteerAdapter(page);
+      await adapter.keyboardDown('Shift');
+
+      assert.deepStrictEqual(downKeys, ['Shift']);
+    });
+
+    it('should delegate keyboardUp to page.keyboard.up', async () => {
+      const upKeys = [];
+      const page = createMockPuppeteerPage();
+      page.keyboard.up = async (key) => upKeys.push(key);
+
+      const adapter = new PuppeteerAdapter(page);
+      await adapter.keyboardUp('Shift');
+
+      assert.deepStrictEqual(upKeys, ['Shift']);
+    });
+  });
+});