appium-uiwatchers-plugin 1.0.0 → 1.0.1

package/src/validators.ts

@@ -1,131 +0,0 @@
-/**
- * Validation functions for UI Watcher registration parameters
- */
-
-/**
- * Valid Appium locator strategies
- */
-const VALID_LOCATOR_STRATEGIES = [
-  'id',
-  'accessibility id',
-  'class name',
-  'xpath',
-  'name',
-  '-android uiautomator',
-  '-ios predicate string',
-  '-ios class chain',
-  'css selector',
-];
-
-/**
- * Validates a locator object
- * @param locator - The locator to validate
- * @param fieldName - Name of the field for error messages
- * @throws Error if locator is invalid
- */
-export function validateLocator(locator: any, fieldName: string): void {
-  // Check if locator exists
-  if (!locator || typeof locator !== 'object') {
-    throw new Error(`${fieldName} is required`);
-  }
-
-  // Check if 'using' field exists and is a string
-  if (!locator.using) {
-    throw new Error(`'using' is mandatory for ${fieldName}`);
-  }
-
-  if (typeof locator.using !== 'string') {
-    throw new Error(`'using' must be string for ${fieldName} `);
-  }
-
-  // Check if 'value' field exists and is a string
-  if (!locator.value) {
-    throw new Error(`'value' is mandatory for ${fieldName}`);
-  }
-
-  if (typeof locator.value !== 'string') {
-    throw new Error(`'value' must be string for ${fieldName} `);
-  }
-
-  // Validate locator strategy (case-insensitive)
-  const strategy = locator.using.toLowerCase();
-  if (!VALID_LOCATOR_STRATEGIES.includes(strategy)) {
-    throw new Error(`Invalid locator strategy for ${fieldName}`);
-  }
-}
-
-/**
- * Validates all watcher registration parameters
- * @param params - Watcher registration parameters
- * @param maxDurationMs - Maximum allowed duration in milliseconds
- * @throws Error if any validation rule fails
- */
-export function validateWatcherParams(params: any, maxDurationMs: number): void {
-  // Check if params exists
-  if (!params || typeof params !== 'object') {
-    throw new Error('Invalid watcher parameters');
-  }
-
-  // Validate required field: name
-  if (!params.name) {
-    throw new Error('UIWatcher name is required');
-  }
-
-  if (typeof params.name !== 'string') {
-    throw new Error('UIWatcher name must be string type');
-  }
-
-  if (params.name.trim() === '') {
-    throw new Error('UIWatcher name is empty');
-  }
-
-  // Validate required field: referenceLocator
-  if (!params.referenceLocator) {
-    throw new Error('UIWatcher referenceLocator is required');
-  }
-  validateLocator(params.referenceLocator, 'referenceLocator');
-
-  // Validate required field: actionLocator
-  if (!params.actionLocator) {
-    throw new Error('UIWatcher actionLocator is required');
-  }
-  validateLocator(params.actionLocator, 'actionLocator');
-
-  // Validate required field: duration
-  if (params.duration === undefined || params.duration === null) {
-    throw new Error('UIWatcher duration is required');
-  }
-
-  if (typeof params.duration !== 'number' || params.duration <= 0) {
-    throw new Error('UIWatcher duration must be a positive number');
-  }
-
-  if (params.duration > maxDurationMs) {
-    throw new Error(`UIWatcher duration must be ≤ ${maxDurationMs / 1000} seconds`);
-  }
-
-  // Validate optional field: priority (if provided)
-  if (params.priority !== undefined && params.priority !== null) {
-    if (typeof params.priority !== 'number') {
-      throw new Error('UIWatcher priority must be a number');
-    }
-  }
-
-  // Validate optional field: stopOnFound (if provided)
-  if (params.stopOnFound !== undefined && params.stopOnFound !== null) {
-    if (typeof params.stopOnFound !== 'boolean') {
-      throw new Error('UIWatcher stopOnFound must be a boolean');
-    }
-  }
-
-  // Validate optional field: cooldownMs (if provided)
-  if (params.cooldownMs !== undefined && params.cooldownMs !== null) {
-    if (typeof params.cooldownMs !== 'number') {
-      throw new Error('UIWatcher cooldownMs must be a number');
-    }
-
-    if (params.cooldownMs < 0) {
-      throw new Error('UIWatcher cooldownMs must be ≥ 0');
-    }
-  }
-}

package/src/watcher-checker.ts

@@ -1,113 +0,0 @@
-/**
- * Core watcher checking algorithm
- */
-
-/* global setTimeout */
-
-import { logger } from '@appium/support';
-import type { WatcherStore } from './watcher-store.js';
-
-const log = logger.getLogger('AppiumUIWatchers');
-
-/**
- * Check all active watchers and execute actions for matching elements
- * @param driver - Appium driver instance
- * @param store - Watcher store instance
- * @returns true if at least one watcher was successfully triggered, false otherwise
- */
-export async function checkWatchers(driver: any, store: WatcherStore): Promise<boolean> {
-  // Track if any watcher was triggered
-  let watcherTriggered = false;
-
-  // Check if watchers are globally disabled
-  if (!store.isEnabled()) {
-    log.debug('[UIWatchers] Watcher checking is disabled, skipping');
-    return false;
-  }
-
-  // Get active, sorted watchers (by priority desc, then FIFO)
-  const watchers = store.getSortedWatchers();
-
-  // Early return if no active watchers
-  if (watchers.length === 0) {
-    log.debug('[UIWatchers] No active watchers to check');
-    return false;
-  }
-
-  log.debug(`[UIWatchers] Checking ${watchers.length} active watchers`);
-
-  // Check each watcher in priority order
-  for (const watcher of watchers) {
-    // Skip inactive watchers (marked inactive by stopOnFound)
-    if (watcher.status === 'inactive') {
-      log.debug(`[UIWatchers] Skipping inactive watcher '${watcher.name}'`);
-      continue;
-    }
-
-    log.debug(`[UIWatchers] Checking watcher '${watcher.name}' (priority=${watcher.priority})`);
-
-    try {
-      // Try to find the reference element
-      try {
-        await driver.findElement(watcher.referenceLocator.using, watcher.referenceLocator.value);
-      } catch {
-        // Reference element not found - continue to next watcher
-        log.debug(`[UIWatchers] Watcher '${watcher.name}': Reference element not found`);
-        continue;
-      }
-
-      // Reference element found
-      log.debug(`[UIWatchers] Watcher '${watcher.name}': Reference element found`);
-
-      // Try to find and click the action element
-      try {
-        const actionElement = await driver.findElement(
-          watcher.actionLocator.using,
-          watcher.actionLocator.value
-        );
-
-        // Click the action element
-        await driver.click(actionElement.ELEMENT || actionElement);
-
-        // Action click succeeded
-        log.info(`[UIWatchers] UIWatcher '${watcher.name}' triggered successfully`);
-        watcherTriggered = true;
-
-        // Update trigger statistics
-        store.incrementTriggerCount(watcher.name);
-
-        // Mark as inactive if stopOnFound is true
-        if (watcher.stopOnFound) {
-          store.markInactive(watcher.name);
-          log.debug(`[UIWatchers] Watcher '${watcher.name}' marked inactive (stopOnFound=true)`);
-        }
-
-        // Execute cooldown wait if configured
-        if (watcher.cooldownMs > 0) {
-          log.debug(
-            `[UIWatchers] Watcher '${watcher.name}': Executing cooldown wait (${watcher.cooldownMs}ms)`
-          );
-          await new Promise((resolve) => setTimeout(resolve, watcher.cooldownMs));
-          log.debug(`[UIWatchers] Watcher '${watcher.name}': Cooldown complete`);
-        }
-      } catch (clickError: any) {
-        // Action click failed
-        log.warn(
-          `[UIWatchers] UIWatcher '${watcher.name}' action click failed: ${clickError.message}`
-        );
-        // Continue to next watcher (don't execute cooldown or mark inactive)
-        continue;
-      }
-    } catch (error: any) {
-      // Unexpected error during watcher checking
-      log.error(
-        `[UIWatchers] Unexpected error checking watcher '${watcher.name}': ${error.message}`
-      );
-      // Continue to next watcher
-      continue;
-    }
-  }
-
-  log.debug(`[UIWatchers] Watcher checking complete (triggered=${watcherTriggered})`);
-  return watcherTriggered;
-}

package/src/watcher-store.ts

@@ -1,210 +0,0 @@
-/**
- * WatcherStore - In-memory storage for registered UI watchers
- */
-
-import type { WatcherState, UIWatcher } from './types.js';
-import type { PluginConfig } from './config.js';
-
-/**
- * WatcherStore manages the lifecycle and state of all registered UI watchers
- */
-export class WatcherStore {
-  /** Internal storage for watchers (keyed by watcher name) */
-  private watchers: Map<string, WatcherState>;
-
-  /** Global enable/disable flag for watcher checking */
-  private enabled: boolean;
-
-  /** Plugin configuration */
-  private config: Required<PluginConfig>;
-
-  constructor(config: Required<PluginConfig>) {
-    this.watchers = new Map();
-    this.enabled = true;
-    this.config = config;
-  }
-
-  /**
-   * Get the plugin configuration
-   * @returns The plugin configuration
-   */
-  getConfig(): Required<PluginConfig> {
-    return this.config;
-  }
-
-  /**
-   * Add a new watcher to the store
-   * @param watcher - Watcher registration parameters
-   * @returns The created watcher state
-   * @throws Error if validation fails
-   */
-  add(watcher: UIWatcher): WatcherState {
-    // Check for duplicate name
-    if (this.watchers.has(watcher.name)) {
-      throw new Error(`UIWatcher with name '${watcher.name}' already exists`);
-    }
-
-    // Check maximum watcher limit (count only non-expired watchers)
-    const activeCount = this.getActiveWatchers().length;
-    if (activeCount >= this.config.maxWatchers) {
-      throw new Error(`Maximum ${this.config.maxWatchers} UI watchers allowed per session`);
-    }
-
-    // Create watcher state with computed fields
-    const now = Date.now();
-    const watcherState: WatcherState = {
-      name: watcher.name,
-      priority: watcher.priority ?? 0,
-      referenceLocator: watcher.referenceLocator,
-      actionLocator: watcher.actionLocator,
-      duration: watcher.duration,
-      stopOnFound: watcher.stopOnFound ?? false,
-      cooldownMs: watcher.cooldownMs ?? 0,
-      registeredAt: now,
-      expiresAt: now + watcher.duration,
-      status: 'active',
-      triggerCount: 0,
-      lastTriggeredAt: null,
-    };
-
-    this.watchers.set(watcher.name, watcherState);
-    return watcherState;
-  }
-
-  /**
-   * Remove a watcher by name
-   * @param name - Name of the watcher to remove
-   * @returns True if watcher was removed, false if not found
-   */
-  remove(name: string): boolean {
-    return this.watchers.delete(name);
-  }
-
-  /**
-   * Get a watcher by name
-   * @param name - Name of the watcher to retrieve
-   * @returns The watcher state, or undefined if not found
-   */
-  get(name: string): WatcherState | undefined {
-    return this.watchers.get(name);
-  }
-
-  /**
-   * Get all watchers (including expired ones)
-   * @returns Array of all watchers
-   */
-  list(): WatcherState[] {
-    return Array.from(this.watchers.values());
-  }
-
-  /**
-   * Get only active (non-expired) watchers
-   * Automatically removes expired watchers from storage
-   * @returns Array of active watchers
-   */
-  getActiveWatchers(): WatcherState[] {
-    const now = Date.now();
-    const activeWatchers: WatcherState[] = [];
-    const expiredNames: string[] = [];
-
-    // Identify active and expired watchers
-    for (const [name, watcher] of this.watchers.entries()) {
-      if (now >= watcher.expiresAt) {
-        expiredNames.push(name);
-      } else {
-        activeWatchers.push(watcher);
-      }
-    }
-
-    // Remove expired watchers
-    for (const name of expiredNames) {
-      this.watchers.delete(name);
-    }
-
-    return activeWatchers;
-  }
-
-  /**
-   * Get active watchers sorted by priority (descending) and registration time (FIFO)
-   * @returns Array of sorted active watchers
-   */
-  getSortedWatchers(): WatcherState[] {
-    const activeWatchers = this.getActiveWatchers();
-
-    return activeWatchers.sort((a, b) => {
-      // Sort by priority descending (higher priority first)
-      if (a.priority !== b.priority) {
-        return b.priority - a.priority;
-      }
-
-      // If priority is the same, sort by registration time ascending (FIFO)
-      return a.registeredAt - b.registeredAt;
-    });
-  }
-
-  /**
-   * Clear all watchers from the store
-   * @returns Number of watchers removed
-   */
-  clear(): number {
-    const count = this.watchers.size;
-    this.watchers.clear();
-    return count;
-  }
-
-  /**
-   * Mark a watcher as inactive (used for stopOnFound)
-   * @param name - Name of the watcher to mark inactive
-   */
-  markInactive(name: string): void {
-    const watcher = this.watchers.get(name);
-    if (watcher) {
-      watcher.status = 'inactive';
-    }
-  }
-
-  /**
-   * Increment the trigger count for a watcher
-   * @param name - Name of the watcher
-   */
-  incrementTriggerCount(name: string): void {
-    const watcher = this.watchers.get(name);
-    if (watcher) {
-      watcher.triggerCount++;
-      watcher.lastTriggeredAt = Date.now();
-    }
-  }
-
-  /**
-   * Update the last triggered timestamp for a watcher
-   * @param name - Name of the watcher
-   */
-  updateLastTriggered(name: string): void {
-    const watcher = this.watchers.get(name);
-    if (watcher) {
-      watcher.lastTriggeredAt = Date.now();
-    }
-  }
-
-  /**
-   * Disable watcher checking globally
-   */
-  disable(): void {
-    this.enabled = false;
-  }
-
-  /**
-   * Enable watcher checking globally
-   */
-  enable(): void {
-    this.enabled = true;
-  }
-
-  /**
-   * Check if watcher checking is enabled
-   * @returns True if enabled, false otherwise
-   */
-  isEnabled(): boolean {
-    return this.enabled;
-  }
-}