appium-uiwatchers-plugin 1.0.0

package/test/unit/utils.spec.js

@@ -0,0 +1,85 @@
+import { describe, it } from 'mocha';
+import { expect } from 'chai';
+import { extractElementId, W3C_ELEMENT_KEY } from '../../lib/utils.js';
+
+describe('Utils', function () {
+  describe('W3C_ELEMENT_KEY', function () {
+    it('should be the correct W3C WebDriver element identifier', function () {
+      expect(W3C_ELEMENT_KEY).to.equal('element-6066-11e4-a52e-4f735466cecf');
+    });
+  });
+
+  describe('extractElementId', function () {
+    describe('W3C format', function () {
+      it('should extract element ID from W3C format', function () {
+        const element = { [W3C_ELEMENT_KEY]: 'abc123' };
+        expect(extractElementId(element)).to.equal('abc123');
+      });
+
+      it('should handle W3C format with additional properties', function () {
+        const element = { [W3C_ELEMENT_KEY]: 'xyz789', someOther: 'prop' };
+        expect(extractElementId(element)).to.equal('xyz789');
+      });
+    });
+
+    describe('JSONWP format', function () {
+      it('should extract element ID from JSONWP format', function () {
+        const element = { ELEMENT: 'def456' };
+        expect(extractElementId(element)).to.equal('def456');
+      });
+
+      it('should handle JSONWP format with additional properties', function () {
+        const element = { ELEMENT: 'ghi012', someOther: 'prop' };
+        expect(extractElementId(element)).to.equal('ghi012');
+      });
+    });
+
+    describe('both formats present', function () {
+      it('should prefer W3C format when both are present', function () {
+        const element = { [W3C_ELEMENT_KEY]: 'w3c-id', ELEMENT: 'jsonwp-id' };
+        expect(extractElementId(element)).to.equal('w3c-id');
+      });
+    });
+
+    describe('direct string ID', function () {
+      it('should return string ID directly', function () {
+        expect(extractElementId('direct-string-id')).to.equal('direct-string-id');
+      });
+
+      it('should handle empty string', function () {
+        expect(extractElementId('')).to.be.undefined;
+      });
+    });
+
+    describe('null and undefined', function () {
+      it('should return undefined for null', function () {
+        expect(extractElementId(null)).to.be.undefined;
+      });
+
+      it('should return undefined for undefined', function () {
+        expect(extractElementId(undefined)).to.be.undefined;
+      });
+    });
+
+    describe('invalid inputs', function () {
+      it('should return undefined for empty object', function () {
+        expect(extractElementId({})).to.be.undefined;
+      });
+
+      it('should return undefined for object without element keys', function () {
+        const element = { foo: 'bar', baz: 'qux' };
+        expect(extractElementId(element)).to.be.undefined;
+      });
+
+      it('should return undefined for object with empty W3C value', function () {
+        const element = { [W3C_ELEMENT_KEY]: '' };
+        expect(extractElementId(element)).to.be.undefined;
+      });
+
+      it('should return undefined for object with empty JSONWP value', function () {
+        const element = { ELEMENT: '' };
+        expect(extractElementId(element)).to.be.undefined;
+      });
+    });
+  });
+});

package/test/unit/validators.spec.js

@@ -0,0 +1,246 @@
+import { describe, it } from 'mocha';
+import { expect } from 'chai';
+import { validateWatcherParams, validateLocator } from '../../lib/validators.js';
+
+describe('Validators', function () {
+  describe('validateLocator', function () {
+    it('should pass for valid locator', function () {
+      const validLocator = { using: 'id', value: 'com.app:id/button' };
+      expect(() => validateLocator(validLocator, 'testLocator')).to.not.throw();
+    });
+
+    it('should throw error if locator is null', function () {
+      expect(() => validateLocator(null, 'testLocator')).to.throw('testLocator is required');
+    });
+
+    it('should throw error if locator is undefined', function () {
+      expect(() => validateLocator(undefined, 'testLocator')).to.throw('testLocator is required');
+    });
+
+    it('should throw error if locator is not an object', function () {
+      expect(() => validateLocator('invalid', 'testLocator')).to.throw('testLocator is required');
+    });
+
+    it('should throw error if using field is missing', function () {
+      const locator = { value: 'test' };
+      expect(() => validateLocator(locator, 'testLocator')).to.throw(
+        "'using' is mandatory for testLocator"
+      );
+    });
+
+    it('should throw error if value field is missing', function () {
+      const locator = { using: 'id' };
+      expect(() => validateLocator(locator, 'testLocator')).to.throw(
+        "'value' is mandatory for testLocator"
+      );
+    });
+
+    it('should throw error if using is not a string', function () {
+      const locator = { using: 123, value: 'test' };
+      expect(() => validateLocator(locator, 'testLocator')).to.throw(
+        "'using' must be string for testLocator"
+      );
+    });
+
+    it('should throw error if value is not a string', function () {
+      const locator = { using: 'id', value: 123 };
+      expect(() => validateLocator(locator, 'testLocator')).to.throw(
+        "'value' must be string for testLocator"
+      );
+    });
+
+    it('should throw error for invalid locator strategy', function () {
+      const locator = { using: 'invalid-strategy', value: 'test' };
+      expect(() => validateLocator(locator, 'testLocator')).to.throw(
+        'Invalid locator strategy for testLocator'
+      );
+    });
+
+    it('should accept all valid locator strategies', function () {
+      const strategies = [
+        'id',
+        'accessibility id',
+        'class name',
+        'xpath',
+        'name',
+        '-android uiautomator',
+        '-ios predicate string',
+        '-ios class chain',
+        'css selector',
+      ];
+
+      strategies.forEach((strategy) => {
+        const locator = { using: strategy, value: 'test' };
+        expect(() => validateLocator(locator, 'testLocator')).to.not.throw();
+      });
+    });
+
+    it('should be case-insensitive for locator strategies', function () {
+      const locator = { using: 'ID', value: 'test' };
+      expect(() => validateLocator(locator, 'testLocator')).to.not.throw();
+    });
+  });
+
+  describe('validateWatcherParams', function () {
+    const validParams = {
+      name: 'test-watcher',
+      referenceLocator: { using: 'id', value: 'popup' },
+      actionLocator: { using: 'id', value: 'close' },
+      duration: 30000,
+    };
+    const defaultMaxDuration = 60000; // Default max duration
+
+    it('should pass for valid watcher params', function () {
+      expect(() => validateWatcherParams(validParams, defaultMaxDuration)).to.not.throw();
+    });
+
+    it('should throw error if params is null', function () {
+      expect(() => validateWatcherParams(null, defaultMaxDuration)).to.throw(
+        'Invalid watcher parameters'
+      );
+    });
+
+    it('should throw error if params is undefined', function () {
+      expect(() => validateWatcherParams(undefined, defaultMaxDuration)).to.throw(
+        'Invalid watcher parameters'
+      );
+    });
+
+    it('should throw error if name is missing', function () {
+      const params = { ...validParams };
+      delete params.name;
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher name is required'
+      );
+    });
+
+    it('should throw error if name is empty string', function () {
+      const params = { ...validParams, name: '' };
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher name is required'
+      );
+    });
+
+    it('should throw error if name is whitespace only', function () {
+      const params = { ...validParams, name: '   ' };
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher name is empty'
+      );
+    });
+
+    it('should throw error if referenceLocator is missing', function () {
+      const params = { ...validParams };
+      delete params.referenceLocator;
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher referenceLocator is required'
+      );
+    });
+
+    it('should throw error if actionLocator is missing', function () {
+      const params = { ...validParams };
+      delete params.actionLocator;
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher actionLocator is required'
+      );
+    });
+
+    it('should throw error if duration is missing', function () {
+      const params = { ...validParams };
+      delete params.duration;
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher duration is required'
+      );
+    });
+
+    it('should throw error if duration is 0', function () {
+      const params = { ...validParams, duration: 0 };
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher duration must be a positive number'
+      );
+    });
+
+    it('should throw error if duration is negative', function () {
+      const params = { ...validParams, duration: -1000 };
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher duration must be a positive number'
+      );
+    });
+
+    it('should throw error if duration > 60000', function () {
+      const params = { ...validParams, duration: 60001 };
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher duration must be ≤ 60 seconds'
+      );
+    });
+
+    it('should accept duration = 60000', function () {
+      const params = { ...validParams, duration: 60000 };
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.not.throw();
+    });
+
+    it('should throw error if priority is not a number', function () {
+      const params = { ...validParams, priority: 'high' };
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher priority must be a number'
+      );
+    });
+
+    it('should accept negative priority values', function () {
+      const params = { ...validParams, priority: -10 };
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.not.throw();
+    });
+
+    it('should throw error if stopOnFound is not a boolean', function () {
+      const params = { ...validParams, stopOnFound: 'true' };
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher stopOnFound must be a boolean'
+      );
+    });
+
+    it('should accept stopOnFound as true or false', function () {
+      const params1 = { ...validParams, stopOnFound: true };
+      const params2 = { ...validParams, stopOnFound: false };
+      expect(() => validateWatcherParams(params1, defaultMaxDuration)).to.not.throw();
+      expect(() => validateWatcherParams(params2, defaultMaxDuration)).to.not.throw();
+    });
+
+    it('should throw error if cooldownMs is not a number', function () {
+      const params = { ...validParams, cooldownMs: '5000' };
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher cooldownMs must be a number'
+      );
+    });
+
+    it('should throw error if cooldownMs is negative', function () {
+      const params = { ...validParams, cooldownMs: -100 };
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher cooldownMs must be ≥ 0'
+      );
+    });
+
+    it('should accept cooldownMs = 0', function () {
+      const params = { ...validParams, cooldownMs: 0 };
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.not.throw();
+    });
+
+    it('should accept all valid optional parameters', function () {
+      const params = {
+        ...validParams,
+        priority: 10,
+        stopOnFound: true,
+        cooldownMs: 5000,
+      };
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.not.throw();
+    });
+
+    it('should respect custom maxDurationMs parameter', function () {
+      const params = { ...validParams, duration: 90000 };
+      // Should fail with default (60000)
+      expect(() => validateWatcherParams(params, defaultMaxDuration)).to.throw(
+        'UIWatcher duration must be ≤'
+      );
+      // Should pass with custom limit (120000)
+      expect(() => validateWatcherParams(params, 120000)).to.not.throw();
+    });
+  });
+});

package/test/unit/watcher-checker.spec.js

@@ -0,0 +1,274 @@
+import { describe, it, beforeEach } from 'mocha';
+import { expect } from 'chai';
+import sinon from 'sinon';
+import { WatcherStore } from '../../lib/watcher-store.js';
+import { checkWatchers } from '../../lib/watcher-checker.js';
+
+describe('WatcherChecker', function () {
+  let store;
+  let mockDriver;
+
+  beforeEach(function () {
+    // Use default config values (same as schema defaults)
+    store = new WatcherStore({ maxWatchers: 5, maxDurationMs: 60000 });
+
+    // Create mock driver
+    mockDriver = {
+      findElement: sinon.stub(),
+      click: sinon.stub(),
+    };
+  });
+
+  describe('checkWatchers', function () {
+    it('should skip checking when watchers are disabled', async function () {
+      store.disable();
+      store.add({
+        name: 'test',
+        referenceLocator: { using: 'id', value: 'popup' },
+        actionLocator: { using: 'id', value: 'close' },
+        duration: 30000,
+      });
+
+      await checkWatchers(mockDriver, store);
+
+      expect(mockDriver.findElement.called).to.be.false;
+    });
+
+    it('should skip checking when no active watchers', async function () {
+      await checkWatchers(mockDriver, store);
+
+      expect(mockDriver.findElement.called).to.be.false;
+    });
+
+    it('should check watchers in priority order', async function () {
+      const calls = [];
+
+      store.add({
+        name: 'low',
+        priority: 1,
+        referenceLocator: { using: 'id', value: 'popup1' },
+        actionLocator: { using: 'id', value: 'close1' },
+        duration: 30000,
+      });
+
+      store.add({
+        name: 'high',
+        priority: 10,
+        referenceLocator: { using: 'id', value: 'popup2' },
+        actionLocator: { using: 'id', value: 'close2' },
+        duration: 30000,
+      });
+
+      mockDriver.findElement.callsFake((using, value) => {
+        calls.push(value);
+        throw new Error('not found');
+      });
+
+      await checkWatchers(mockDriver, store);
+
+      // Should check high priority first
+      expect(calls[0]).to.equal('popup2');
+      expect(calls[1]).to.equal('popup1');
+    });
+
+    it('should skip inactive watchers', async function () {
+      store.add({
+        name: 'test',
+        referenceLocator: { using: 'id', value: 'popup' },
+        actionLocator: { using: 'id', value: 'close' },
+        duration: 30000,
+      });
+
+      store.markInactive('test');
+
+      await checkWatchers(mockDriver, store);
+
+      expect(mockDriver.findElement.called).to.be.false;
+    });
+
+    it('should continue to next watcher if reference not found', async function () {
+      store.add({
+        name: 'watcher1',
+        referenceLocator: { using: 'id', value: 'popup1' },
+        actionLocator: { using: 'id', value: 'close1' },
+        duration: 30000,
+      });
+
+      store.add({
+        name: 'watcher2',
+        referenceLocator: { using: 'id', value: 'popup2' },
+        actionLocator: { using: 'id', value: 'close2' },
+        duration: 30000,
+      });
+
+      mockDriver.findElement.throws(new Error('not found'));
+
+      await checkWatchers(mockDriver, store);
+
+      // Should attempt both watchers
+      expect(mockDriver.findElement.callCount).to.equal(2);
+    });
+
+    it('should click action element when reference found', async function () {
+      store.add({
+        name: 'test',
+        referenceLocator: { using: 'id', value: 'popup' },
+        actionLocator: { using: 'id', value: 'close' },
+        duration: 30000,
+      });
+
+      mockDriver.findElement.resolves({ ELEMENT: 'element-1' });
+      mockDriver.click.resolves();
+
+      await checkWatchers(mockDriver, store);
+
+      expect(mockDriver.findElement.callCount).to.equal(2); // reference + action
+      expect(mockDriver.click.calledOnce).to.be.true;
+    });
+
+    it('should increment trigger count on successful click', async function () {
+      store.add({
+        name: 'test',
+        referenceLocator: { using: 'id', value: 'popup' },
+        actionLocator: { using: 'id', value: 'close' },
+        duration: 30000,
+      });
+
+      mockDriver.findElement.resolves({ ELEMENT: 'element-1' });
+      mockDriver.click.resolves();
+
+      await checkWatchers(mockDriver, store);
+
+      const watcher = store.get('test');
+      expect(watcher.triggerCount).to.equal(1);
+      expect(watcher.lastTriggeredAt).to.be.a('number');
+    });
+
+    it('should mark inactive when stopOnFound is true', async function () {
+      store.add({
+        name: 'test',
+        referenceLocator: { using: 'id', value: 'popup' },
+        actionLocator: { using: 'id', value: 'close' },
+        duration: 30000,
+        stopOnFound: true,
+      });
+
+      mockDriver.findElement.resolves({ ELEMENT: 'element-1' });
+      mockDriver.click.resolves();
+
+      await checkWatchers(mockDriver, store);
+
+      const watcher = store.get('test');
+      expect(watcher.status).to.equal('inactive');
+    });
+
+    it('should execute cooldown wait when configured', async function () {
+      this.timeout(5000);
+
+      store.add({
+        name: 'test',
+        referenceLocator: { using: 'id', value: 'popup' },
+        actionLocator: { using: 'id', value: 'close' },
+        duration: 30000,
+        cooldownMs: 100,
+      });
+
+      mockDriver.findElement.resolves({ ELEMENT: 'element-1' });
+      mockDriver.click.resolves();
+
+      const start = Date.now();
+      await checkWatchers(mockDriver, store);
+      const elapsed = Date.now() - start;
+
+      // Should have waited at least 100ms
+      expect(elapsed).to.be.at.least(100);
+    });
+
+    it('should continue to next watcher if action click fails', async function () {
+      store.add({
+        name: 'watcher1',
+        referenceLocator: { using: 'id', value: 'popup1' },
+        actionLocator: { using: 'id', value: 'close1' },
+        duration: 30000,
+      });
+
+      store.add({
+        name: 'watcher2',
+        referenceLocator: { using: 'id', value: 'popup2' },
+        actionLocator: { using: 'id', value: 'close2' },
+        duration: 30000,
+      });
+
+      mockDriver.findElement.resolves({ ELEMENT: 'element-1' });
+      mockDriver.click.onFirstCall().rejects(new Error('Click failed'));
+      mockDriver.click.onSecondCall().resolves();
+
+      await checkWatchers(mockDriver, store);
+
+      // Should attempt both watchers
+      expect(mockDriver.click.callCount).to.equal(2);
+
+      // First watcher should not be counted as triggered
+      const watcher1 = store.get('watcher1');
+      expect(watcher1.triggerCount).to.equal(0);
+
+      // Second watcher should be counted
+      const watcher2 = store.get('watcher2');
+      expect(watcher2.triggerCount).to.equal(1);
+    });
+
+    it('should not execute cooldown if click fails', async function () {
+      store.add({
+        name: 'test',
+        referenceLocator: { using: 'id', value: 'popup' },
+        actionLocator: { using: 'id', value: 'close' },
+        duration: 30000,
+        cooldownMs: 1000,
+      });
+
+      mockDriver.findElement.resolves({ ELEMENT: 'element-1' });
+      mockDriver.click.rejects(new Error('Click failed'));
+
+      const start = Date.now();
+      await checkWatchers(mockDriver, store);
+      const elapsed = Date.now() - start;
+
+      // Should not have waited for cooldown
+      expect(elapsed).to.be.below(500);
+    });
+
+    it('should handle multiple watchers triggering sequentially', async function () {
+      this.timeout(5000);
+
+      store.add({
+        name: 'watcher1',
+        referenceLocator: { using: 'id', value: 'popup1' },
+        actionLocator: { using: 'id', value: 'close1' },
+        duration: 30000,
+        cooldownMs: 50,
+      });
+
+      store.add({
+        name: 'watcher2',
+        referenceLocator: { using: 'id', value: 'popup2' },
+        actionLocator: { using: 'id', value: 'close2' },
+        duration: 30000,
+        cooldownMs: 50,
+      });
+
+      mockDriver.findElement.resolves({ ELEMENT: 'element-1' });
+      mockDriver.click.resolves();
+
+      const start = Date.now();
+      await checkWatchers(mockDriver, store);
+      const elapsed = Date.now() - start;
+
+      // Should have waited for both cooldowns (50ms + 50ms = 100ms minimum)
+      expect(elapsed).to.be.at.least(100);
+
+      // Both should be triggered
+      expect(store.get('watcher1').triggerCount).to.equal(1);
+      expect(store.get('watcher2').triggerCount).to.equal(1);
+    });
+  });
+});