appium-uiwatchers-plugin 1.0.0

package/src/commands/register.ts

@@ -0,0 +1,47 @@
+/**
+ * registerUIWatcher command implementation
+ */
+
+import { logger } from '@appium/support';
+import type { WatcherStore } from '../watcher-store.js';
+import type { UIWatcher, RegisterWatcherResult } from '../types.js';
+import { validateWatcherParams } from '../validators.js';
+
+const log = logger.getLogger('AppiumUIWatchers');
+
+/**
+ * Register a new UI watcher
+ * @param store - Watcher store instance
+ * @param params - Watcher registration parameters
+ * @returns Registration result
+ */
+export async function registerUIWatcher(
+  store: WatcherStore,
+  params: UIWatcher
+): Promise<RegisterWatcherResult> {
+  // Get configuration from store
+  const config = store.getConfig();
+
+  // Validate parameters with configured max duration
+  validateWatcherParams(params, config.maxDurationMs);
+
+  // Add watcher to store (this will throw if validation fails at store level)
+  const watcherState = store.add(params);
+
+  // Log successful registration
+  log.info(
+    `[UIWatchers] UIWatcher '${params.name}' registered (priority=${watcherState.priority}, duration=${params.duration}ms)`
+  );
+
+  // Return success response
+  return {
+    success: true,
+    watcher: {
+      name: watcherState.name,
+      priority: watcherState.priority,
+      registeredAt: watcherState.registeredAt,
+      expiresAt: watcherState.expiresAt,
+      status: watcherState.status,
+    },
+  };
+}

package/src/commands/toggle.ts

@@ -0,0 +1,43 @@
+/**
+ * disableUIWatchers and enableUIWatchers command implementations
+ */
+
+import { logger } from '@appium/support';
+import type { WatcherStore } from '../watcher-store.js';
+import type { ToggleWatchersResult } from '../types.js';
+
+const log = logger.getLogger('AppiumUIWatchers');
+
+/**
+ * Disable all UI watcher checking
+ * @param store - Watcher store instance
+ * @returns Disable result
+ */
+export async function disableUIWatchers(store: WatcherStore): Promise<ToggleWatchersResult> {
+  store.disable();
+
+  // Log successful disable
+  log.info('[UIWatchers] All UI watchers disabled');
+
+  return {
+    success: true,
+    message: 'All UI watchers disabled',
+  };
+}
+
+/**
+ * Enable all UI watcher checking
+ * @param store - Watcher store instance
+ * @returns Enable result
+ */
+export async function enableUIWatchers(store: WatcherStore): Promise<ToggleWatchersResult> {
+  store.enable();
+
+  // Log successful enable
+  log.info('[UIWatchers] All UI watchers enabled');
+
+  return {
+    success: true,
+    message: 'All UI watchers enabled',
+  };
+}

package/src/commands/unregister.ts

@@ -0,0 +1,43 @@
+/**
+ * unregisterUIWatcher command implementation
+ */
+
+import { logger } from '@appium/support';
+import type { WatcherStore } from '../watcher-store.js';
+import type { UnregisterWatcherResult } from '../types.js';
+
+const log = logger.getLogger('AppiumUIWatchers');
+
+/**
+ * Unregister a specific UI watcher by name
+ * @param store - Watcher store instance
+ * @param name - Name of the watcher to remove
+ * @returns Unregistration result
+ */
+export async function unregisterUIWatcher(
+  store: WatcherStore,
+  name: string
+): Promise<UnregisterWatcherResult> {
+  // Validate name parameter
+  if (!name || typeof name !== 'string') {
+    throw new Error('UIWatcher name is required');
+  }
+
+  // Check if watcher exists
+  const watcher = store.get(name);
+  if (!watcher) {
+    throw new Error(`UIWatcher '${name}' not found`);
+  }
+
+  // Remove watcher from store
+  store.remove(name);
+
+  // Log successful removal
+  log.info(`[UIWatchers] UIWatcher '${name}' unregistered`);
+
+  // Return success response
+  return {
+    success: true,
+    removed: name,
+  };
+}

package/src/config.ts

@@ -0,0 +1,30 @@
+/**
+ * Configuration module for UI Watchers Plugin
+ */
+
+/**
+ * Plugin configuration interface
+ */
+export interface PluginConfig {
+  /** Maximum number of watchers allowed per session (1-20) */
+  maxWatchers?: number;
+
+  /** Maximum duration per watcher in milliseconds (1000-600000) */
+  maxDurationMs?: number;
+
+  /** Maximum element references to cache for stale recovery (10-200) */
+  maxCacheEntries?: number;
+
+  /** TTL for cached element references in milliseconds (5000-300000) */
+  elementTtlMs?: number;
+}
+
+/**
+ * Default configuration values
+ */
+export const DefaultPluginConfig: Required<PluginConfig> = {
+  maxWatchers: 5,
+  maxDurationMs: 60000,
+  maxCacheEntries: 50,
+  elementTtlMs: 60000,
+};

package/src/element-cache.ts

@@ -0,0 +1,262 @@
+/**
+ * Element Reference Cache for StaleElement Recovery
+ *
+ * This module provides caching of element locators to enable automatic recovery
+ * from StaleElementReferenceException on element action commands.
+ */
+
+import { logger } from '@appium/support';
+import type { CachedRef, CachedElementRef, CachedElementsRef } from './types.js';
+import type { PluginConfig } from './config.js';
+import { extractElementId, type ElementObject } from './utils.js';
+
+const log = logger.getLogger('AppiumUIWatchers');
+
+/**
+ * Configuration for ElementReferenceCache
+ */
+export interface CacheConfig {
+  maxCacheEntries: number;
+  elementTtlMs: number;
+}
+
+/**
+ * ElementReferenceCache manages cached element locators for stale element recovery.
+ *
+ * Features:
+ * - Caches element locators on successful findElement/findElements
+ * - Provides element ID mapping for recovered elements
+ * - Supports transitive mapping updates (abc→efg, efg→hij => abc→hij)
+ * - LRU eviction when max entries reached
+ * - TTL-based expiry for old entries
+ */
+export class ElementReferenceCache {
+  /** Cache storage: elementId → CachedRef */
+  private cache: Map<string, CachedRef>;
+
+  /** Element ID mappings: oldId → newId */
+  private idMappings: Map<string, string>;
+
+  /** Reverse index for transitive updates: newId → Set<oldId> */
+  private reverseIndex: Map<string, Set<string>>;
+
+  /** LRU order tracking (most recent at end) */
+  private accessOrder: string[];
+
+  /** Configuration */
+  private config: CacheConfig;
+
+  constructor(config: Required<PluginConfig>) {
+    this.cache = new Map();
+    this.idMappings = new Map();
+    this.reverseIndex = new Map();
+    this.accessOrder = [];
+    this.config = {
+      maxCacheEntries: config.maxCacheEntries,
+      elementTtlMs: config.elementTtlMs,
+    };
+  }
+
+  /**
+   * Cache an element reference from findElement
+   */
+  cacheElement(elementId: string, using: string, value: string): void {
+    const ref: CachedElementRef = {
+      using,
+      value,
+      source: 'findElement',
+      createdAt: Date.now(),
+    };
+
+    this.addToCache(elementId, ref);
+    log.debug(`[UIWatchers] Cached element reference: ${elementId} (${using}=${value})`);
+  }
+
+  /**
+   * Cache element references from findElements
+   * Each element is cached with its index position
+   */
+  cacheElements(elements: ElementObject[], using: string, value: string): void {
+    for (let i = 0; i < elements.length; i++) {
+      const element = elements[i];
+      const elementId = extractElementId(element);
+      if (!elementId) continue;
+
+      const ref: CachedElementsRef = {
+        using,
+        value,
+        index: i,
+        source: 'findElements',
+        createdAt: Date.now(),
+      };
+
+      this.addToCache(elementId, ref);
+    }
+    log.debug(
+      `[UIWatchers] Cached ${elements.length} element references from findElements (${using}=${value})`
+    );
+  }
+
+  /**
+   * Get cached reference for an element
+   * Returns undefined if not found or expired
+   */
+  getRef(elementId: string): CachedRef | undefined {
+    const ref = this.cache.get(elementId);
+    if (!ref) return undefined;
+
+    // Check TTL
+    if (this.isExpired(ref)) {
+      this.removeFromCache(elementId);
+      return undefined;
+    }
+
+    // Update LRU order
+    this.updateAccessOrder(elementId);
+
+    return ref;
+  }
+
+  /**
+   * Create element ID mapping with transitive update
+   *
+   * When we map oldId → newId, we also update any existing mappings
+   * that point to oldId to instead point to newId.
+   *
+   * Example:
+   *   Existing: abc → efg
+   *   New mapping: efg → hij
+   *   Result: abc → hij, efg → hij
+   */
+  setMapping(oldId: string, newId: string): void {
+    // Step 1: Find all mappings where value == oldId (using reverse index)
+    const pointingToOld = this.reverseIndex.get(oldId);
+    if (pointingToOld) {
+      // Update all these mappings to point to newId
+      for (const sourceId of pointingToOld) {
+        this.idMappings.set(sourceId, newId);
+        // Update reverse index
+        this.addToReverseIndex(sourceId, newId);
+      }
+      // Remove old reverse index entry
+      this.reverseIndex.delete(oldId);
+    }
+
+    // Step 2: Add the new mapping
+    this.idMappings.set(oldId, newId);
+    this.addToReverseIndex(oldId, newId);
+
+    log.debug(`[UIWatchers] Created element ID mapping: ${oldId} → ${newId}`);
+  }
+
+  /**
+   * Get mapped element ID if exists
+   * Returns the new ID if a mapping exists, otherwise returns undefined
+   */
+  getMappedId(elementId: string): string | undefined {
+    return this.idMappings.get(elementId);
+  }
+
+  /**
+   * Remove expired entries from cache
+   */
+  cleanup(): void {
+    const now = Date.now();
+    const toRemove: string[] = [];
+
+    for (const [elementId, ref] of this.cache) {
+      if (now - ref.createdAt >= this.config.elementTtlMs) {
+        toRemove.push(elementId);
+      }
+    }
+
+    for (const elementId of toRemove) {
+      this.removeFromCache(elementId);
+    }
+
+    if (toRemove.length > 0) {
+      log.debug(`[UIWatchers] Cleaned up ${toRemove.length} expired cache entries`);
+    }
+  }
+
+  /**
+   * Clear all cache entries and mappings
+   */
+  clear(): void {
+    const count = this.cache.size;
+    this.cache.clear();
+    this.idMappings.clear();
+    this.reverseIndex.clear();
+    this.accessOrder = [];
+    log.debug(`[UIWatchers] Cleared element cache (${count} entries)`);
+  }
+
+  /**
+   * Get current cache size
+   */
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Get current mappings count
+   */
+  get mappingsCount(): number {
+    return this.idMappings.size;
+  }
+
+  // ============================================================================
+  // Private helper methods
+  // ============================================================================
+
+  private addToCache(elementId: string, ref: CachedRef): void {
+    // Evict if at capacity
+    while (this.cache.size >= this.config.maxCacheEntries) {
+      this.evictLRU();
+    }
+
+    this.cache.set(elementId, ref);
+    this.updateAccessOrder(elementId);
+  }
+
+  private removeFromCache(elementId: string): void {
+    this.cache.delete(elementId);
+    // Remove from access order
+    const index = this.accessOrder.indexOf(elementId);
+    if (index !== -1) {
+      this.accessOrder.splice(index, 1);
+    }
+  }
+
+  private evictLRU(): void {
+    if (this.accessOrder.length === 0) return;
+
+    // Remove least recently used (first in array)
+    const lruId = this.accessOrder.shift();
+    if (lruId) {
+      this.cache.delete(lruId);
+      log.debug(`[UIWatchers] Evicted LRU cache entry: ${lruId}`);
+    }
+  }
+
+  private updateAccessOrder(elementId: string): void {
+    // Remove from current position
+    const index = this.accessOrder.indexOf(elementId);
+    if (index !== -1) {
+      this.accessOrder.splice(index, 1);
+    }
+    // Add to end (most recently used)
+    this.accessOrder.push(elementId);
+  }
+
+  private isExpired(ref: CachedRef): boolean {
+    return Date.now() - ref.createdAt >= this.config.elementTtlMs;
+  }
+
+  private addToReverseIndex(oldId: string, newId: string): void {
+    if (!this.reverseIndex.has(newId)) {
+      this.reverseIndex.set(newId, new Set());
+    }
+    this.reverseIndex.get(newId)!.add(oldId);
+  }
+}