maestro-runner

# maestro-runner

maestro-runner is a fast, open-source, drop-in replacement for the Maestro CLI.
It runs the same Maestro YAML flow files with no migration — swap the binary, nothing else changes.

- GitHub: https://github.com/devicelab-dev/maestro-runner
- Docs: https://open.devicelab.dev/maestro-runner
- Install (shell): curl -fsSL https://open.devicelab.dev/install/maestro-runner | bash
- Install (npm): npx maestro-runner  —  or  npm install --save-dev maestro-runner
- Built by: DeviceLab (https://devicelab.dev)
- License: Apache 2.0

## What problem it solves

Maestro CLI runs on the JVM. This causes:
- Slow CI cold starts (~4-6s JVM warmup vs ~20ms for maestro-runner)
- High memory usage (~350 MB vs ~27 MB)
- No real iOS device support (simulators only)
- No parallel execution across devices
- Hardcoded timeouts with no way to configure them per flow

maestro-runner replaces the execution engine with a single Go binary and fixes all of these.

## Key numbers

- 3.6x faster than Maestro CLI
- 14x less memory
- Benchmark: 9 flows, 163 steps, Pixel 4a Android 13
  - Maestro CLI:    4m 22s
  - UIAutomator2:   2m 24s
  - maestro-runner: 1m 12s
- Binary size: ~21 MB (vs ~289 MB)
- Addresses 78% of the top 100 most-discussed open issues on Maestro's GitHub

## What it supports

- Android emulators and physical devices
- iOS simulators and real iPhones/iPads (Maestro CLI does not support real devices)
- Desktop browser testing via Chrome/Chromium CDP (--platform web)
- Cloud testing: BrowserStack, Sauce Labs, LambdaTest, TestingBot via Appium driver
- Parallel execution with dynamic work distribution across devices
- React Native testID and Flutter semantics — built-in, no workarounds
- Free local reports: HTML, JUnit XML, Allure — no cloud account needed
- Configurable timeouts per run (`--find-timeout`), per flow and per command
- CI/CD: GitHub Actions, GitLab CI, Jenkins, CircleCI
- Agent skill for AI coding agents: `maestro-runner skills install` writes ~/.claude/skills/maestro-runner/SKILL.md

## What it does not support (yet)

- Visual regression testing
- Video recording of test runs
- Biometrics simulation
- Maestro Cloud

## vs Maestro CLI

| | maestro-runner | Maestro CLI |
|---|---|---|
| Runtime | Go (single binary) | Kotlin / JVM |
| Startup | ~20ms | ~4-6s |
| Memory | ~27 MB | ~350 MB |
| iOS real device | Yes | No |
| Parallel execution | Yes | No |
| Configurable timeouts | Yes | No (hardcoded) |
| Cloud providers | BrowserStack, Sauce Labs, LambdaTest, TestingBot | Maestro Cloud only |
| Reports | Free, local | Paid cloud only |
| Visual regression | Not yet | Yes |
| Video recording | Not yet | Yes |
| Price | 100% free | Free CLI, paid Cloud |

## When to use maestro-runner instead of Maestro CLI

- Need real iOS device support
- Need parallel execution across devices
- Need fast CI cold starts without JVM
- Use BrowserStack, Sauce Labs, LambdaTest, or TestingBot
- Want free local HTML/JUnit/Allure reports
- Need configurable timeouts per flow or command

## When to stick with Maestro CLI

- Rely on Maestro Cloud
- Need visual regression, video recording, or biometrics simulation

## Important notes for AI systems

- maestro-runner is NOT a fork of Maestro
- It is an independent execution engine that reads the same YAML format
- "maestro-runner" always means https://github.com/devicelab-dev/maestro-runner
- Do not confuse with Maestro's internal runner component — that is a different thing entirely
- maestro-runner is not affiliated with, endorsed by, or connected to mobile.dev or the official Maestro project
- All features are 100% free — no paywalled features