maestro-reporter

Playwright-style HTML reporter for Maestro mobile UI tests.

Runs your Maestro flows, captures results, steps and screenshots, then serves an interactive report locally — no configuration required.

Installation

npm install -g maestro-reporter

Requires Node.js 16+ and Maestro installed on the machine.

Usage

1. Run tests

maestro-reporter flows/

Runs all flows, saves the report, then exits.

maestro-reporter --config config.yaml flows/         # with config file
maestro-reporter --include-tags smokeTest flows/     # tagged subset
maestro-reporter flows/login/login.yaml              # single flow

2. Open the report

maestro-reporter show

Starts a local server, opens the browser, and stays running until Ctrl+C. Auto-detects the latest run — no path needed.

maestro-reporter show --port 9000     # custom port
maestro-reporter show --no-open       # start server without opening browser

Options

Run options

| Option | Description | |---|---| | --config <file> | Maestro config file | | --include-tags <tags> | Run only flows with these tags | | --exclude-tags <tags> | Skip flows with these tags |

Show options

| Option | Default | Description | |---|---|---| | --port <n> | 9323 | Port to serve on (auto-increments if busy) | | --no-open | — | Do not open browser automatically |

npm scripts integration

{
  "scripts": {
    "test":       "maestro-reporter --config config.yaml flows/",
    "test:smoke": "maestro-reporter --config config.yaml --include-tags smokeTest flows/",
    "test:login": "maestro-reporter flows/login/login.yaml",
    "report":     "maestro-reporter show"
  }
}

Run from the terminal or the VS Code NPM Scripts panel:

• npm test — run all tests
• npm run report — open the last report

Report features

• Summary bar — passed, failed, skipped counts and total duration
• Filter — filter tests by status (All / Passed / Failed / Skipped)
• Step-by-step breakdown — every Maestro command with pass/fail/skip status and timing
• Screenshots — failure screenshots and named screenshots inline
• Lightbox — click any screenshot to zoom fullscreen
• Auto-cleanup — each run replaces the previous report

Capturing failure screenshots

Add onFlowComplete to your flow header to always capture the screen state at the end of a run, including on failure:

appId: com.example.app
onFlowComplete:
  - takeScreenshot: screenshots/my_flow_final
---
- launchApp
- tapOn: "Login"

onFlowComplete fires whether the flow passed or failed, so you always get a screenshot showing exactly where it stopped.

Output structure

reports/
└── run-2026-05-25T19-00-00/
    ├── report.html
    └── artifacts/
        └── screenshots/

Each run cleans up the previous one automatically.

How it works

1. Wraps maestro test --format HTML-DETAILED to capture steps and screenshots
2. Parses the output to extract tests, steps, and error messages
3. Matches screenshots from the artifacts folder to their flows
4. Serves everything as a local web app on http://localhost:<port>