browser-commander 0.2.0

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

@@ -0,0 +1,170 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import {
+  EngineAdapter,
+  PlaywrightAdapter,
+  PuppeteerAdapter,
+  createEngineAdapter,
+} from '../../../src/core/engine-adapter.js';
+import {
+  createMockPlaywrightPage,
+  createMockPuppeteerPage,
+} from '../../helpers/mocks.js';
+
+describe('engine-adapter', () => {
+  describe('EngineAdapter (base class)', () => {
+    it('should throw on abstract methods', () => {
+      const adapter = new EngineAdapter({});
+
+      assert.throws(() => adapter.getEngineName(), /must be implemented/);
+      assert.throws(() => adapter.createLocator('sel'), /must be implemented/);
+    });
+  });
+
+  describe('PlaywrightAdapter', () => {
+    let page;
+    let adapter;
+
+    it('should create adapter', () => {
+      page = createMockPlaywrightPage();
+      adapter = new PlaywrightAdapter(page);
+      assert.ok(adapter);
+    });
+
+    it('should return playwright as engine name', () => {
+      page = createMockPlaywrightPage();
+      adapter = new PlaywrightAdapter(page);
+      assert.strictEqual(adapter.getEngineName(), 'playwright');
+    });
+
+    it('should create locator from selector', () => {
+      page = createMockPlaywrightPage();
+      adapter = new PlaywrightAdapter(page);
+      const locator = adapter.createLocator('button');
+      assert.ok(locator);
+    });
+
+    it('should handle :nth-of-type selector', () => {
+      page = createMockPlaywrightPage();
+      adapter = new PlaywrightAdapter(page);
+      const locator = adapter.createLocator('button:nth-of-type(2)');
+      assert.ok(locator);
+    });
+
+    it('should query single element', async () => {
+      page = createMockPlaywrightPage({ elements: { button: { count: 1 } } });
+      adapter = new PlaywrightAdapter(page);
+      const element = await adapter.querySelector('button');
+      assert.ok(element);
+    });
+
+    it('should return null when element not found', async () => {
+      page = createMockPlaywrightPage({ elements: { button: { count: 0 } } });
+      adapter = new PlaywrightAdapter(page);
+      const element = await adapter.querySelector('button');
+      assert.strictEqual(element, null);
+    });
+
+    it('should query all elements', async () => {
+      page = createMockPlaywrightPage({ elements: { button: { count: 3 } } });
+      adapter = new PlaywrightAdapter(page);
+      const elements = await adapter.querySelectorAll('button');
+      assert.strictEqual(elements.length, 3);
+    });
+
+    it('should count elements', async () => {
+      page = createMockPlaywrightPage({ elements: { button: { count: 5 } } });
+      adapter = new PlaywrightAdapter(page);
+      const count = await adapter.count('button');
+      assert.strictEqual(count, 5);
+    });
+  });
+
+  describe('PuppeteerAdapter', () => {
+    let page;
+    let adapter;
+
+    it('should create adapter', () => {
+      page = createMockPuppeteerPage();
+      adapter = new PuppeteerAdapter(page);
+      assert.ok(adapter);
+    });
+
+    it('should return puppeteer as engine name', () => {
+      page = createMockPuppeteerPage();
+      adapter = new PuppeteerAdapter(page);
+      assert.strictEqual(adapter.getEngineName(), 'puppeteer');
+    });
+
+    it('should return selector string as locator', () => {
+      page = createMockPuppeteerPage();
+      adapter = new PuppeteerAdapter(page);
+      const locator = adapter.createLocator('button');
+      assert.strictEqual(locator, 'button');
+    });
+
+    it('should query single element', async () => {
+      page = createMockPuppeteerPage({ elements: { button: { count: 1 } } });
+      adapter = new PuppeteerAdapter(page);
+      const element = await adapter.querySelector('button');
+      assert.ok(element);
+    });
+
+    it('should return null when element not found', async () => {
+      page = createMockPuppeteerPage({ elements: { button: { count: 0 } } });
+      adapter = new PuppeteerAdapter(page);
+      const element = await adapter.querySelector('button');
+      assert.strictEqual(element, null);
+    });
+
+    it('should query all elements', async () => {
+      page = createMockPuppeteerPage({ elements: { button: { count: 3 } } });
+      adapter = new PuppeteerAdapter(page);
+      const elements = await adapter.querySelectorAll('button');
+      assert.strictEqual(elements.length, 3);
+    });
+
+    it('should count elements', async () => {
+      page = createMockPuppeteerPage({ elements: { button: { count: 5 } } });
+      adapter = new PuppeteerAdapter(page);
+      const count = await adapter.count('button');
+      assert.strictEqual(count, 5);
+    });
+  });
+
+  describe('createEngineAdapter', () => {
+    it('should create PlaywrightAdapter for playwright engine', () => {
+      const page = createMockPlaywrightPage();
+      const adapter = createEngineAdapter(page, 'playwright');
+      assert.ok(adapter instanceof PlaywrightAdapter);
+    });
+
+    it('should create PuppeteerAdapter for puppeteer engine', () => {
+      const page = createMockPuppeteerPage();
+      const adapter = createEngineAdapter(page, 'puppeteer');
+      assert.ok(adapter instanceof PuppeteerAdapter);
+    });
+
+    it('should throw for unknown engine', () => {
+      const page = createMockPlaywrightPage();
+      assert.throws(
+        () => createEngineAdapter(page, 'unknown'),
+        /Unsupported engine/
+      );
+    });
+
+    it('should throw when page is not provided', () => {
+      assert.throws(
+        () => createEngineAdapter(null, 'playwright'),
+        /page is required/
+      );
+    });
+
+    it('should throw when page is undefined', () => {
+      assert.throws(
+        () => createEngineAdapter(undefined, 'playwright'),
+        /page is required/
+      );
+    });
+  });
+});

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

@@ -0,0 +1,81 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { detectEngine } from '../../../src/core/engine-detection.js';
+import {
+  createMockPlaywrightPage,
+  createMockPuppeteerPage,
+} from '../../helpers/mocks.js';
+
+describe('engine-detection', () => {
+  describe('detectEngine', () => {
+    it('should detect Playwright page', () => {
+      const mockPage = createMockPlaywrightPage();
+      // Add Playwright-specific methods
+      mockPage.locator = (selector) => ({});
+      mockPage.context = () => ({});
+
+      const engine = detectEngine(mockPage);
+      assert.strictEqual(engine, 'playwright');
+    });
+
+    it('should detect Puppeteer page', () => {
+      const mockPage = {
+        $eval: async () => {},
+        $$eval: async () => {},
+        $: async () => {},
+        $$: async () => {},
+        // Puppeteer does NOT have locator or context methods
+      };
+
+      const engine = detectEngine(mockPage);
+      assert.strictEqual(engine, 'puppeteer');
+    });
+
+    it('should throw error for unknown engine', () => {
+      const mockPage = {
+        // No recognizable methods
+        someMethod: () => {},
+      };
+
+      assert.throws(() => {
+        detectEngine(mockPage);
+      }, /Unknown browser automation engine/);
+    });
+
+    it('should detect Playwright when locator is function and context exists', () => {
+      const mockPage = {
+        $eval: async () => {},
+        $$eval: async () => {},
+        locator: (selector) => ({}),
+        context: () => ({}),
+      };
+
+      const engine = detectEngine(mockPage);
+      assert.strictEqual(engine, 'playwright');
+    });
+
+    it('should detect Puppeteer when $eval exists but no context', () => {
+      const mockPage = {
+        $eval: async () => {},
+        $$eval: async () => {},
+        // No locator as function, no context
+        locator: 'not-a-function',
+      };
+
+      const engine = detectEngine(mockPage);
+      assert.strictEqual(engine, 'puppeteer');
+    });
+
+    it('should handle page with context as object', () => {
+      const mockPage = {
+        $eval: async () => {},
+        $$eval: async () => {},
+        locator: (selector) => ({}),
+        context: {}, // context as object, not function
+      };
+
+      const engine = detectEngine(mockPage);
+      assert.strictEqual(engine, 'playwright');
+    });
+  });
+});

package/tests/unit/core/logger.test.js

@@ -0,0 +1,80 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { isVerboseEnabled, createLogger } from '../../../src/core/logger.js';
+
+describe('logger', () => {
+  let originalEnv;
+  let originalArgv;
+
+  beforeEach(() => {
+    originalEnv = process.env.VERBOSE;
+    originalArgv = [...process.argv];
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.VERBOSE = originalEnv;
+    } else {
+      delete process.env.VERBOSE;
+    }
+    process.argv = originalArgv;
+  });
+
+  describe('isVerboseEnabled', () => {
+    it('should return false when VERBOSE env is not set', () => {
+      delete process.env.VERBOSE;
+      // Filter out --verbose from argv if present
+      process.argv = process.argv.filter((arg) => arg !== '--verbose');
+      assert.strictEqual(isVerboseEnabled(), false);
+    });
+
+    it('should return true when VERBOSE env is set', () => {
+      process.env.VERBOSE = 'true';
+      assert.strictEqual(isVerboseEnabled(), true);
+    });
+
+    it('should return true when VERBOSE env is set to any value', () => {
+      process.env.VERBOSE = '1';
+      assert.strictEqual(isVerboseEnabled(), true);
+    });
+
+    it('should return true when --verbose flag is in argv', () => {
+      delete process.env.VERBOSE;
+      process.argv = ['node', 'script.js', '--verbose'];
+      assert.strictEqual(isVerboseEnabled(), true);
+    });
+  });
+
+  describe('createLogger', () => {
+    it('should create a logger instance', () => {
+      const log = createLogger();
+      assert.ok(log);
+      assert.ok(typeof log === 'function' || typeof log === 'object');
+    });
+
+    it('should create logger with verbose disabled by default', () => {
+      const log = createLogger();
+      assert.ok(log);
+    });
+
+    it('should create logger with verbose enabled', () => {
+      const log = createLogger({ verbose: true });
+      assert.ok(log);
+    });
+
+    it('should create logger with verbose disabled', () => {
+      const log = createLogger({ verbose: false });
+      assert.ok(log);
+    });
+
+    it('should handle empty options', () => {
+      const log = createLogger({});
+      assert.ok(log);
+    });
+
+    it('should have debug method', () => {
+      const log = createLogger({ verbose: true });
+      assert.ok(typeof log.debug === 'function');
+    });
+  });
+});

package/tests/unit/core/navigation-safety.test.js

@@ -0,0 +1,202 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import {
+  isNavigationError,
+  safeOperation,
+  makeNavigationSafe,
+  withNavigationSafety,
+} from '../../../src/core/navigation-safety.js';
+
+describe('navigation-safety', () => {
+  describe('isNavigationError', () => {
+    it('should return false for null', () => {
+      assert.strictEqual(isNavigationError(null), false);
+    });
+
+    it('should return false for undefined', () => {
+      assert.strictEqual(isNavigationError(undefined), false);
+    });
+
+    it('should return false for error without message', () => {
+      assert.strictEqual(isNavigationError({}), false);
+    });
+
+    it('should return false for regular error', () => {
+      const error = new Error('Some regular error');
+      assert.strictEqual(isNavigationError(error), false);
+    });
+
+    it('should return true for "Execution context was destroyed" error', () => {
+      const error = new Error('Execution context was destroyed');
+      assert.strictEqual(isNavigationError(error), true);
+    });
+
+    it('should return true for "detached Frame" error', () => {
+      const error = new Error('Element is a detached Frame');
+      assert.strictEqual(isNavigationError(error), true);
+    });
+
+    it('should return true for "Target closed" error', () => {
+      const error = new Error('Target closed');
+      assert.strictEqual(isNavigationError(error), true);
+    });
+
+    it('should return true for "Session closed" error', () => {
+      const error = new Error('Session closed');
+      assert.strictEqual(isNavigationError(error), true);
+    });
+
+    it('should return true for "Protocol error" error', () => {
+      const error = new Error('Protocol error');
+      assert.strictEqual(isNavigationError(error), true);
+    });
+
+    it('should return true for "frame was detached" error', () => {
+      const error = new Error('frame was detached');
+      assert.strictEqual(isNavigationError(error), true);
+    });
+
+    it('should return true for "Page crashed" error', () => {
+      const error = new Error('Page crashed');
+      assert.strictEqual(isNavigationError(error), true);
+    });
+
+    it('should return true for "context was destroyed" error', () => {
+      const error = new Error('context was destroyed');
+      assert.strictEqual(isNavigationError(error), true);
+    });
+  });
+
+  describe('safeOperation', () => {
+    it('should return success result on successful operation', async () => {
+      const result = await safeOperation(async () => 'success');
+      assert.strictEqual(result.success, true);
+      assert.strictEqual(result.value, 'success');
+      assert.strictEqual(result.navigationError, false);
+    });
+
+    it('should return default value on navigation error', async () => {
+      const result = await safeOperation(
+        async () => {
+          throw new Error('Execution context was destroyed');
+        },
+        { defaultValue: 'default', silent: true }
+      );
+      assert.strictEqual(result.success, false);
+      assert.strictEqual(result.value, 'default');
+      assert.strictEqual(result.navigationError, true);
+    });
+
+    it('should rethrow non-navigation errors', async () => {
+      await assert.rejects(
+        async () =>
+          safeOperation(async () => {
+            throw new Error('Regular error');
+          }),
+        /Regular error/
+      );
+    });
+
+    it('should use null as default value when not specified', async () => {
+      const result = await safeOperation(
+        async () => {
+          throw new Error('Execution context was destroyed');
+        },
+        { silent: true }
+      );
+      assert.strictEqual(result.value, null);
+    });
+
+    it('should handle operation name for logging', async () => {
+      const result = await safeOperation(
+        async () => {
+          throw new Error('Execution context was destroyed');
+        },
+        { operationName: 'test operation', silent: true }
+      );
+      assert.strictEqual(result.navigationError, true);
+    });
+  });
+
+  describe('makeNavigationSafe', () => {
+    it('should wrap async function', async () => {
+      const fn = async () => 'result';
+      const safeFn = makeNavigationSafe(fn);
+      const result = await safeFn();
+      assert.strictEqual(result, 'result');
+    });
+
+    it('should return default value on navigation error', async () => {
+      const fn = async () => {
+        throw new Error('Execution context was destroyed');
+      };
+      const safeFn = makeNavigationSafe(fn, 'default');
+      const result = await safeFn();
+      assert.strictEqual(result, 'default');
+    });
+
+    it('should pass arguments to wrapped function', async () => {
+      const fn = async (a, b) => a + b;
+      const safeFn = makeNavigationSafe(fn);
+      const result = await safeFn(1, 2);
+      assert.strictEqual(result, 3);
+    });
+  });
+
+  describe('withNavigationSafety', () => {
+    it('should return function result on success', async () => {
+      const fn = async () => 'success';
+      const safeFn = withNavigationSafety(fn);
+      const result = await safeFn();
+      assert.strictEqual(result, 'success');
+    });
+
+    it('should call onNavigationError callback on navigation error', async () => {
+      let called = false;
+      const fn = async () => {
+        throw new Error('Execution context was destroyed');
+      };
+      const safeFn = withNavigationSafety(fn, {
+        onNavigationError: () => {
+          called = true;
+          return 'handled';
+        },
+      });
+      const result = await safeFn();
+      assert.strictEqual(called, true);
+      assert.strictEqual(result, 'handled');
+    });
+
+    it('should return undefined when rethrow is false and no callback', async () => {
+      const fn = async () => {
+        throw new Error('Execution context was destroyed');
+      };
+      const safeFn = withNavigationSafety(fn, { rethrow: false });
+      const result = await safeFn();
+      assert.strictEqual(result, undefined);
+    });
+
+    it('should rethrow navigation error when rethrow is true and no callback', async () => {
+      const fn = async () => {
+        throw new Error('Execution context was destroyed');
+      };
+      const safeFn = withNavigationSafety(fn, { rethrow: true });
+      await assert.rejects(safeFn, /Execution context was destroyed/);
+    });
+
+    it('should rethrow non-navigation errors', async () => {
+      const fn = async () => {
+        throw new Error('Regular error');
+      };
+      const safeFn = withNavigationSafety(fn);
+      await assert.rejects(safeFn, /Regular error/);
+    });
+
+    it('should pass arguments through', async () => {
+      const fn = async (x) => x * 2;
+      const safeFn = withNavigationSafety(fn);
+      const result = await safeFn(5);
+      assert.strictEqual(result, 10);
+    });
+  });
+});