testrelic-appium 0.1.0__tar.gz

testrelic_appium-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Build artifacts (also covered by repo-root .gitignore but kept here for clarity)
+dist/
+build/
+*.egg-info/
+
+# Local virtualenv used during development
+.venv/
+
+# Caches
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Reporter output produced by the package's own pytest runs
+test-results/
+
+# Local cloud queue
+.testrelic/queue/
+.testrelic/cache/

testrelic_appium-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to `testrelic-appium` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release. Python port of [`@testrelic/appium-analytics`](https://www.npmjs.com/package/@testrelic/appium-analytics).
+- `pytest11` plugin that auto-loads on install and captures Appium WebDriver sessions with zero user configuration.
+- Auto-detection and per-instance wrapping of `appium.webdriver.webdriver.WebDriver` instances; opt-out via `--testrelic-no-autowrap`.
+- Command timeline capture with category inference (find / interaction / gesture / navigation / lifecycle / context / device / keyboard / alert / screenshot / other), timing, selector extraction, and sensitive-argument redaction.
+- Device capability snapshot (platform, version, automation name, device name, app path, browser name, UDID).
+- Device log capture: Android `logcat`, iOS `syslog` / `crashlog` (polling via `driver.get_log`).
+- Console log capture: WebView / browser console via BiDi `log.entryAdded` with polling fallback (`browser`, `safariConsole`).
+- Network capture: Chrome DevTools Protocol performance logs (Android), `safariNetwork` (iOS), plus optional `mitmproxy` fallback via `[network-proxy]` extra.
+- Screenshots (off / on / on-failure / on-every-step) and 3-tier video recording (Appium `start_recording_screen` → `mobile: startScreenRecording` → `adb screenrecord`).
+- Assertion tracking via `assert_that(...)` context manager and opportunistic `pytest_assertion_pass` hook.
+- pytest-xdist parallel-worker coordination: single cloud run with per-worker manifest finalization in the master process.
+- Cloud upload via the shared cloud client (batch / realtime / both / none), with offline queue at `.testrelic/queue/`, 7-day expiry sweep, and OAuth token refresh.
+- Presigned-URL artifact upload (screenshots, videos, device logs as gzipped JSONL).
+- Self-contained interactive HTML report with embedded JSON payload.
+- `testrelic-appium` CLI: `version`, `merge`, `serve`, `drain`, `cleanup-queue`.
+- CI metadata auto-detection (GitHub Actions, GitLab CI, Jenkins, CircleCI, Bitbucket Pipelines).
+- Sensitive-data redaction shared with `testrelic-playwright` plus Appium-specific command-argument redaction (`elementSendKeys`, `setValueImmediate`, `replaceValue`).

testrelic_appium-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TestRelic AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

testrelic_appium-0.1.0/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: testrelic-appium
+Version: 0.1.0
+Summary: Appium/pytest test analytics reporter — command timeline, device log capture (logcat/syslog), network interception, screenshot/video artifacts, and interactive HTML reports for Android and iOS.
+Project-URL: Homepage, https://testrelic.ai
+Project-URL: Documentation, https://docs.testrelic.ai/appium
+Project-URL: Repository, https://github.com/testrelic-ai/testrelic-python-sdk
+Project-URL: Bug Tracker, https://github.com/testrelic-ai/testrelic-python-sdk/issues
+Author-email: TestRelic AI <hello@testrelic.ai>
+License: MIT
+License-File: LICENSE
+Keywords: analytics,android,appium,ci,device-testing,e2e-testing,html-report,ios,mobile-testing,network,pytest,reporter,test,test-automation,test-results,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Requires-Dist: appium-python-client<6.0,>=4.0
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic<3.0,>=2.6
+Requires-Dist: pytest>=7.0
+Requires-Dist: selenium<5.0,>=4.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer<1.0,>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Provides-Extra: network-proxy
+Requires-Dist: mitmproxy>=10.0; extra == 'network-proxy'
+Description-Content-Type: text/markdown
+
+# testrelic-appium
+
+Appium test analytics reporter for **pytest** — captures command timelines,
+device logs (Android `logcat` / iOS `syslog`), console logs, network requests,
+screenshots, and video, then generates a self-contained interactive HTML
+report. Python port of
+[`@testrelic/appium-analytics`](https://www.npmjs.com/package/@testrelic/appium-analytics).
+
+## What it does
+
+When you run your Appium tests with `pytest` and the `testrelic-appium` plugin
+installed, you get JSON + HTML reports that capture:
+
+- **Command timeline** — every Appium / WebDriver command with timing,
+  category (`find`, `interaction`, `gesture`, `navigation`, `lifecycle`,
+  `context`, `device`, `keyboard`, `alert`, `screenshot`, `other`), selector,
+  arguments (sensitive ones redacted), and result.
+- **Device logs** — Android `logcat`, iOS `syslog` and `crashlog`, polled in
+  the background and sliced per test.
+- **Console logs** — WebView / browser console output via WebDriver BiDi
+  (`log.entryAdded`) when supported, with polling fallback (`browser`,
+  `safariConsole`).
+- **Network capture** — Chrome DevTools Protocol performance logs (Android),
+  `safariNetwork` (iOS), with optional `mitmproxy` fallback for emulators
+  without CDP.
+- **Screenshots & video** — configurable: off, on every test, on failure, or
+  on every step. Video uses Appium recording commands first, falling back to
+  `adb screenrecord`.
+- **Assertions** — `assert_that(...)` context manager records named assertion
+  steps; bare `assert` statements are picked up by `pytest_assertion_pass`.
+- **CI metadata** — auto-detect GitHub Actions, GitLab CI, Jenkins, CircleCI,
+  Bitbucket Pipelines.
+- **Sensitive-data redaction** — AWS access keys, Bearer tokens, PEM private
+  keys, embedded URL credentials, plus Appium-specific command-argument
+  redaction (`elementSendKeys`, `setValueImmediate`, `replaceValue`).
+- **HTML report** — self-contained, opens in any browser.
+
+## System requirements
+
+The package itself has no platform requirements beyond Python, but to test
+mobile apps you'll need the standard Appium tooling on your machine. None of
+these are pip dependencies — they are subprocess dependencies the SDK invokes
+when needed.
+
+| Tool | Required for |
+|---|---|
+| Appium server (`npm install -g appium`) | All tests |
+| `appium driver install uiautomator2` | Android |
+| `appium driver install xcuitest` | iOS (macOS only) |
+| `adb` on `PATH` | Android device-log capture, video recording fallback, proxy network capture |
+| `xcrun simctl` | iOS simulators |
+
+> **iOS testing requires macOS 13+ with Xcode 15+.** iOS tests cannot run on Windows or Linux.
+
+## Quick start
+
+### 1. Install
+
+```bash
+pip install testrelic-appium
+```
+
+The plugin activates automatically because `testrelic-appium` registers a
+`pytest11` entry point. No `conftest.py` plumbing required.
+
+For the optional HTTPS network-capture proxy:
+
+```bash
+pip install "testrelic-appium[network-proxy]"
+```
+
+### 2. Write a test
+
+Use any Appium driver instantiation pattern. The plugin walks
+`item.funcargs` after each fixture resolves and per-instance wraps any
+`appium.webdriver.webdriver.WebDriver` it finds — Selenium-only tests are
+never touched.
+
+```python
+# tests/test_login.py
+import pytest
+from appium import webdriver
+from appium.options.android import UiAutomator2Options
+
+
+@pytest.fixture
+def driver():
+    options = UiAutomator2Options()
+    options.platform_name = "Android"
+    options.device_name = "emulator-5554"
+    options.app = "/path/to/MyApp.apk"
+    d = webdriver.Remote("http://127.0.0.1:4723", options=options)
+    yield d
+    d.quit()
+
+
+def test_login_succeeds(driver):
+    driver.find_element("accessibility id", "username").send_keys("alice")
+    driver.find_element("accessibility id", "password").send_keys("hunter2")
+    driver.find_element("accessibility id", "submit").click()
+    assert driver.find_element("accessibility id", "welcome").is_displayed()
+```
+
+### 3. Run
+
+```bash
+pytest
+```
+
+Outputs land in:
+
+```
+test-results/
+├── testrelic-timeline.json
+└── testrelic-timeline.html
+```
+
+## Configuration
+
+Reporter options can be supplied three ways (highest priority first):
+
+1. **Environment variables** (`TESTRELIC_API_KEY`, `TESTRELIC_CLOUD_ENDPOINT`,
+   `TESTRELIC_UPLOAD_STRATEGY`, `TESTRELIC_CLOUD_TIMEOUT`,
+   `TESTRELIC_RUN_TYPE`).
+2. **`pytest.ini` / `pyproject.toml`** under `testrelic_options`.
+3. **`.testrelic/testrelic-config.json`** in the project root.
+
+### `pyproject.toml`
+
+```toml
+[tool.pytest.ini_options]
+testrelic_options = [
+  "outputPath=./test-results/testrelic-timeline.json",
+  "includeDeviceLogs=true",
+  "includeNetworkLogs=true",
+  "screenshotOnEvery=failure",
+  "includeVideoRecording=false",
+]
+```
+
+### CLI flags
+
+```bash
+pytest --testrelic-output ./test-results/custom.json
+pytest --testrelic-disable          # turn the reporter off for this run
+pytest --testrelic-quiet            # suppress banner output
+pytest --testrelic-no-autowrap      # disable WebDriver auto-detection
+```
+
+### Full option list
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `outputPath` | str | `./test-results/testrelic-timeline.json` | JSON report path |
+| `htmlReportPath` | str | derived from `outputPath` | HTML report path |
+| `openReport` | bool | `false` | Open the HTML report in the default browser after the run |
+| `includeDeviceLogs` | bool | `true` | Capture Android `logcat` / iOS `syslog` and `crashlog` |
+| `includeNetworkLogs` | bool | `true` | Capture HTTP network requests and responses |
+| `includeConsoleLogs` | bool | `true` | Capture webview / browser console output |
+| `includeScreenshots` | bool | `true` | Capture device screenshots |
+| `screenshotOnEvery` | `off` \| `on` \| `on-failure` \| `on-every-step` | `on-failure` | When to take screenshots |
+| `includeVideoRecording` | bool | `false` | Record the device screen for each test |
+| `includeCommands` | bool | `true` | Record every Appium / WebDriver command |
+| `includeAssertions` | bool | `true` | Record assertion steps |
+| `deviceLogPollInterval` | int (ms) | `1000` | Interval between device log polls (min `100`) |
+| `maxDeviceLogMb` | int | `20` | Truncate per-test device log buffer above this size |
+| `preferBiDi` | bool | `true` | Try BiDi `log.entryAdded` before polling |
+| `redactPatterns` | list[str] | `[]` | Extra regex patterns to redact (built-ins always apply) |
+| `quiet` | bool | `false` | Suppress the console summary table at session end |
+| `metadata` | dict | `null` | Arbitrary key-value pairs attached to the run report |
+| `cloud` | object | — | Cloud upload configuration (see below) |
+
+### Cloud integration
+
+Set `TESTRELIC_API_KEY` and the reporter uploads the run to
+`https://platform.testrelic.ai/api/v1/runs` at session end.
+
+```bash
+export TESTRELIC_API_KEY=tk_live_...
+export TESTRELIC_UPLOAD_STRATEGY=both   # realtime | batch | both | none
+```
+
+Or use a project file:
+
+```json
+// .testrelic/testrelic-config.json
+{
+  "cloud": {
+    "apiKey": "$TESTRELIC_API_KEY",
+    "endpoint": "https://platform.testrelic.ai/api/v1",
+    "upload": "both",
+    "projectName": "my-mobile-app"
+  }
+}
+```
+
+Network failures are queued to `.testrelic/queue/` and retried with:
+
+```bash
+testrelic-appium drain
+testrelic-appium cleanup-queue --max-age-days 7
+```
+
+### Parallel runs (pytest-xdist)
+
+`pytest -n 2` runs workers as separate subprocesses. The master process
+creates the cloud run during `pytest_configure`, writes a manifest, and
+finalizes the run after all workers exit. Each worker uploads its per-test
+realtime data under the master's run ID — exactly one run shows up on the
+dashboard.
+
+## CLI
+
+```bash
+testrelic-appium version
+testrelic-appium merge shard-1.json shard-2.json -o merged.json
+testrelic-appium serve ./test-results --port 9323
+testrelic-appium drain
+testrelic-appium cleanup-queue --max-age-days 7
+```
+
+## Manual driver wrap
+
+If auto-detection misses your driver (custom subclass, fixture indirection,
+non-pytest harness), use the explicit fixture or wrap function:
+
+```python
+import pytest
+from testrelic_appium import testrelic_appium_driver  # fixture
+
+def test_with_explicit_fixture(testrelic_appium_driver):
+    driver = testrelic_appium_driver  # already wrapped
+    driver.find_element("accessibility id", "btn").click()
+```
+
+```python
+from testrelic_appium import wrap_driver
+
+def test_with_manual_wrap(driver):
+    unwrap = wrap_driver(driver)
+    try:
+        driver.find_element("accessibility id", "btn").click()
+    finally:
+        unwrap()
+```
+
+## Compatibility
+
+- Python 3.9 – 3.12
+- pytest 7.0+
+- Appium-Python-Client 4.x – 5.x
+- Appium 2.x / 3.x
+
+## License
+
+MIT — see [LICENSE](https://github.com/testrelic-ai/testrelic-python-sdk/blob/main/packages/testrelic-appium/LICENSE).

testrelic_appium-0.1.0/README.md

@@ -0,0 +1,256 @@
+# testrelic-appium
+
+Appium test analytics reporter for **pytest** — captures command timelines,
+device logs (Android `logcat` / iOS `syslog`), console logs, network requests,
+screenshots, and video, then generates a self-contained interactive HTML
+report. Python port of
+[`@testrelic/appium-analytics`](https://www.npmjs.com/package/@testrelic/appium-analytics).
+
+## What it does
+
+When you run your Appium tests with `pytest` and the `testrelic-appium` plugin
+installed, you get JSON + HTML reports that capture:
+
+- **Command timeline** — every Appium / WebDriver command with timing,
+  category (`find`, `interaction`, `gesture`, `navigation`, `lifecycle`,
+  `context`, `device`, `keyboard`, `alert`, `screenshot`, `other`), selector,
+  arguments (sensitive ones redacted), and result.
+- **Device logs** — Android `logcat`, iOS `syslog` and `crashlog`, polled in
+  the background and sliced per test.
+- **Console logs** — WebView / browser console output via WebDriver BiDi
+  (`log.entryAdded`) when supported, with polling fallback (`browser`,
+  `safariConsole`).
+- **Network capture** — Chrome DevTools Protocol performance logs (Android),
+  `safariNetwork` (iOS), with optional `mitmproxy` fallback for emulators
+  without CDP.
+- **Screenshots & video** — configurable: off, on every test, on failure, or
+  on every step. Video uses Appium recording commands first, falling back to
+  `adb screenrecord`.
+- **Assertions** — `assert_that(...)` context manager records named assertion
+  steps; bare `assert` statements are picked up by `pytest_assertion_pass`.
+- **CI metadata** — auto-detect GitHub Actions, GitLab CI, Jenkins, CircleCI,
+  Bitbucket Pipelines.
+- **Sensitive-data redaction** — AWS access keys, Bearer tokens, PEM private
+  keys, embedded URL credentials, plus Appium-specific command-argument
+  redaction (`elementSendKeys`, `setValueImmediate`, `replaceValue`).
+- **HTML report** — self-contained, opens in any browser.
+
+## System requirements
+
+The package itself has no platform requirements beyond Python, but to test
+mobile apps you'll need the standard Appium tooling on your machine. None of
+these are pip dependencies — they are subprocess dependencies the SDK invokes
+when needed.
+
+| Tool | Required for |
+|---|---|
+| Appium server (`npm install -g appium`) | All tests |
+| `appium driver install uiautomator2` | Android |
+| `appium driver install xcuitest` | iOS (macOS only) |
+| `adb` on `PATH` | Android device-log capture, video recording fallback, proxy network capture |
+| `xcrun simctl` | iOS simulators |
+
+> **iOS testing requires macOS 13+ with Xcode 15+.** iOS tests cannot run on Windows or Linux.
+
+## Quick start
+
+### 1. Install
+
+```bash
+pip install testrelic-appium
+```
+
+The plugin activates automatically because `testrelic-appium` registers a
+`pytest11` entry point. No `conftest.py` plumbing required.
+
+For the optional HTTPS network-capture proxy:
+
+```bash
+pip install "testrelic-appium[network-proxy]"
+```
+
+### 2. Write a test
+
+Use any Appium driver instantiation pattern. The plugin walks
+`item.funcargs` after each fixture resolves and per-instance wraps any
+`appium.webdriver.webdriver.WebDriver` it finds — Selenium-only tests are
+never touched.
+
+```python
+# tests/test_login.py
+import pytest
+from appium import webdriver
+from appium.options.android import UiAutomator2Options
+
+
+@pytest.fixture
+def driver():
+    options = UiAutomator2Options()
+    options.platform_name = "Android"
+    options.device_name = "emulator-5554"
+    options.app = "/path/to/MyApp.apk"
+    d = webdriver.Remote("http://127.0.0.1:4723", options=options)
+    yield d
+    d.quit()
+
+
+def test_login_succeeds(driver):
+    driver.find_element("accessibility id", "username").send_keys("alice")
+    driver.find_element("accessibility id", "password").send_keys("hunter2")
+    driver.find_element("accessibility id", "submit").click()
+    assert driver.find_element("accessibility id", "welcome").is_displayed()
+```
+
+### 3. Run
+
+```bash
+pytest
+```
+
+Outputs land in:
+
+```
+test-results/
+├── testrelic-timeline.json
+└── testrelic-timeline.html
+```
+
+## Configuration
+
+Reporter options can be supplied three ways (highest priority first):
+
+1. **Environment variables** (`TESTRELIC_API_KEY`, `TESTRELIC_CLOUD_ENDPOINT`,
+   `TESTRELIC_UPLOAD_STRATEGY`, `TESTRELIC_CLOUD_TIMEOUT`,
+   `TESTRELIC_RUN_TYPE`).
+2. **`pytest.ini` / `pyproject.toml`** under `testrelic_options`.
+3. **`.testrelic/testrelic-config.json`** in the project root.
+
+### `pyproject.toml`
+
+```toml
+[tool.pytest.ini_options]
+testrelic_options = [
+  "outputPath=./test-results/testrelic-timeline.json",
+  "includeDeviceLogs=true",
+  "includeNetworkLogs=true",
+  "screenshotOnEvery=failure",
+  "includeVideoRecording=false",
+]
+```
+
+### CLI flags
+
+```bash
+pytest --testrelic-output ./test-results/custom.json
+pytest --testrelic-disable          # turn the reporter off for this run
+pytest --testrelic-quiet            # suppress banner output
+pytest --testrelic-no-autowrap      # disable WebDriver auto-detection
+```
+
+### Full option list
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `outputPath` | str | `./test-results/testrelic-timeline.json` | JSON report path |
+| `htmlReportPath` | str | derived from `outputPath` | HTML report path |
+| `openReport` | bool | `false` | Open the HTML report in the default browser after the run |
+| `includeDeviceLogs` | bool | `true` | Capture Android `logcat` / iOS `syslog` and `crashlog` |
+| `includeNetworkLogs` | bool | `true` | Capture HTTP network requests and responses |
+| `includeConsoleLogs` | bool | `true` | Capture webview / browser console output |
+| `includeScreenshots` | bool | `true` | Capture device screenshots |
+| `screenshotOnEvery` | `off` \| `on` \| `on-failure` \| `on-every-step` | `on-failure` | When to take screenshots |
+| `includeVideoRecording` | bool | `false` | Record the device screen for each test |
+| `includeCommands` | bool | `true` | Record every Appium / WebDriver command |
+| `includeAssertions` | bool | `true` | Record assertion steps |
+| `deviceLogPollInterval` | int (ms) | `1000` | Interval between device log polls (min `100`) |
+| `maxDeviceLogMb` | int | `20` | Truncate per-test device log buffer above this size |
+| `preferBiDi` | bool | `true` | Try BiDi `log.entryAdded` before polling |
+| `redactPatterns` | list[str] | `[]` | Extra regex patterns to redact (built-ins always apply) |
+| `quiet` | bool | `false` | Suppress the console summary table at session end |
+| `metadata` | dict | `null` | Arbitrary key-value pairs attached to the run report |
+| `cloud` | object | — | Cloud upload configuration (see below) |
+
+### Cloud integration
+
+Set `TESTRELIC_API_KEY` and the reporter uploads the run to
+`https://platform.testrelic.ai/api/v1/runs` at session end.
+
+```bash
+export TESTRELIC_API_KEY=tk_live_...
+export TESTRELIC_UPLOAD_STRATEGY=both   # realtime | batch | both | none
+```
+
+Or use a project file:
+
+```json
+// .testrelic/testrelic-config.json
+{
+  "cloud": {
+    "apiKey": "$TESTRELIC_API_KEY",
+    "endpoint": "https://platform.testrelic.ai/api/v1",
+    "upload": "both",
+    "projectName": "my-mobile-app"
+  }
+}
+```
+
+Network failures are queued to `.testrelic/queue/` and retried with:
+
+```bash
+testrelic-appium drain
+testrelic-appium cleanup-queue --max-age-days 7
+```
+
+### Parallel runs (pytest-xdist)
+
+`pytest -n 2` runs workers as separate subprocesses. The master process
+creates the cloud run during `pytest_configure`, writes a manifest, and
+finalizes the run after all workers exit. Each worker uploads its per-test
+realtime data under the master's run ID — exactly one run shows up on the
+dashboard.
+
+## CLI
+
+```bash
+testrelic-appium version
+testrelic-appium merge shard-1.json shard-2.json -o merged.json
+testrelic-appium serve ./test-results --port 9323
+testrelic-appium drain
+testrelic-appium cleanup-queue --max-age-days 7
+```
+
+## Manual driver wrap
+
+If auto-detection misses your driver (custom subclass, fixture indirection,
+non-pytest harness), use the explicit fixture or wrap function:
+
+```python
+import pytest
+from testrelic_appium import testrelic_appium_driver  # fixture
+
+def test_with_explicit_fixture(testrelic_appium_driver):
+    driver = testrelic_appium_driver  # already wrapped
+    driver.find_element("accessibility id", "btn").click()
+```
+
+```python
+from testrelic_appium import wrap_driver
+
+def test_with_manual_wrap(driver):
+    unwrap = wrap_driver(driver)
+    try:
+        driver.find_element("accessibility id", "btn").click()
+    finally:
+        unwrap()
+```
+
+## Compatibility
+
+- Python 3.9 – 3.12
+- pytest 7.0+
+- Appium-Python-Client 4.x – 5.x
+- Appium 2.x / 3.x
+
+## License
+
+MIT — see [LICENSE](https://github.com/testrelic-ai/testrelic-python-sdk/blob/main/packages/testrelic-appium/LICENSE).