appium-uiwatchers-plugin 1.0.0

package/test/e2e/plugin.e2e.spec.cjs

@@ -0,0 +1,312 @@
+const path = require('path');
+const { remote: wdio } = require('webdriverio');
+const { pluginE2EHarness } = require('@appium/plugin-test-support');
+
+const THIS_PLUGIN_DIR = path.join(__dirname, '..', '..');
+const TEST_HOST = '127.0.0.1';
+const TEST_PORT = 4723;
+const TEST_FAKE_APP = path.join(
+  THIS_PLUGIN_DIR,
+  'node_modules',
+  '@appium',
+  'fake-driver',
+  'test',
+  'fixtures',
+  'app.xml'
+);
+
+const TEST_CAPS = {
+  platformName: 'Fake',
+  'appium:automationName': 'Fake',
+  'appium:deviceName': 'Fake',
+  'appium:app': TEST_FAKE_APP,
+};
+
+const WDIO_OPTS = {
+  hostname: TEST_HOST,
+  port: TEST_PORT,
+  connectionRetryCount: 0,
+  capabilities: TEST_CAPS,
+};
+
+describe('UIWatchers Plugin E2E', function () {
+  let driver;
+
+  pluginE2EHarness({
+    before,
+    after,
+    port: TEST_PORT,
+    host: TEST_HOST,
+    appiumHome: THIS_PLUGIN_DIR,
+    driverName: 'fake',
+    driverSource: 'npm',
+    driverSpec: '@appium/fake-driver',
+    pluginName: 'uiwatchers',
+    pluginSource: 'local',
+    pluginSpec: THIS_PLUGIN_DIR,
+  });
+
+  beforeEach(async function () {
+    driver = await wdio(WDIO_OPTS);
+  });
+
+  afterEach(async function () {
+    if (driver) {
+      await driver.deleteSession();
+    }
+  });
+
+  describe('Plugin activation', function () {
+    it('should start session with plugin active', async function () {
+      const session = await driver.getSession();
+      session.should.exist;
+    });
+  });
+
+  describe('mobile: registerUIWatcher', function () {
+    it('should register a new watcher successfully', async function () {
+      const result = await driver.executeScript('mobile: registerUIWatcher', [
+        {
+          name: 'test-watcher',
+          referenceLocator: { using: 'id', value: 'popup' },
+          actionLocator: { using: 'id', value: 'close' },
+          duration: 30000,
+        },
+      ]);
+
+      result.should.have.property('success', true);
+      result.should.have.property('watcher');
+      result.watcher.should.have.property('name', 'test-watcher');
+      result.watcher.should.have.property('priority', 0);
+      result.watcher.should.have.property('status', 'active');
+    });
+
+    it('should register watcher with optional parameters', async function () {
+      const result = await driver.executeScript('mobile: registerUIWatcher', [
+        {
+          name: 'priority-watcher',
+          referenceLocator: { using: 'id', value: 'banner' },
+          actionLocator: { using: 'id', value: 'dismiss' },
+          duration: 60000,
+          priority: 10,
+          stopOnFound: true,
+          cooldownMs: 5000,
+        },
+      ]);
+
+      result.should.have.property('success', true);
+      result.watcher.should.have.property('priority', 10);
+    });
+
+    it('should throw error for duration > 60000', async function () {
+      try {
+        await driver.executeScript('mobile: registerUIWatcher', [
+          {
+            name: 'long-duration',
+            referenceLocator: { using: 'id', value: 'popup' },
+            actionLocator: { using: 'id', value: 'close' },
+            duration: 70000,
+          },
+        ]);
+        throw new Error('Should have thrown an error');
+      } catch (error) {
+        error.message.should.match(/60 seconds/);
+      }
+    });
+  });
+
+  describe('mobile: listUIWatchers', function () {
+    beforeEach(async function () {
+      // Clear any existing watchers
+      await driver.executeScript('mobile: clearAllUIWatchers', []);
+
+      // Register a few watchers
+      await driver.executeScript('mobile: registerUIWatcher', [
+        {
+          name: 'list-test-1',
+          referenceLocator: { using: 'id', value: 'popup1' },
+          actionLocator: { using: 'id', value: 'close1' },
+          duration: 30000,
+          priority: 10,
+        },
+      ]);
+
+      await driver.executeScript('mobile: registerUIWatcher', [
+        {
+          name: 'list-test-2',
+          referenceLocator: { using: 'id', value: 'popup2' },
+          actionLocator: { using: 'id', value: 'close2' },
+          duration: 30000,
+          priority: 5,
+        },
+      ]);
+    });
+
+    it('should list all registered watchers', async function () {
+      const result = await driver.executeScript('mobile: listUIWatchers', []);
+
+      result.should.have.property('success', true);
+      result.should.have.property('watchers');
+      result.should.have.property('totalCount');
+      result.watchers.should.be.an('array');
+      result.totalCount.should.be.at.least(2);
+    });
+
+    it('should include complete watcher state', async function () {
+      const result = await driver.executeScript('mobile: listUIWatchers', []);
+
+      const watcher = result.watchers.find((w) => w.name === 'list-test-1');
+      watcher.should.exist;
+      watcher.should.have.property('name');
+      watcher.should.have.property('priority');
+      watcher.should.have.property('referenceLocator');
+      watcher.should.have.property('actionLocator');
+      watcher.should.have.property('status');
+      watcher.should.have.property('triggerCount');
+    });
+  });
+
+  describe('mobile: unregisterUIWatcher', function () {
+    beforeEach(async function () {
+      await driver.executeScript('mobile: clearAllUIWatchers', []);
+      await driver.executeScript('mobile: registerUIWatcher', [
+        {
+          name: 'to-remove',
+          referenceLocator: { using: 'id', value: 'popup' },
+          actionLocator: { using: 'id', value: 'close' },
+          duration: 30000,
+        },
+      ]);
+    });
+
+    it('should unregister an existing watcher', async function () {
+      const result = await driver.executeScript('mobile: unregisterUIWatcher', [
+        { name: 'to-remove' },
+      ]);
+
+      result.should.have.property('success', true);
+      result.should.have.property('removed', 'to-remove');
+
+      // Verify it's actually removed
+      const listResult = await driver.executeScript('mobile: listUIWatchers', []);
+      const found = listResult.watchers.find((w) => w.name === 'to-remove');
+      (found === undefined).should.be.true;
+    });
+
+    it('should throw error for non-existent watcher', async function () {
+      try {
+        await driver.executeScript('mobile: unregisterUIWatcher', [{ name: 'non-existent' }]);
+        throw new Error('Should have thrown an error');
+      } catch (error) {
+        error.message.should.match(/not found/);
+      }
+    });
+  });
+
+  describe('mobile: clearAllUIWatchers', function () {
+    beforeEach(async function () {
+      await driver.executeScript('mobile: clearAllUIWatchers', []);
+      await driver.executeScript('mobile: registerUIWatcher', [
+        {
+          name: 'clear-test-1',
+          referenceLocator: { using: 'id', value: 'popup1' },
+          actionLocator: { using: 'id', value: 'close1' },
+          duration: 30000,
+        },
+      ]);
+
+      await driver.executeScript('mobile: registerUIWatcher', [
+        {
+          name: 'clear-test-2',
+          referenceLocator: { using: 'id', value: 'popup2' },
+          actionLocator: { using: 'id', value: 'close2' },
+          duration: 30000,
+        },
+      ]);
+    });
+
+    it('should clear all watchers', async function () {
+      const result = await driver.executeScript('mobile: clearAllUIWatchers', []);
+
+      result.should.have.property('success', true);
+      result.should.have.property('removedCount');
+      result.removedCount.should.be.at.least(2);
+
+      // Verify all are removed
+      const listResult = await driver.executeScript('mobile: listUIWatchers', []);
+      listResult.totalCount.should.equal(0);
+      listResult.watchers.should.be.empty;
+    });
+  });
+
+  describe('mobile: disableUIWatchers / enableUIWatchers', function () {
+    it('should disable watcher checking', async function () {
+      const result = await driver.executeScript('mobile: disableUIWatchers', []);
+
+      result.should.have.property('success', true);
+      result.should.have.property('message');
+      result.message.should.match(/disabled/);
+    });
+
+    it('should enable watcher checking', async function () {
+      const result = await driver.executeScript('mobile: enableUIWatchers', []);
+
+      result.should.have.property('success', true);
+      result.should.have.property('message');
+      result.message.should.match(/enabled/);
+    });
+  });
+
+  describe('Maximum watcher limit', function () {
+    beforeEach(async function () {
+      await driver.executeScript('mobile: clearAllUIWatchers', []);
+    });
+
+    it('should allow up to 5 watchers', async function () {
+      for (let i = 1; i <= 5; i++) {
+        const result = await driver.executeScript('mobile: registerUIWatcher', [
+          {
+            name: `limit-test-${i}`,
+            referenceLocator: { using: 'id', value: `popup-${i}` },
+            actionLocator: { using: 'id', value: `close-${i}` },
+            duration: 30000,
+          },
+        ]);
+        result.success.should.be.true;
+      }
+
+      // Verify all 5 are registered
+      const listResult = await driver.executeScript('mobile: listUIWatchers', []);
+      listResult.totalCount.should.equal(5);
+    });
+
+    it('should throw error when adding 6th watcher', async function () {
+      // First add 5 watchers
+      for (let i = 1; i <= 5; i++) {
+        await driver.executeScript('mobile: registerUIWatcher', [
+          {
+            name: `limit-test-${i}`,
+            referenceLocator: { using: 'id', value: `popup-${i}` },
+            actionLocator: { using: 'id', value: `close-${i}` },
+            duration: 30000,
+          },
+        ]);
+      }
+
+      // Try to add 6th
+      try {
+        await driver.executeScript('mobile: registerUIWatcher', [
+          {
+            name: 'limit-test-6',
+            referenceLocator: { using: 'id', value: 'popup-6' },
+            actionLocator: { using: 'id', value: 'close-6' },
+            duration: 30000,
+          },
+        ]);
+        throw new Error('Should have thrown an error');
+      } catch (error) {
+        error.message.should.match(/Maximum 5/);
+      }
+    });
+  });
+});

package/test/unit/element-cache.spec.js

@@ -0,0 +1,269 @@
+import { describe, it, beforeEach } from 'mocha';
+import { expect } from 'chai';
+import { ElementReferenceCache } from '../../lib/element-cache.js';
+
+describe('ElementReferenceCache', function () {
+  let cache;
+
+  const defaultConfig = {
+    maxWatchers: 5,
+    maxDurationMs: 60000,
+    maxCacheEntries: 50,
+    elementTtlMs: 60000,
+  };
+
+  beforeEach(function () {
+    cache = new ElementReferenceCache(defaultConfig);
+  });
+
+  describe('cacheElement', function () {
+    it('should cache element from findElement', function () {
+      cache.cacheElement('elem-123', 'id', 'submit-btn');
+
+      const ref = cache.getRef('elem-123');
+      expect(ref).to.not.be.undefined;
+      expect(ref.using).to.equal('id');
+      expect(ref.value).to.equal('submit-btn');
+      expect(ref.source).to.equal('findElement');
+      expect(ref.createdAt).to.be.a('number');
+    });
+
+    it('should increment cache size when adding elements', function () {
+      expect(cache.size).to.equal(0);
+
+      cache.cacheElement('elem-1', 'id', 'btn1');
+      expect(cache.size).to.equal(1);
+
+      cache.cacheElement('elem-2', 'id', 'btn2');
+      expect(cache.size).to.equal(2);
+    });
+  });
+
+  describe('cacheElements', function () {
+    it('should cache elements from findElements with correct indices', function () {
+      const elements = [
+        { 'element-6066-11e4-a52e-4f735466cecf': 'elem-1' },
+        { 'element-6066-11e4-a52e-4f735466cecf': 'elem-2' },
+        { 'element-6066-11e4-a52e-4f735466cecf': 'elem-3' },
+      ];
+
+      cache.cacheElements(elements, 'css selector', '.item');
+
+      const ref1 = cache.getRef('elem-1');
+      expect(ref1.source).to.equal('findElements');
+      expect(ref1.index).to.equal(0);
+
+      const ref2 = cache.getRef('elem-2');
+      expect(ref2.source).to.equal('findElements');
+      expect(ref2.index).to.equal(1);
+
+      const ref3 = cache.getRef('elem-3');
+      expect(ref3.source).to.equal('findElements');
+      expect(ref3.index).to.equal(2);
+    });
+
+    it('should handle JSONWP element format', function () {
+      const elements = [{ ELEMENT: 'jsonwp-elem-1' }, { ELEMENT: 'jsonwp-elem-2' }];
+
+      cache.cacheElements(elements, 'xpath', '//div');
+
+      const ref1 = cache.getRef('jsonwp-elem-1');
+      expect(ref1).to.not.be.undefined;
+      expect(ref1.index).to.equal(0);
+
+      const ref2 = cache.getRef('jsonwp-elem-2');
+      expect(ref2).to.not.be.undefined;
+      expect(ref2.index).to.equal(1);
+    });
+  });
+
+  describe('getRef', function () {
+    it('should return undefined for non-existent element', function () {
+      const ref = cache.getRef('non-existent');
+      expect(ref).to.be.undefined;
+    });
+
+    it('should return cached reference for existing element', function () {
+      cache.cacheElement('elem-123', 'id', 'myBtn');
+
+      const ref = cache.getRef('elem-123');
+      expect(ref).to.not.be.undefined;
+      expect(ref.using).to.equal('id');
+      expect(ref.value).to.equal('myBtn');
+    });
+  });
+
+  describe('LRU eviction', function () {
+    it('should evict oldest entry when max entries reached', function () {
+      // Use small cache for testing
+      const smallCache = new ElementReferenceCache({
+        ...defaultConfig,
+        maxCacheEntries: 3,
+      });
+
+      smallCache.cacheElement('elem-1', 'id', 'btn1');
+      smallCache.cacheElement('elem-2', 'id', 'btn2');
+      smallCache.cacheElement('elem-3', 'id', 'btn3');
+
+      expect(smallCache.size).to.equal(3);
+
+      // Adding 4th should evict elem-1 (oldest)
+      smallCache.cacheElement('elem-4', 'id', 'btn4');
+
+      expect(smallCache.size).to.equal(3);
+      expect(smallCache.getRef('elem-1')).to.be.undefined;
+      expect(smallCache.getRef('elem-2')).to.not.be.undefined;
+      expect(smallCache.getRef('elem-3')).to.not.be.undefined;
+      expect(smallCache.getRef('elem-4')).to.not.be.undefined;
+    });
+
+    it('should update LRU order when accessing element', function () {
+      const smallCache = new ElementReferenceCache({
+        ...defaultConfig,
+        maxCacheEntries: 3,
+      });
+
+      smallCache.cacheElement('elem-1', 'id', 'btn1');
+      smallCache.cacheElement('elem-2', 'id', 'btn2');
+      smallCache.cacheElement('elem-3', 'id', 'btn3');
+
+      // Access elem-1 to make it most recently used
+      smallCache.getRef('elem-1');
+
+      // Adding elem-4 should evict elem-2 (now the oldest)
+      smallCache.cacheElement('elem-4', 'id', 'btn4');
+
+      expect(smallCache.getRef('elem-1')).to.not.be.undefined; // Was accessed, not evicted
+      expect(smallCache.getRef('elem-2')).to.be.undefined; // Evicted
+      expect(smallCache.getRef('elem-3')).to.not.be.undefined;
+      expect(smallCache.getRef('elem-4')).to.not.be.undefined;
+    });
+  });
+
+  describe('TTL expiry', function () {
+    it('should return undefined for expired entries', function () {
+      // Use very short TTL for testing
+      const shortTtlCache = new ElementReferenceCache({
+        ...defaultConfig,
+        elementTtlMs: 10, // 10ms TTL
+      });
+
+      shortTtlCache.cacheElement('elem-1', 'id', 'btn1');
+
+      // Wait for TTL to expire
+      return new Promise((resolve) => {
+        setTimeout(() => {
+          const ref = shortTtlCache.getRef('elem-1');
+          expect(ref).to.be.undefined;
+          resolve();
+        }, 20);
+      });
+    });
+  });
+
+  describe('setMapping', function () {
+    it('should create element ID mapping', function () {
+      cache.setMapping('old-id', 'new-id');
+
+      const mapped = cache.getMappedId('old-id');
+      expect(mapped).to.equal('new-id');
+    });
+
+    it('should return undefined for unmapped ID', function () {
+      const mapped = cache.getMappedId('unknown-id');
+      expect(mapped).to.be.undefined;
+    });
+
+    it('should increment mappings count', function () {
+      expect(cache.mappingsCount).to.equal(0);
+
+      cache.setMapping('old-1', 'new-1');
+      expect(cache.mappingsCount).to.equal(1);
+
+      cache.setMapping('old-2', 'new-2');
+      expect(cache.mappingsCount).to.equal(2);
+    });
+  });
+
+  describe('transitive mapping update', function () {
+    it('should update existing mappings when creating new mapping', function () {
+      // Initial mapping: abc → efg
+      cache.setMapping('abc', 'efg');
+      expect(cache.getMappedId('abc')).to.equal('efg');
+
+      // New mapping: efg → hij
+      // Should also update abc → hij
+      cache.setMapping('efg', 'hij');
+
+      expect(cache.getMappedId('abc')).to.equal('hij'); // Transitive update
+      expect(cache.getMappedId('efg')).to.equal('hij'); // Direct mapping
+    });
+
+    it('should handle multiple transitive chains', function () {
+      // Create chain: a → b, c → b
+      cache.setMapping('a', 'b');
+      cache.setMapping('c', 'b');
+
+      expect(cache.getMappedId('a')).to.equal('b');
+      expect(cache.getMappedId('c')).to.equal('b');
+
+      // Now b → d should update both a and c
+      cache.setMapping('b', 'd');
+
+      expect(cache.getMappedId('a')).to.equal('d');
+      expect(cache.getMappedId('c')).to.equal('d');
+      expect(cache.getMappedId('b')).to.equal('d');
+    });
+
+    it('should handle deep transitive chains', function () {
+      // Create chain: x → y → z
+      cache.setMapping('x', 'y');
+      cache.setMapping('y', 'z');
+
+      expect(cache.getMappedId('x')).to.equal('z');
+      expect(cache.getMappedId('y')).to.equal('z');
+
+      // Now z → w should update all
+      cache.setMapping('z', 'w');
+
+      expect(cache.getMappedId('x')).to.equal('w');
+      expect(cache.getMappedId('y')).to.equal('w');
+      expect(cache.getMappedId('z')).to.equal('w');
+    });
+  });
+
+  describe('cleanup', function () {
+    it('should remove expired entries', function () {
+      const shortTtlCache = new ElementReferenceCache({
+        ...defaultConfig,
+        elementTtlMs: 10, // 10ms TTL
+      });
+
+      shortTtlCache.cacheElement('elem-1', 'id', 'btn1');
+
+      return new Promise((resolve) => {
+        setTimeout(() => {
+          shortTtlCache.cleanup();
+          expect(shortTtlCache.size).to.equal(0);
+          resolve();
+        }, 20);
+      });
+    });
+  });
+
+  describe('clear', function () {
+    it('should remove all entries', function () {
+      cache.cacheElement('elem-1', 'id', 'btn1');
+      cache.cacheElement('elem-2', 'id', 'btn2');
+      cache.setMapping('old', 'new');
+
+      expect(cache.size).to.equal(2);
+      expect(cache.mappingsCount).to.equal(1);
+
+      cache.clear();
+
+      expect(cache.size).to.equal(0);
+      expect(cache.mappingsCount).to.equal(0);
+    });
+  });
+});

package/test/unit/plugin.spec.js

@@ -0,0 +1,52 @@
+import sinon from 'sinon';
+import plugin from '../../lib/plugin.js';
+import { BasePlugin } from '@appium/base-plugin';
+
+const UIWatchersPlugin = plugin.default || plugin;
+
+describe('UIWatchersPlugin', function () {
+  let sandbox;
+
+  before(async function () {
+    const chai = await import('chai');
+    const chaiAsPromised = await import('chai-as-promised');
+    chai.use(chaiAsPromised.default);
+    chai.should();
+  });
+
+  beforeEach(function () {
+    sandbox = sinon.createSandbox();
+  });
+
+  afterEach(function () {
+    sandbox.restore();
+  });
+
+  describe('constructor', function () {
+    it('should create a new plugin instance', function () {
+      const pluginInstance = new UIWatchersPlugin('uiwatchers');
+      pluginInstance.should.exist;
+    });
+
+    it('should extend BasePlugin', function () {
+      const pluginInstance = new UIWatchersPlugin('uiwatchers');
+      pluginInstance.should.be.instanceOf(BasePlugin);
+    });
+
+    it('should have the correct class name', function () {
+      const pluginInstance = new UIWatchersPlugin('uiwatchers');
+      pluginInstance.constructor.name.should.equal('UIWatchersPlugin');
+    });
+
+    it('should accept optional CLI arguments', function () {
+      const cliArgs = { verbose: true };
+      const pluginInstance = new UIWatchersPlugin('uiwatchers', cliArgs);
+      pluginInstance.should.exist;
+    });
+
+    it('should initialize without CLI arguments', function () {
+      const pluginInstance = new UIWatchersPlugin('uiwatchers');
+      pluginInstance.should.exist;
+    });
+  });
+});