Metadata-Version: 2.4
Name: testrelic-appium
Version: 0.2.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).
