@testrelic/maestro-analytics 1.0.0-next.14

package/README.md

@@ -0,0 +1,108 @@
+# @testrelic/maestro-analytics
+
+[![npm](https://img.shields.io/npm/v/@testrelic/maestro-analytics.svg)](https://www.npmjs.com/package/@testrelic/maestro-analytics)
+[![Website](https://img.shields.io/badge/website-testrelic.ai-blue)](https://testrelic.ai)
+
+Maestro mobile testing analytics for the [TestRelic](https://testrelic.ai) observability platform.
+
+Wraps the Maestro CLI to capture rich test telemetry — JUnit results, step-level timing, screenshots, video, AI defect reports, and visual regression data — then uploads everything to the TestRelic dashboard.
+
+## Installation
+
+```bash
+npm install @testrelic/maestro-analytics
+```
+
+## Quick Start
+
+### Mode 1: CLI Wrapper (recommended)
+
+Zero changes to your YAML flows. The wrapper runs Maestro with the right flags and reports results automatically.
+
+```bash
+npx testrelic-maestro test ./flows
+```
+
+### Mode 2: Post-Run Parser
+
+If you already run Maestro in CI, parse existing artifacts after the fact:
+
+```bash
+maestro test --format junit --output report.xml --test-output-dir ./artifacts ./flows
+npx testrelic-maestro report --junit report.xml --artifacts ./artifacts
+```
+
+## Cloud Reporting
+
+Set the `TESTRELIC_API_KEY` environment variable or add it to `.testrelic/testrelic-config.json`:
+
+```json
+{
+  "cloud": {
+    "apiKey": "${TESTRELIC_API_KEY}"
+  }
+}
+```
+
+## What Gets Captured
+
+| Data | Source |
+|------|--------|
+| Flow pass/fail/skip | JUnit XML |
+| Per-step timing | commands-*.json |
+| Assertions | commands-*.json |
+| Screenshots | --test-output-dir |
+| Video recordings | --test-output-dir |
+| AI defect reports | --analyze output |
+| Flow metadata | YAML header (appId, tags, properties) |
+| Device/platform info | CLI output |
+| CI/CD context | Environment detection |
+| Git metadata | Local git |
+
+## E2E Integration Test (Real Device Recording)
+
+The `scripts/e2e-integration-test.mjs` script runs the sample flows in `e2e/flows/` against a real Android device or emulator and uploads the actual screen recordings to TestRelic.
+
+### Prerequisites
+
+1. **Maestro CLI** — install from [maestro.mobile.dev](https://maestro.mobile.dev):
+   ```bash
+   curl -Ls "https://get.maestro.mobile.dev" | bash
+   ```
+2. **Android emulator or device** connected and visible in `adb devices`
+3. **Wikipedia APK** installed on the device — download from [github.com/wikimedia/apps-android-wikipedia/releases](https://github.com/wikimedia/apps-android-wikipedia/releases):
+   ```bash
+   adb install -r wikipedia.apk
+   ```
+4. **TESTRELIC_API_KEY** environment variable set (or `testrelic.config.yaml` present)
+
+### Running
+
+```bash
+# Build the package first
+pnpm build
+
+# Start an Android emulator (if not already running)
+emulator -avd <AVD_NAME>
+
+# Run the real E2E test — captures actual screen recordings
+node scripts/e2e-integration-test.mjs
+```
+
+The script prints a run URL at the end. Open it in your browser to verify:
+- The video shows the **actual app screen recording** (not a placeholder clip)
+- Each flow shows its **own recording** when selected in the sidebar
+
+### Synthetic Test Scripts (pipeline validation only)
+
+The other scripts in `scripts/` use placeholder/synthetic video data and do **not** run real device tests:
+
+| Script | What it uploads |
+|--------|----------------|
+| `cloud-upload-test.mjs` | 32-byte stub MP4 (non-playable) |
+| `cloud-realtime-test.mjs` | ffmpeg black frame or Big Buck Bunny sample |
+| `e2e-integration-test.mjs` | **Real app screen recording** ← use this |
+
+## License
+
+MIT