\n\t
![\"Xenon\"](\"assets/xenon-logo.png\"){kind=logo}
\n\t\n\t
\n\tIntelligent Mobile Infrastructure\n\t
\n
\n\t\n Self-healing device orchestration platform for Appium\n
\n\n\n Features •\n Quick Start •\n Capabilities •\n API Docs •\n Documentation •\n Contributing\n
\n\n---\n\n## ✨ What is Xenon?\n\n**Xenon** is an intelligent Appium plugin that transforms your mobile device lab into a **self-healing, autonomous infrastructure**. Named after the noble gas known for its stability and reliability, Xenon brings enterprise-grade device orchestration to your testing pipeline.\n\n### Why Xenon?\n\n| Problem | Xenon Solution |\n|---------|----------------|\n| Tests fail due to device state | **Auto-recovery** - Devices heal themselves |\n| Manual device management | **Smart allocation** - Queue, reserve, prioritize |\n| Debugging is painful | **Interactive control** - Live stream, touch, shell |\n| No visibility into failures | **Rich artifacts** - Video, screenshots, profiling |\n| Infrastructure silos | **Unified dashboard** - One view for all devices |\n\n---\n\n## 🚀 Features\n\n### Device Orchestration\n- ✅ **Automatic device discovery** - Android (USB + emulators), iOS (devices + simulators)\n- ✅ **Smart session allocation** - Queue management with ETA\n- ✅ **WebSocket-First Sync** - Real-time Hub-Node-Dashboard bidirectional sync\n- ✅ **Device reservation** - Manual mode for debugging\n- ✅ **Team-based quotas** - Fair resource sharing\n\n### Interactive Control\n- ✅ **Live streaming** - Real-time device screen in browser\n- ✅ **Touch interaction** - Tap, swipe, scroll remotely\n- ✅ **App management** - Install, uninstall, clear data\n- ✅ **Interactive Shell** - Execute ADB/iOS commands directly\n- ✅ **Device information** - Battery, storage, network status\n\n### 🧠 AI Self-Healing (Flagship)\n- ✅ **5-Tier Healing Orchestration** - From DOM to LLM recovery\n- ✅ **Signature-Based Learning** - Persistent \"Etalon\" signatures for high-confidence recovery\n- ✅ **Multi-Modal Fallback** - Syntactic -> OCR -> Visual AI -> LLM reasoning\n- ✅ **Infrastructure-Free** - Works with existing LokiJS (local) or PostgreSQL (remote)\n\n#### Selector lifecycle (Trust & Truth layer)\n\nHealed selectors flow through a state machine: **Active → Pending → Resolved**, with an optional **Muted** branch.\n\n- **Active** — a hot selector that's healing in flight; surfaces on the Selector Health dashboard, the CI gate, and the webhook digest.\n- **Mark as Fixed** — after rewriting the selector in your test source, click \"Mark as Fixed\" in the dashboard. The row moves to **Pending**.\n- **Pending** — Xenon watches subsequent CI builds. When 3 distinct `build_id`s have run the selector with no heals, it auto-promotes to **Resolved** (`SelectorVerificationJob` runs every 15 minutes).\n- **Resolved** — the rewrite stuck. Excluded from the CI gate and digest. A future heal flips the row back to Active with a regression badge (institutional memory).\n- **Muted** — a selector you've intentionally chosen to ignore (legacy flow, etc.). Hidden from dashboard, CI gate, and digest until unmuted.\n\nThe dashboard shows strategy + value (`Accessibility ID: login-btn`) so suggested rewrites are copy-ready in JS / Java / Python / C# / Ruby — your client language is remembered in `localStorage.xenon.copyLang`.\n\n> **CI gate behavior change:** muted/pending/resolved selectors no longer count toward `/healing/hotspots/violations`. If your CI was passing/failing based on that endpoint, the signal will get quieter after this release — selectors actively being managed are no longer flagged. Pass `?status=all` to opt back into the old behavior.\n\n### Recording & Artifacts\n- ✅ **Video recording** - Full session capture\n- ✅ **Screenshot capture** - On-demand and per-command\n- ✅ **Network interceptor** - Live HTTP/HTTPS capture, mocking, and HAR export ([docs](https://xenon-docs.vercel.app/docs/network-interceptor))\n- ✅ **Distributed Tracing** - OpenTelemetry spans for exact command latency\n- ✅ **Performance profiling** - CPU, memory, FPS metrics\n- ✅ **Log aggregation** - Appium, device, app logs\n- ✅ **OpenTelemetry Integration** - Standardized distributed tracing for all sessions\n\n### Intelligence (Roadmap)\n- 🔲 **Flaky test detection** - Auto-identify unstable tests\n- 🔲 **Error categorization** - Crash vs timeout vs element not found\n- 🔲 **Predictive health** - USB/battery failure prediction\n\n---\n\n## ⚡ Quick Start\n\n### Installation\n\n```bash\n# Install Xenon plugin\nappium plugin install --source=npm @xenon-device-management/xenon\n\n# Or install from source\ngit clone https://github.com/xenon-platform/xenon.git\ncd xenon\nnpm install\nnpm run build:all\nappium plugin install --source=local .\n```\n\n### Running\n\n```bash\n# Start Appium with Xenon\nappium server --use-plugins=xenon \\\n --plugin-xenon-platform=both \\\n --plugin-xenon-enable-dashboard\n```\n\n## 🔧 Configuration\n\nXenon supports configuration via CLI arguments or a configuration file (YAML/JSON). We recommend using a configuration file for production deployments.\n\n### Using Configuration File (Recommended)\n\nCreate a `xenon-config.yaml` file:\n```yaml\nserver:\n usePlugins: [\"xenon\"]\n plugin:\n xenon:\n platform: both\n maxSessions: 8\n enableDashboard: true\n enableSelfHealing: true\n```\n\nRun Appium with the config:\n```bash\nappium server --config xenon-config.yaml\n```\n\n### Runtime Configuration ⚡️\n\nYou can update configuration options at runtime without restarting the server using the API:\n\n```bash\n# Get current config\nGET /xenon/api/config\n\n# Update config (e.g. change max sessions)\nPUT /xenon/api/config\n{ \"maxSessions\": 10 }\n```\n\n> **Note:** Some changes (like `platform` or `hub` URL) require a server restart to take full effect. The API response will indicate if a restart is required.\n\n### Build & Session Retention 🧹\n\nXenon includes an enterprise-ready cleanup job that automatically purges older builds, sessions, and associated assets (videos/screenshots) to manage disk space.\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `buildCleanupDays` | Retention period in days | `30` |\n| `buildCleanupMaxCount` | Maximum number of builds to keep | `100` |\n| `buildCleanupSchedule` | Cron schedule for the cleanup job | `\"0 0 * * *\"` |\n| `deleteBuildAssets` | Delete video recordings and screenshots from disk | `true` |\n\n**Example (YAML):**\n```yaml\nplugin:\n xenon:\n buildCleanupDays: 14\n buildCleanupMaxCount: 50\n buildCleanupSchedule: \"0 0 * * *\"\n deleteBuildAssets: true\n```\n\nDetailed explanation of how the retention logic works can be found in the **[Data Retention & Maintenance Guide](docs/retention.md)**.\n\nSee [docs/server-args.md](docs/server-args.md) for all available options.\n\n---\n\n## 📋 Capabilities\n\nXenon uses the `xe:` prefix for its custom capabilities. You can also use `xenon:` as an alternative.\n\n### `xe:options`: credentials, leases and nested options\n\n`xe:options` is Xenon's capability namespace. It holds the session's credentials (`accessKey` + `token`, or `sessionToken`), a lease (`leaseId` + `leaseToken`, which the lease-create response's `appiumCapabilities` already carry), and options such as `healingTiers`. `xenon:options` is still accepted as an alias; when both are sent, `xe:options` wins field by field. `df:options` is not read. See [Teams](#teams-device-access-control) for an example.\n\n### Session & Build Tracking\n\n| Capability | Description | Example |\n|------------|-------------|---------|\n| `xe:build` | Build name for grouping sessions | `\"xe:build\": \"Release-v2.0\"` |\n| `xe:name` | Session name for identification | `\"xe:name\": \"Login Test Suite\"` |\n\n### Recording & Screenshots\n\n| Capability | Description | Default |\n|------------|-------------|---------|\n| `xe:record_video` | Enable video recording | `true` |\n| `xe:screenshot_on_failure` | Capture screenshot on test failure | `true` |\n| `xe:screenshot_on_every_command` | Capture screenshot after each command | `false` |\n| `xe:save_device_logs` | Save device logs (logcat/syslog) | `false` |\n\n### Device Filtering\n\n| Capability | Description | Example |\n|------------|-------------|---------|\n| `appium:udids` | Comma-separated list of allowed UDIDs | `\"device1,device2\"` |\n| `appium:minSDK` | Minimum OS version | `\"15\"` |\n| `appium:maxSDK` | Maximum OS version | `\"17\"` |\n| `appium:iPhoneOnly` | Use only iPhone simulators | `true` |\n| `appium:iPadOnly` | Use only iPad simulators | `true` |\n| `appium:filterByHost` | Filter by node IP address | `\"192.168.0.100\"` |\n\n### Timeouts\n\n| Capability | Description | Default |\n|------------|-------------|---------|\n| `appium:deviceAvailabilityTimeout` | Wait time for device availability (ms) | `180000` |\n| `appium:deviceRetryInterval` | Polling interval for device check (ms) | `10000` |\n\n### Example Configuration\n\n```javascript\nconst capabilities = {\n platformName: 'iOS',\n 'appium:automationName': 'XCUITest',\n 'appium:app': '/path/to/app.ipa',\n \n // Xenon capabilities\n 'xe:build': 'Sprint-42',\n 'xe:name': 'Login Flow Test',\n 'xe:record_video': true,\n 'xe:screenshot_on_failure': true,\n 'xe:save_device_logs': true,\n \n // Device filtering\n 'appium:minSDK': '16',\n 'appium:iPhoneOnly': true\n};\n```\n\n### Custom Execute Script Commands\n\nXenon supports extended control and reporting via the `xenon:` execute script namespace. These commands allow you to interact with the Xenon dashboard and session management directly from your test code.\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `xenon: setSessionStatus` | Mark session as passed/failed in dashboard | `{\"status\": \"passed\", \"reason\": \"All steps OK\"}` |\n| `xenon: setSessionName` | Update session name at runtime | `{\"name\": \"Step 2: Payment Verification\"}` |\n| `xenon: captureEvidence` | Trigger manual screenshot with custom label | `{\"reason\": \"Checkpoint reached\", \"label\": \"success\"}` |\n| `xenon: addTag` | Add searchable tags to the session | `{\"tag\": \"regression\"}` |\n| `xenon: debug` | Send custom debug logs to Xenon dashboard | `{\"message\": \"API Response: 200 OK\"}` |\n\nFull reference for these commands is in the Swagger UI at `/xenon/api-docs`.\n\n---\n\n## 🧠 AI Self-Healing\n\nXenon features a best-in-class, 5-tier self-healing system that ensures your tests never fail due to minor UI changes. It automatically intercepts `NoSuchElementError` and attempts to recover the locator using increasingly advanced methods.\n\n### 🛡️ The 5-Tier Strategy\n\n| Tier | Provider | Mechanism | Stability |\n|:---|:---|:---|:---|\n| **1** | **Native** | Standard Appium `findElement` | Baseline |\n| **2** | **Fuzzy XML**| **Weighted Signature Matching** (Dice Coefficient) | **85%+** |\n| **3** | **OCR** | Local Text Recognition (Tesseract.js) | High |\n| **4** | **Visual AI**| AI-powered coordinate discovery | High |\n| **5** | **LLM** | Deep Reasoning (Gemini/OpenAI) | Absolute |\n\n### ⚡ Signature-Based Learning (Etalon)\n\nXenon \"learns\" during every successful run. When an element is found, it captures a persistent **Element Signature (Etalon)**. \n- **Zero Configuration**: Learning is fully automatic and backgrounded.\n- **Persistent Memory**: Signatures are stored in your database (LokiJS or PostgreSQL).\n- **Extreme Precision**: Even if `id`, `text`, or `class` changes, Xenon uses anchor attributes (`content-desc`, `resource-id`) from its memory to find the match with industrial-grade confidence.\n\n### 🎛️ Control & Transparency\n\nXenon provides full visibility and control over its self-healing system:\n\n- **Global Toggle**: Enable or disable healing via CLI:\n ```bash\n appium server --use-plugins=xenon --plugin-xenon-enable-self-healing=true\n ```\n- **Live Configuration**: Toggle self-healing directly from the **Xenon Dashboard Settings** at runtime without restarting the server.\n- **Audit Logs**: Every healing event is recorded in the session command history. You can see:\n - **Original Selector**: The locator that failed.\n - **Recovered Selector**: The replacement locator found by Xenon.\n - **Confidence Score**: The mathematical match probability (0-1.0).\n - **Healing Tier**: Which tier (Fuzzy XML, OCR, etc.) performed the recovery.\n\n---\n\n## 📖 API Documentation\n\nXenon provides a comprehensive REST API for device management, session control, and more.\n\n### Swagger UI\n\nAccess interactive API documentation at:\n```\nhttp://localhost:4723/xenon/api-docs\n```\n\n### OpenAPI Spec\n\nGet the raw OpenAPI specification:\n```\nhttp://localhost:4723/xenon/api-docs.json\n```\n\n### API Categories\n\n| Category | Base Path | Description |\n|----------|-----------|-------------|\n| **Devices** | `/xenon/api/devices` | Device discovery and management |\n| **Sessions** | `/xenon/api/session` | Session management and logs |\n| **Builds** | `/xenon/api/build` | Build and test execution tracking |\n| **Control** | `/xenon/api/control` | Interactive device control |\n| **Reservations** | `/xenon/api/reservation` | Device reservation for exclusive use |\n| **Applications** | `/xenon/api/apps` | App repository and installation |\n| **Webhooks** | `/xenon/api/webhook` | Notification webhook configuration |\n\n### Key Endpoints\n\n#### Devices\n```bash\n# Get all devices\nGET /xenon/api/devices\n\n# Get device by platform\nGET /xenon/api/device/{platform}\n\n# Block/Unblock device\nPOST /xenon/api/device/{udid}/block\nPOST /xenon/api/device/{udid}/unblock\n```\n\n#### Control API\n```bash\n# Take screenshot\nGET /xenon/api/control/{udid}/screenshot\n\n# Tap at coordinates\nPOST /xenon/api/control/{udid}/tap\n{ \"x\": 100, \"y\": 200 }\n\n# Swipe gesture\nPOST /xenon/api/control/{udid}/swipe\n{ \"x\": 100, \"y\": 500, \"endX\": 100, \"endY\": 100, \"duration\": 1000 }\n\n# Type text\nPOST /xenon/api/control/{udid}/text\n{ \"text\": \"Hello World\" }\n\n# Execute shell command (Android)\nPOST /xenon/api/control/{udid}/shell\n{ \"command\": \"pm list packages\" }\n\n# Live stream\nGET /xenon/api/control/{udid}/stream\n```\n\n#### Reservations\n```bash\n# Reserve a device\nPOST /xenon/api/reservation\n{ \"udid\": \"...\", \"host\": \"...\", \"reservedBy\": \"John\", \"duration\": \"2h\" }\n\n# Release reservation\nDELETE /xenon/api/reservation/{udid}/{host}\n\n# Extend reservation\nPOST /xenon/api/reservation/{udid}/{host}/extend\n{ \"duration\": \"1h\" }\n```\n\n---\n\n## 🎨 Dashboard\n\nAccess the dashboard at `http://localhost:4723/xenon/`\n\n\n ![\"Xenon](\"assets/dashboard.png\")
\n
\n Xenon - Stable. Reliable. Intelligent.\n
\n Named after Element 54 - the noble gas known for stability\n