appium-uiwatchers-plugin 1.0.0

package/.c8rc.json

@@ -0,0 +1,12 @@
+{
+  "all": true,
+  "include": ["lib/**/*.js"],
+  "exclude": ["test/**", "**/*.spec.js", "**/*.test.js", "**/*.e2e.spec.cjs", "lib/types.js"],
+  "reporter": ["text", "html", "lcov"],
+  "report-dir": "./coverage",
+  "check-coverage": true,
+  "lines": 80,
+  "statements": 80,
+  "functions": 80,
+  "branches": 80
+}

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,28 @@
+name: Publish to NPM
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install latest npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public

package/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx lint-staged

package/.lintstagedrc.json

@@ -0,0 +1,4 @@
+{
+  "*.{ts,js}": ["eslint --fix", "prettier --write"],
+  "*.{json,md}": ["prettier --write"]
+}

package/.mocharc.json

@@ -0,0 +1,10 @@
+{
+  "require": ["@appium/support/build/lib/env"],
+  "timeout": 20000,
+  "slow": 10000,
+  "reporter": "spec",
+  "color": true,
+  "recursive": true,
+  "exit": true,
+  "spec": ["test/unit/**/*.spec.js", "test/integration/**/*.spec.js", "test/e2e/**/*.e2e.spec.cjs"]
+}

package/.prettierignore

@@ -0,0 +1,6 @@
+node_modules
+lib
+coverage
+*.log
+.nyc_output
+package-lock.json

package/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "always",
+  "bracketSpacing": true,
+  "endOfLine": "lf"
+}

package/README.md

@@ -0,0 +1,376 @@
+# Appium UI Watchers Plugin
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Appium 3.x](https://img.shields.io/badge/Appium-3.x-purple.svg)](https://appium.io/)
+[![Node.js 18+](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
+[![npm version](https://img.shields.io/npm/v/appium-uiwatchers-plugin.svg)](https://www.npmjs.com/package/appium-uiwatchers-plugin)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/rajvinodh/appium-uiwatchers-plugin/ci.yml?branch=main)](https://github.com/rajvinodh/appium-uiwatchers-plugin/actions)
+
+## Introduction
+
+Mobile apps often display unexpected UI elements — cookie consent dialogs, permission prompts, rating popups—that break test automation. Traditional approaches require explicit waits or try-catch blocks scattered throughout test code.
+
+This plugin provides a centralized, declarative way to handle these interruptions automatically.
+
+## Features
+
+- **Zero Wait Overhead** — No waiting for UI elements that may never appear
+- **Centralized Management** — Register watchers once, apply across entire session
+- **Priority-Based Execution** — Higher priority watchers are checked first
+- **Cooldown Support** — Wait for stable UI after dismissing an element
+- **Auto-Expiry** — Watchers automatically expire after specified duration
+- **One-Shot or Continuous** — Stop after first trigger or keep watching
+- **Transparent Interception** — Handles on findElement, findElements, and element actions automatically
+- **Session-Scoped** — Each session maintains its own independent set of watchers
+
+## Installation
+
+### From npm (coming soon)
+
+```bash
+appium plugin install appium-uiwatchers-plugin
+```
+
+### From local source
+
+```bash
+appium plugin install --source=local /path/to/appium-uiwatchers-plugin
+```
+
+### Verify installation
+
+```bash
+appium plugin list
+```
+
+You should see `uiwatchers` in the installed plugins list.
+
+### Activate the plugin
+
+```bash
+appium --use-plugins=uiwatchers
+```
+
+## Quick Start
+
+> **Note:** Ensure Appium server is started with `--use-plugins=uiwatchers`
+
+**JavaScript**
+
+```javascript
+// Register a watcher for cookie consent
+await driver.execute('mobile: registerUIWatcher', {
+  name: 'cookie-consent',
+  referenceLocator: { using: 'id', value: 'com.app:id/cookie_banner' },
+  actionLocator: { using: 'id', value: 'com.app:id/accept_button' },
+});
+
+// Run tests - watchers trigger automatically on findElement/findElements
+await driver.findElement('id', 'com.app:id/login_button');
+```
+
+**Java**
+
+```java
+// Register a watcher for cookie consent
+Map<String, Object> watcherParams = new HashMap<>();
+watcherParams.put("name", "cookie-consent");
+watcherParams.put("referenceLocator", Map.of("using", "id", "value", "com.app:id/cookie_banner"));
+watcherParams.put("actionLocator", Map.of("using", "id", "value", "com.app:id/accept_button"));
+
+driver.executeScript("mobile: registerUIWatcher", watcherParams);
+
+// Run tests - watchers trigger automatically on findElement/findElements
+driver.findElement(By.id("com.app:id/login_button"));
+```
+
+## API Reference
+
+### mobile: registerUIWatcher
+
+Registers a new UI watcher for automatic element handling.
+
+**Parameters**
+
+| Parameter        | Type    | Required | Default | Description                              |
+| ---------------- | ------- | -------- | ------- | ---------------------------------------- |
+| name             | string  | Yes      | -       | Unique watcher identifier                |
+| referenceLocator | object  | Yes      | -       | Element to detect (trigger condition)    |
+| actionLocator    | object  | Yes      | -       | Element to click when triggered          |
+| duration         | number  | Yes      | -       | Auto-expiry time in ms (max: 60000)      |
+| priority         | number  | No       | 0       | Execution order (higher = first)         |
+| stopOnFound      | boolean | No       | false   | Deactivate after first trigger           |
+| cooldownMs       | number  | No       | 0       | Wait time after action before re-trigger |
+
+**Locator Object**
+
+| Property | Type   | Description                                       |
+| -------- | ------ | ------------------------------------------------- |
+| using    | string | Strategy: `id`, `xpath`, `accessibility id`, etc. |
+| value    | string | Locator value                                     |
+
+**Example**
+
+```json
+{
+  "name": "cookie-consent",
+  "priority": 10,
+  "referenceLocator": {
+    "using": "id",
+    "value": "com.app:id/cookie_banner"
+  },
+  "actionLocator": {
+    "using": "id",
+    "value": "com.app:id/accept_button"
+  },
+  "duration": 60000,
+  "stopOnFound": false,
+  "cooldownMs": 5000
+}
+```
+
+**Response**
+
+```json
+{
+  "success": true,
+  "watcher": {
+    "name": "cookie-consent",
+    "priority": 10,
+    "registeredAt": 1704067200000,
+    "expiresAt": 1704067260000,
+    "status": "active"
+  }
+}
+```
+
+### mobile: unregisterUIWatcher
+
+Removes a registered watcher by name.
+
+**Parameters**
+
+| Parameter | Type   | Required | Description                   |
+| --------- | ------ | -------- | ----------------------------- |
+| name      | string | Yes      | Name of the watcher to remove |
+
+**Example**
+
+```json
+{
+  "name": "cookie-consent"
+}
+```
+
+**Response**
+
+```json
+{
+  "success": true,
+  "removed": "cookie-consent"
+}
+```
+
+### mobile: listUIWatchers
+
+Returns all registered watchers with their current state.
+
+**Parameters**
+
+None.
+
+**Response**
+
+```json
+{
+  "success": true,
+  "watchers": [
+    {
+      "name": "cookie-consent",
+      "priority": 10,
+      "referenceLocator": { "using": "id", "value": "com.app:id/cookie_banner" },
+      "actionLocator": { "using": "id", "value": "com.app:id/accept_button" },
+      "duration": 60000,
+      "stopOnFound": false,
+      "cooldownMs": 5000,
+      "registeredAt": 1704067200000,
+      "expiresAt": 1704067260000,
+      "status": "active",
+      "triggerCount": 2,
+      "lastTriggeredAt": 1704067230000
+    }
+  ],
+  "totalCount": 1
+}
+```
+
+### mobile: clearAllUIWatchers
+
+Removes all registered watchers for the current session.
+
+**Parameters**
+
+None.
+
+**Response**
+
+```json
+{
+  "success": true,
+  "removedCount": 3
+}
+```
+
+### mobile: enableUIWatchers
+
+Enables watcher checking (enabled by default).
+
+**Parameters**
+
+None.
+
+**Response**
+
+```json
+{
+  "success": true,
+  "message": "UI Watchers enabled"
+}
+```
+
+### mobile: disableUIWatchers
+
+Temporarily disables watcher checking without removing watchers.
+
+**Parameters**
+
+None.
+
+**Response**
+
+```json
+{
+  "success": true,
+  "message": "UI Watchers disabled"
+}
+```
+
+## Configuration
+
+Plugin behavior can be customized via CLI options when starting Appium server.
+
+| Option                                | Type    | Range       | Default | Description                       |
+| ------------------------------------- | ------- | ----------- | ------- | --------------------------------- |
+| --plugin-uiwatchers-max-watchers      | integer | 1-20        | 5       | Maximum watchers per session      |
+| --plugin-uiwatchers-max-duration-ms   | integer | 1000-600000 | 60000   | Maximum watcher duration in ms    |
+| --plugin-uiwatchers-max-cache-entries | integer | 10-200      | 50      | Maximum cached element references |
+| --plugin-uiwatchers-element-ttl-ms    | integer | 5000-300000 | 60000   | Cache entry TTL in ms             |
+
+**Example**
+
+```bash
+appium --use-plugins=uiwatchers \
+  --plugin-uiwatchers-max-watchers=10 \
+  --plugin-uiwatchers-max-duration-ms=120000 \
+  --plugin-uiwatchers-max-cache-entries=100 \
+  --plugin-uiwatchers-element-ttl-ms=30000
+```
+
+## How It Works
+
+### Watcher Checking Flow
+
+```mermaid
+flowchart TD
+    A[findElement / findElements] --> B{Command Success?}
+    B -->|Yes| C[Cache element reference]
+    C --> D[Return result]
+    B -->|No / Empty| E[Check watchers by priority]
+    E --> F{Reference element found?}
+    F -->|No| G{More watchers?}
+    G -->|Yes| E
+    F -->|Yes| H[Click action element]
+    H --> I[Apply cooldown]
+    I --> G
+    G -->|No| J[Retry original command]
+    J --> D
+```
+
+### Stale Element Recovery Flow
+
+```mermaid
+flowchart TD
+    A[Element action: click, getText, etc.] --> B{StaleElementReferenceException?}
+    B -->|No| C[Return result]
+    B -->|Yes| D[Check watchers]
+    D --> E{Watcher triggered?}
+    E -->|No| F[Throw original exception]
+    E -->|Yes| G[Lookup cached locator]
+    G --> H{Found in cache?}
+    H -->|No| F
+    H -->|Yes| I[Re-find element using locator]
+    I --> J[Map old ID → new ID]
+    J --> K[Retry action with new element]
+    K --> C
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- Appium 3.x
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/rajvinodh/appium-uiwatchers-plugin.git
+cd appium-uiwatchers-plugin
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+```
+
+### Scripts
+
+| Script                  | Description                        |
+| ----------------------- | ---------------------------------- |
+| `npm run build`         | Compile TypeScript to JavaScript   |
+| `npm run test`          | Run all tests (unit + integration) |
+| `npm run test:unit`     | Run unit tests only                |
+| `npm run test:coverage` | Run tests with coverage report     |
+| `npm run lint`          | Run ESLint and Prettier checks     |
+| `npm run lint:fix`      | Auto-fix linting issues            |
+
+### Project Structure
+
+```
+├── src/                  # TypeScript source code
+│   ├── plugin.ts         # Main plugin class
+│   ├── watcher-store.ts  # Watcher state management
+│   ├── watcher-checker.ts# Watcher execution logic
+│   ├── element-cache.ts  # Element reference caching
+│   ├── commands/         # Command implementations
+│   ├── config.ts         # Configuration defaults
+│   ├── types.ts          # Type definitions
+│   └── utils.ts          # Utility functions
+├── test/
+│   ├── unit/             # Unit tests
+│   └── integration/      # Integration tests
+└── lib/                  # Compiled output
+```
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes
+4. Run tests (`npm run test`)
+5. Run linting (`npm run lint`)
+6. Commit your changes
+7. Push to your branch
+8. Open a Pull Request

package/eslint.config.js

@@ -0,0 +1,65 @@
+import js from '@eslint/js';
+import tseslint from '@typescript-eslint/eslint-plugin';
+import tsparser from '@typescript-eslint/parser';
+import prettier from 'eslint-config-prettier';
+
+export default [
+  js.configs.recommended,
+  {
+    files: ['src/**/*.ts', 'test/**/*.js'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        ecmaVersion: 2020,
+        sourceType: 'module',
+      },
+      globals: {
+        console: 'readonly',
+        process: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        Buffer: 'readonly',
+        module: 'readonly',
+        require: 'readonly',
+        exports: 'readonly',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+        },
+      ],
+      '@typescript-eslint/explicit-module-boundary-types': 'off',
+      '@typescript-eslint/no-explicit-any': 'warn',
+      'no-console': 'warn',
+      'prefer-const': 'error',
+      'no-var': 'error',
+    },
+  },
+  {
+    files: ['test/**/*.js', 'test/**/*.cjs'],
+    languageOptions: {
+      globals: {
+        describe: 'readonly',
+        it: 'readonly',
+        before: 'readonly',
+        after: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        setTimeout: 'readonly',
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-unused-expressions': 'off',
+      'no-undef': 'off',
+    },
+  },
+  prettier,
+];

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "appium-uiwatchers-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./lib/plugin.js",
+  "types": "./lib/plugin.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "clean": "rm -rf lib coverage",
+    "prepublishOnly": "npm run build",
+    "test": "npm run test:unit && npm run test:integration",
+    "test:unit": "mocha --config .mocharc.json \"test/unit/**/*.spec.js\"",
+    "test:integration": "mocha --config .mocharc.json \"test/integration/**/*.spec.js\"",
+    "test:e2e": "mocha --config .mocharc.json \"test/e2e/**/*.e2e.spec.cjs\"",
+    "test:coverage": "c8 npm run test",
+    "test:watch": "mocha --config .mocharc.json --watch",
+    "lint": "eslint src test && prettier --check .",
+    "lint:fix": "eslint src test --fix && prettier --write .",
+    "format": "prettier --write .",
+    "prepare": "husky",
+    "install:local": "npm run build && appium plugin install --source=local ."
+  },
+  "keywords": [
+    "appium",
+    "appium-plugin",
+    "automation",
+    "testing",
+    "mobile",
+    "ui-watchers",
+    "popup-handler"
+  ],
+  "author": "Vinodh Raj R",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rajvinodh/uiwatchers.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rajvinodh/uiwatchers/issues"
+  },
+  "homepage": "https://github.com/rajvinodh/uiwatchers#readme",
+  "description": "Appium plugin to automatically handle unexpected UI elements (popups, banners, dialogs) during test execution",
+  "peerDependencies": {
+    "appium": "^3.1.2"
+  },
+  "appium": {
+    "pluginName": "uiwatchers",
+    "mainClass": "UIWatchersPlugin",
+    "schema": {
+      "$schema": "http://json-schema.org/draft-07/schema",
+      "type": "object",
+      "properties": {
+        "max-watchers": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 20,
+          "default": 5,
+          "description": "Maximum number of UI watchers allowed per session"
+        },
+        "max-duration-ms": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 600000,
+          "default": 60000,
+          "description": "Maximum duration for each UI watcher in milliseconds"
+        },
+        "max-cache-entries": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 200,
+          "default": 50,
+          "description": "Maximum element references to cache for stale element recovery"
+        },
+        "element-ttl-ms": {
+          "type": "integer",
+          "minimum": 5000,
+          "maximum": 300000,
+          "default": 60000,
+          "description": "TTL for cached element references in milliseconds"
+        }
+      }
+    }
+  },
+  "dependencies": {
+    "@appium/base-plugin": "^3.0.5",
+    "@appium/support": "^7.0.4"
+  },
+  "devDependencies": {
+    "@appium/fake-driver": "^6.0.1",
+    "@appium/plugin-test-support": "^1.0.4",
+    "@appium/test-support": "^4.0.4",
+    "@types/chai": "^5.2.3",
+    "@types/chai-as-promised": "^8.0.2",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^25.0.3",
+    "@types/sinon": "^21.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.51.0",
+    "@typescript-eslint/parser": "^8.51.0",
+    "appium-inspector-plugin": "^2025.11.1",
+    "c8": "^10.1.3",
+    "chai": "^6.2.2",
+    "chai-as-promised": "^8.0.2",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "mocha": "^11.7.5",
+    "prettier": "^3.7.4",
+    "sinon": "^21.0.1",
+    "typescript": "^5.9.3",
+    "webdriverio": "^9.22.0"
+  }
+}

package/src/commands/clear.ts

@@ -0,0 +1,28 @@
+/**
+ * clearAllUIWatchers command implementation
+ */
+
+import { logger } from '@appium/support';
+import type { WatcherStore } from '../watcher-store.js';
+import type { ClearAllWatchersResult } from '../types.js';
+
+const log = logger.getLogger('AppiumUIWatchers');
+
+/**
+ * Clear all UI watchers from the session
+ * @param store - Watcher store instance
+ * @returns Clear result with count of removed watchers
+ */
+export async function clearAllUIWatchers(store: WatcherStore): Promise<ClearAllWatchersResult> {
+  // Get count before clearing
+  const count = store.clear();
+
+  // Log successful clear
+  log.info(`[UIWatchers] All UI watchers cleared (removed ${count} watchers)`);
+
+  // Return success response
+  return {
+    success: true,
+    removedCount: count,
+  };
+}

package/src/commands/list.ts

@@ -0,0 +1,23 @@
+/**
+ * listUIWatchers command implementation
+ */
+
+import type { WatcherStore } from '../watcher-store.js';
+import type { ListWatchersResult } from '../types.js';
+
+/**
+ * List all active UI watchers with their state
+ * @param store - Watcher store instance
+ * @returns List of all active watchers
+ */
+export async function listUIWatchers(store: WatcherStore): Promise<ListWatchersResult> {
+  // Get all active watchers (this automatically filters out expired ones)
+  const activeWatchers = store.getActiveWatchers();
+
+  // Return success response
+  return {
+    success: true,
+    watchers: activeWatchers,
+    totalCount: activeWatchers.length,
+  };
+}