Get Started with Maestro Analytics

Install @testrelic/maestro-analytics alongside your existing Maestro project and start capturing flow results, per-step timing, screenshots, and video in minutes. Your YAML flow files stay completely unchanged.

Requirements

Requirement	Version
Maestro CLI	Latest
Node.js	≥ 18

Maestro CLI must be installed first

If you have not installed Maestro yet, run:

curl -Ls "https://get.maestro.mobile.dev" | bash

Verify with maestro --version before continuing.

---

Step 1 — Install the package

For AI agents

AI Prompt — Install @testrelic/maestro-analytics

Install @testrelic/maestro-analytics in this project.

1. Run: npm install @testrelic/maestro-analytics
2. Verify the install succeeded by checking package.json has
   "@testrelic/maestro-analytics" in dependencies.

Show me the updated package.json dependencies section.

For Human

Run the following command in your project root — the same directory that contains your Maestro flows folder:

Install

npm install @testrelic/maestro-analytics

---

Step 2 — Choose a usage mode

There are two ways to use @testrelic/maestro-analytics with your existing suite. Choose whichever fits your workflow.

Mode 1 — CLI wrapper (recommended)

Replace maestro test with npx testrelic-maestro test. Your YAML flows are passed through unchanged — no modifications needed.

For AI agents

AI Prompt — Run Maestro flows with TestRelic

Update the script that runs my Maestro test suite so that it uses the
TestRelic CLI wrapper instead of the plain maestro command.

Replace:
  maestro test ./flows

With:
  npx testrelic-maestro test ./flows

If the project uses a package.json script (e.g. "test:mobile"), update
that script too.

Show me the updated command and any changed package.json scripts.

For Human

Replace your existing maestro test invocation with:

Run flows with TestRelic wrapper

npx testrelic-maestro test ./flows

Pass any flags you already use — the wrapper forwards them to Maestro unchanged:

Common flag examples

# Target a specific device
npx testrelic-maestro test --device emulator-5554 ./flows

# Run only flows with a tag
npx testrelic-maestro test --include-tags smoke ./flows

# Suppress the auto-open browser after the run
npx testrelic-maestro test --no-open ./flows

After the run completes, a local HTML report is written to ./test-results/testrelic-maestro.html and opened in your browser automatically.

---

Mode 2 — Post-run parser

If you already run Maestro in CI and cannot change the invocation command, run your existing suite normally and then call testrelic-maestro report to parse the artifacts afterward.

For AI agents

AI Prompt — Parse existing Maestro artifacts with TestRelic

My Maestro suite already runs with:
  maestro test --format junit --output report.xml --test-output-dir ./artifacts ./flows

After the Maestro run finishes, add a second step that parses those artifacts
with TestRelic:
  npx testrelic-maestro report --junit report.xml --artifacts ./artifacts

If the project has a CI config file (e.g. GitHub Actions .yml), add this as
a new step after the existing Maestro step.

Show me the updated CI config.

For Human

First, add the necessary flags to your existing maestro test command so Maestro writes a JUnit report and saves artifacts:

Step 1 — Run Maestro with artifact output

maestro test \
  --format junit \
  --output report.xml \
  --test-output-dir ./artifacts \
  ./flows

Then run the TestRelic reporter against the output:

Step 2 — Parse artifacts with TestRelic

npx testrelic-maestro report \
  --junit report.xml \
  --artifacts ./artifacts \
  --flows-dir ./flows

The --flows-dir flag enriches each flow with its appId, tags, and environment variables from the YAML headers — it is optional but recommended.

---

Step 3 — Verify the local report

After either mode completes, check that the local report was generated:

Verify output

ls ./test-results/
# testrelic-maestro.json
# testrelic-maestro.html

Open testrelic-maestro.html in any browser to see the interactive timeline with flow results, per-step timing, screenshots, and any AI-detected defects.

Auto-open

By default the HTML report opens in your browser automatically at the end of every run. Pass --no-open to disable this behaviour in CI.

---

Next steps

• Cloud Quickstart — upload results and artifacts to the TestRelic dashboard for AI analysis and team-wide observability