appium-uiwatchers-plugin 1.0.0

package/src/plugin.ts

@@ -0,0 +1,437 @@
+import { BasePlugin } from '@appium/base-plugin';
+import { logger } from '@appium/support';
+import { WatcherStore } from './watcher-store.js';
+import { ElementReferenceCache } from './element-cache.js';
+import { registerUIWatcher } from './commands/register.js';
+import { unregisterUIWatcher } from './commands/unregister.js';
+import { clearAllUIWatchers } from './commands/clear.js';
+import { listUIWatchers } from './commands/list.js';
+import { disableUIWatchers, enableUIWatchers } from './commands/toggle.js';
+import { checkWatchers } from './watcher-checker.js';
+import { DefaultPluginConfig, type PluginConfig } from './config.js';
+import { extractElementId } from './utils.js';
+
+const log = logger.getLogger('AppiumUIWatchers');
+
+/**
+ * Element action commands to intercept for StaleElement recovery
+ * These are Appium command names that operate on elements
+ */
+const ELEMENT_ACTION_COMMANDS = [
+  'click',
+  'getText',
+  'getAttribute',
+  'elementDisplayed',
+  'elementEnabled',
+  'elementSelected',
+  'getName',
+  'getLocation',
+  'getSize',
+  'setValue',
+  'setValueImmediate',
+  'clear',
+  'getElementScreenshot',
+  'getElementRect',
+];
+
+/**
+ * UIWatchersPlugin - Appium plugin for automatic UI element handling
+ *
+ * This plugin provides automatic detection and handling of unexpected UI elements
+ * (popups, banners, dialogs) during test execution without explicit waits.
+ */
+class UIWatchersPlugin extends BasePlugin {
+  /** Per-session watcher storage (keyed by sessionId) */
+  private stores: Map<string, WatcherStore>;
+
+  /** Per-session element reference cache (keyed by sessionId) */
+  private caches: Map<string, ElementReferenceCache>;
+
+  /** Plugin configuration */
+  private config: Required<PluginConfig>;
+
+  /**
+   * Creates an instance of UIWatchersPlugin
+   * @param pluginName - The name of the plugin
+   * @param cliArgs - Optional CLI arguments passed to the plugin
+   */
+  constructor(pluginName: string, cliArgs?: Record<string, unknown>) {
+    super(pluginName, cliArgs);
+
+    this.config = Object.assign({}, DefaultPluginConfig, cliArgs as PluginConfig);
+
+    this.stores = new Map();
+    this.caches = new Map();
+    log.info('[UIWatchers] Plugin initialized with config:', this.config);
+  }
+
+  /**
+   * Get or create WatcherStore for a specific session
+   * @param driver - The driver instance containing sessionId
+   * @returns The WatcherStore for this session
+   * @throws Error if no sessionId is available
+   */
+  private getStore(driver: any): WatcherStore {
+    const sessionId = driver.sessionId;
+    if (!sessionId) {
+      throw new Error('No session ID available');
+    }
+
+    if (!this.stores.has(sessionId)) {
+      this.stores.set(sessionId, new WatcherStore(this.config));
+      log.info(`[UIWatchers] Created watcher store for session ${sessionId}`);
+    }
+
+    return this.stores.get(sessionId)!;
+  }
+
+  /**
+   * Get or create ElementReferenceCache for a specific session
+   * @param driver - The driver instance containing sessionId
+   * @returns The ElementReferenceCache for this session
+   * @throws Error if no sessionId is available
+   */
+  private getCache(driver: any): ElementReferenceCache {
+    const sessionId = driver.sessionId;
+    if (!sessionId) {
+      throw new Error('No session ID available');
+    }
+
+    if (!this.caches.has(sessionId)) {
+      this.caches.set(sessionId, new ElementReferenceCache(this.config));
+      log.info(`[UIWatchers] Created element cache for session ${sessionId}`);
+    }
+
+    return this.caches.get(sessionId)!;
+  }
+
+  /**
+   * Check if error is a StaleElementReferenceException
+   */
+  private isStaleElementException(error: any): boolean {
+    const errorName = error?.name || error?.error || '';
+    return (
+      errorName.includes('StaleElementReference') ||
+      error?.message?.includes('stale element reference') ||
+      error?.message?.includes('element is not attached')
+    );
+  }
+
+  /**
+   * Override execute command to handle mobile: commands
+   */
+  async execute(next: () => Promise<any>, driver: any, script: string, args: any[]): Promise<any> {
+    const params = args && args.length > 0 ? args[0] : null;
+    const store = this.getStore(driver);
+
+    switch (script) {
+      case 'mobile: registerUIWatcher':
+        return await registerUIWatcher(store, params);
+      case 'mobile: unregisterUIWatcher':
+        return await unregisterUIWatcher(store, params.name);
+      case 'mobile: clearAllUIWatchers':
+        return await clearAllUIWatchers(store);
+      case 'mobile: listUIWatchers':
+        return await listUIWatchers(store);
+      case 'mobile: disableUIWatchers':
+        return await disableUIWatchers(store);
+      case 'mobile: enableUIWatchers':
+        return await enableUIWatchers(store);
+      default:
+        return await next();
+    }
+  }
+
+  /**
+   * Intercept findElement to check watchers on exceptions and cache on success
+   */
+  async findElement(next: () => Promise<any>, driver: any, ...args: any[]): Promise<any> {
+    const [using, value] = args;
+
+    try {
+      // Try the original findElement
+      const result = await next();
+
+      // On success, cache the element reference for stale element recovery
+      if (result && using && value) {
+        const elementId = extractElementId(result);
+        if (elementId) {
+          const cache = this.getCache(driver);
+          cache.cacheElement(elementId, using, value);
+        }
+      }
+
+      return result;
+    } catch (error: any) {
+      // Check if this is NoSuchElementException or StaleElementReferenceException
+      const errorName = error.name || error.error || '';
+      const shouldCheckWatchers =
+        errorName.includes('NoSuchElement') ||
+        errorName.includes('StaleElementReference') ||
+        error.message?.includes('An element could not be located');
+
+      if (shouldCheckWatchers) {
+        log.debug('[UIWatchers] findElement failed, checking watchers');
+
+        try {
+          const store = this.getStore(driver);
+          // Check all watchers
+          await checkWatchers(driver, store);
+
+          // Retry findElement once
+          log.debug('[UIWatchers] Retrying findElement after watcher checking');
+          const result = await next();
+
+          // Cache the successful retry result
+          if (result && using && value) {
+            const elementId = extractElementId(result);
+            if (elementId) {
+              const cache = this.getCache(driver);
+              cache.cacheElement(elementId, using, value);
+            }
+          }
+
+          return result;
+        } catch {
+          // If retry also fails, throw the original exception
+          log.debug('[UIWatchers] Retry failed, throwing original exception');
+          throw error;
+        }
+      }
+
+      // Not a handled exception type, re-throw
+      throw error;
+    }
+  }
+
+  /**
+   * Intercept findElements to check watchers on empty results and cache on success
+   */
+  async findElements(next: () => Promise<any>, driver: any, ...args: any[]): Promise<any> {
+    const [using, value] = args;
+
+    try {
+      // Try the original findElements
+      const result = await next();
+
+      // Check if result is empty array
+      if (Array.isArray(result) && result.length === 0) {
+        log.debug('[UIWatchers] findElements returned empty array, checking watchers');
+
+        try {
+          const store = this.getStore(driver);
+          // Check all watchers
+          await checkWatchers(driver, store);
+
+          // Retry findElements once
+          log.debug('[UIWatchers] Retrying findElements after watcher checking');
+          const retryResult = await next();
+
+          // Cache successful retry results
+          if (Array.isArray(retryResult) && retryResult.length > 0 && using && value) {
+            const cache = this.getCache(driver);
+            cache.cacheElements(retryResult, using, value);
+          }
+
+          return retryResult;
+        } catch {
+          // If retry fails, return empty array (original result)
+          log.debug('[UIWatchers] Retry failed, returning empty array');
+          return result;
+        }
+      }
+
+      // Non-empty result, cache all elements and return
+      if (Array.isArray(result) && result.length > 0 && using && value) {
+        const cache = this.getCache(driver);
+        cache.cacheElements(result, using, value);
+      }
+
+      return result;
+    } catch (error: any) {
+      // Exception thrown by findElements
+      log.debug('[UIWatchers] findElements threw exception, checking watchers');
+
+      try {
+        const store = this.getStore(driver);
+        // Check all watchers
+        await checkWatchers(driver, store);
+
+        // Retry findElements once
+        log.debug('[UIWatchers] Retrying findElements after watcher checking');
+        const result = await next();
+
+        // Cache successful retry results
+        if (Array.isArray(result) && result.length > 0 && using && value) {
+          const cache = this.getCache(driver);
+          cache.cacheElements(result, using, value);
+        }
+
+        return result;
+      } catch {
+        // If retry also fails, throw the original exception
+        log.debug('[UIWatchers] Retry failed, throwing original exception');
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * Handle method intercepts all Appium commands not specifically handled by named methods
+   * We use this to intercept element action commands (click, getText, etc.) for StaleElement recovery
+   */
+  async handle(
+    next: () => Promise<any>,
+    driver: any,
+    cmdName: string,
+    ...args: any[]
+  ): Promise<any> {
+    // Only intercept element action commands
+    if (!ELEMENT_ACTION_COMMANDS.includes(cmdName)) {
+      return await next();
+    }
+
+    // Extract elementId from args (first argument for element commands)
+    const elementId = args[0];
+    if (!elementId) {
+      return await next();
+    }
+
+    return this.interceptAction(next, driver, elementId, cmdName, args);
+  }
+
+  /**
+   * Intercept element action commands for StaleElement recovery
+   */
+  private async interceptAction(
+    next: () => Promise<any>,
+    driver: any,
+    elementId: string,
+    cmdName: string,
+    args: any[]
+  ): Promise<any> {
+    const cache = this.getCache(driver);
+
+    // Check for mapped ID first (from previous recovery)
+    const actualId = cache.getMappedId(elementId) || elementId;
+
+    try {
+      return await next();
+    } catch (error: any) {
+      // Only handle StaleElementReferenceException
+      if (!this.isStaleElementException(error)) {
+        throw error;
+      }
+
+      log.debug(`[UIWatchers] StaleElement on ${cmdName}, checking watchers`);
+
+      // Step 1: Check watchers FIRST
+      const store = this.getStore(driver);
+      const watchersTriggered = await checkWatchers(driver, store);
+
+      // Step 2: If no watchers handled, throw original exception
+      if (!watchersTriggered) {
+        log.debug('[UIWatchers] No watchers triggered, throwing original exception');
+        throw error;
+      }
+
+      // Step 3: Lookup cached reference (only if watchers handled something)
+      const ref = cache.getRef(actualId);
+      if (!ref) {
+        log.error(`[UIWatchers] Element reference not found in cache for ${actualId}`);
+        throw new Error(
+          'Element reference not found in cache. Unable to recover from StaleElementReferenceException.'
+        );
+      }
+
+      log.debug(
+        `[UIWatchers] Attempting to recover element using cached locator (${ref.using}=${ref.value})`
+      );
+
+      // Step 4: Re-find element
+      let newElement: any;
+      if (ref.source === 'findElement') {
+        newElement = await driver.findElement(ref.using, ref.value);
+      } else {
+        // findElements - need to get element at specific index
+        const elements = await driver.findElements(ref.using, ref.value);
+        if (elements.length <= ref.index) {
+          throw new Error(
+            `Element at index ${ref.index} not found in findElements result. Expected at least ${ref.index + 1} elements.`
+          );
+        }
+        newElement = elements[ref.index];
+      }
+
+      // Step 5: Create mapping with transitive update
+      const newId = extractElementId(newElement);
+      if (newId) {
+        cache.setMapping(elementId, newId);
+        log.debug(`[UIWatchers] Created element ID mapping: ${elementId} → ${newId}`);
+
+        // Step 6: Retry action with new element ID
+        // Replace elementId in args with newId, then call driver command
+        const newArgs = [newId, ...args.slice(1)];
+        log.debug(`[UIWatchers] Retrying ${cmdName} with recovered element`);
+        return await driver[cmdName](...newArgs);
+      }
+
+      // If we couldn't extract newId, throw original error
+      throw error;
+    }
+  }
+
+  /**
+   * Cleanup watcher store and element cache when session ends normally
+   * Appium lifecycle hook called when deleteSession is invoked
+   */
+  async deleteSession(next: () => Promise<any>, driver: any, ..._args: any[]): Promise<any> {
+    const sessionId = driver.sessionId;
+
+    // Call the original deleteSession first
+    const result = await next();
+
+    // Clean up our session-specific store and cache
+    if (sessionId) {
+      if (this.stores.has(sessionId)) {
+        this.stores.delete(sessionId);
+        log.info(`[UIWatchers] Cleaned up watcher store for session ${sessionId}`);
+      }
+      if (this.caches.has(sessionId)) {
+        this.caches.get(sessionId)!.clear();
+        this.caches.delete(sessionId);
+        log.info(`[UIWatchers] Cleaned up element cache for session ${sessionId}`);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Cleanup watcher store and element cache when session ends unexpectedly (crash, timeout, etc.)
+   * Appium lifecycle hook called on unexpected shutdown
+   */
+  async onUnexpectedShutdown(driver: any, cause: string): Promise<void> {
+    const sessionId = driver.sessionId;
+
+    if (sessionId) {
+      if (this.stores.has(sessionId)) {
+        this.stores.delete(sessionId);
+        log.info(
+          `[UIWatchers] Cleaned up watcher store for session ${sessionId} (cause: ${cause})`
+        );
+      }
+      if (this.caches.has(sessionId)) {
+        this.caches.get(sessionId)!.clear();
+        this.caches.delete(sessionId);
+        log.info(
+          `[UIWatchers] Cleaned up element cache for session ${sessionId} (cause: ${cause})`
+        );
+      }
+    }
+  }
+}
+
+// Export as both default and named export for compatibility
+export { UIWatchersPlugin };
+export default UIWatchersPlugin;

package/src/types.ts

@@ -0,0 +1,207 @@
+/**
+ * Type definitions for Appium UI Watchers Plugin
+ */
+
+/**
+ * Appium locator strategy definition
+ * Represents a standard Appium element locator
+ */
+export interface Locator {
+  /** Locator strategy (e.g., 'id', 'xpath', 'accessibility id') */
+  using: string;
+  /** Locator value/selector */
+  value: string;
+}
+
+/**
+ * UI Watcher registration parameters
+ * These are the parameters passed when registering a new watcher
+ */
+export interface UIWatcher {
+  /** Unique identifier for the watcher */
+  name: string;
+
+  /**
+   * Priority level for watcher execution (higher values checked first)
+   * @default 0
+   */
+  priority?: number;
+
+  /** Locator for the element to watch for (e.g., popup, banner) */
+  referenceLocator: Locator;
+
+  /** Locator for the element to click when reference is found */
+  actionLocator: Locator;
+
+  /**
+   * Time in milliseconds before watcher auto-expires from registration time
+   * Must be ≤ 60000ms (1 minute)
+   */
+  duration: number;
+
+  /**
+   * If true, deactivate watcher after first successful trigger
+   * @default false
+   */
+  stopOnFound?: boolean;
+
+  /**
+   * Cooldown period in milliseconds after successful action click
+   * Watcher skipped during cooldown. Ignored if stopOnFound=true
+   * @default 0
+   */
+  cooldownMs?: number;
+}
+
+/**
+ * Internal watcher state representation
+ * Used for managing watcher lifecycle and tracking trigger information
+ */
+export interface WatcherState {
+  /** Unique identifier for the watcher */
+  name: string;
+
+  /** Priority level for watcher execution */
+  priority: number;
+
+  /** Locator for the element to watch for */
+  referenceLocator: Locator;
+
+  /** Locator for the element to click when reference is found */
+  actionLocator: Locator;
+
+  /** Duration in milliseconds before auto-expiry */
+  duration: number;
+
+  /** If true, deactivate after first trigger */
+  stopOnFound: boolean;
+
+  /** Cooldown period in milliseconds */
+  cooldownMs: number;
+
+  /** Timestamp when watcher was registered (milliseconds since epoch) */
+  registeredAt: number;
+
+  /** Timestamp when watcher expires (milliseconds since epoch) */
+  expiresAt: number;
+
+  /** Current watcher status */
+  status: 'active' | 'inactive';
+
+  /** Number of times watcher has been triggered */
+  triggerCount: number;
+
+  /** Timestamp of last trigger (null if never triggered) */
+  lastTriggeredAt: number | null;
+}
+
+/**
+ * Result returned by registerUIWatcher command
+ */
+export interface RegisterWatcherResult {
+  /** Operation success status */
+  success: boolean;
+
+  /** Watcher information after registration */
+  watcher: {
+    name: string;
+    priority: number;
+    registeredAt: number;
+    expiresAt: number;
+    status: 'active' | 'inactive';
+  };
+}
+
+/**
+ * Result returned by unregisterUIWatcher command
+ */
+export interface UnregisterWatcherResult {
+  /** Operation success status */
+  success: boolean;
+
+  /** Name of the removed watcher */
+  removed: string;
+}
+
+/**
+ * Result returned by clearAllUIWatchers command
+ */
+export interface ClearAllWatchersResult {
+  /** Operation success status */
+  success: boolean;
+
+  /** Number of watchers removed */
+  removedCount: number;
+}
+
+/**
+ * Result returned by listUIWatchers command
+ */
+export interface ListWatchersResult {
+  /** Operation success status */
+  success: boolean;
+
+  /** List of all active watchers with their state */
+  watchers: WatcherState[];
+
+  /** Total count of watchers */
+  totalCount: number;
+}
+
+/**
+ * Result returned by disableUIWatchers/enableUIWatchers commands
+ */
+export interface ToggleWatchersResult {
+  /** Operation success status */
+  success: boolean;
+
+  /** Status message */
+  message: string;
+}
+
+// ============================================================================
+// Element Reference Caching Types (for StaleElement recovery)
+// ============================================================================
+
+/**
+ * Cached reference for element from findElement
+ */
+export interface CachedElementRef {
+  /** Locator strategy used to find the element */
+  using: string;
+
+  /** Locator value used to find the element */
+  value: string;
+
+  /** Source operation that found this element */
+  source: 'findElement';
+
+  /** Timestamp when this reference was cached */
+  createdAt: number;
+}
+
+/**
+ * Cached reference for element from findElements
+ * Includes the index position in the result array
+ */
+export interface CachedElementsRef {
+  /** Locator strategy used to find the elements */
+  using: string;
+
+  /** Locator value used to find the elements */
+  value: string;
+
+  /** Index position of this element in the findElements result array */
+  index: number;
+
+  /** Source operation that found this element */
+  source: 'findElements';
+
+  /** Timestamp when this reference was cached */
+  createdAt: number;
+}
+
+/**
+ * Union type for cached element references
+ */
+export type CachedRef = CachedElementRef | CachedElementsRef;

package/src/utils.ts

@@ -0,0 +1,47 @@
+/**
+ * Utility functions for UI Watchers Plugin
+ */
+
+/**
+ * W3C WebDriver Element Identifier key
+ * This is the standard key used in W3C WebDriver protocol to identify elements
+ */
+export const W3C_ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf';
+
+/**
+ * Element object type that supports both W3C and JSONWP formats
+ */
+export interface ElementObject {
+  ELEMENT?: string;
+  [W3C_ELEMENT_KEY]?: string;
+}
+
+/**
+ * Extract element ID from element object
+ * Handles W3C format, JSONWP format, and direct string IDs
+ *
+ * @param element - Element object or string ID
+ * @returns The element ID string, or undefined if not found
+ */
+export function extractElementId(
+  element: ElementObject | string | null | undefined
+): string | undefined {
+  if (!element) return undefined;
+
+  // Direct string ID
+  if (typeof element === 'string') {
+    return element;
+  }
+
+  // W3C format
+  if (element[W3C_ELEMENT_KEY]) {
+    return element[W3C_ELEMENT_KEY];
+  }
+
+  // JSONWP format
+  if (element.ELEMENT) {
+    return element.ELEMENT;
+  }
+
+  return undefined;
+}