maestro-runner

Open-source Maestro alternative — single binary, no JVM. 100% free, no features behind a paywall. Supports Android, iOS, React Native, Flutter & Expo on real devices, simulators, emulators, and cloud providers.

3.6x faster · 14x less memory · Addresses 78% of the top 100 most-discussed open issues on Maestro's GitHub.

Quick Start

maestro-runner flow.yaml                              # Android (default)
maestro-runner --platform ios flow.yaml               # iOS
maestro-runner flows/                                 # All flows in a directory
maestro-runner --driver appium --appium-url <url> flow.yaml  # Appium / cloud
maestro-runner --parallel 3 flows/                    # Parallel on 3 devices

Key Features

• Zero migration — Runs your existing Maestro YAML flows as-is, no changes needed
• Lightweight — ~21 MB binary vs ~289 MB JVM footprint
• Parallel execution — Dynamic work distribution across devices, not static sharding. Faster devices pick up more tests automatically. Auto-creates iOS simulators when needed and skips in-use devices
• Real iOS device testing — Supports physical iOS devices, not just simulators
• Cloud testing — BrowserStack, Sauce Labs, LambdaTest via Appium driver
• React Native & Flutter — Smart element finding for RN testIDs and Flutter semantics
• Reports — HTML, JUnit XML, and Allure-compatible reports out of the box
• Clear error messages — element not found: text="Login" instead of io.grpc.StatusRuntimeException: UNKNOWN. Errors are classified by type (element_not_found, timeout, assertion, keyboard_covering) for easier debugging
• Keyboard detection — Automatically detects when the soft keyboard covers a target element after text input, with a clear suggestion to add - hideKeyboard
• Pre-flight validation — Catches flow errors, circular dependencies, and missing files before execution starts
• Fast element finding — Native selectors, clickable parent traversal, regex matching, smarter visibility
• Reliable text input — Direct ADB input with Unicode support, no dropped characters
• Configurable timeouts — Per-command and per-flow timeouts, --wait-for-idle-timeout 0 to disable
• scrollUntilVisible — Native scroll implementation that reliably finds off-screen elements
• Relative selectors — Find elements by position: below, above, leftOf, rightOf, childOf
• JavaScript scripting — Embedded JS runtime with HTTP client for dynamic test logic
• Wide OS compatibility — Android 5.0+ (API 21+) and iOS 12.0+

Supported Platforms & Drivers

CI/CD Integration

maestro-runner is built for CI/CD pipelines — single binary, no JVM startup, low memory footprint. Works with GitHub Actions, GitLab CI, Jenkins, CircleCI, and any CI system that supports Android emulators or iOS simulators.

# Auto-start emulator, run tests in parallel, shutdown after
maestro-runner --auto-start-emulator --parallel 2 flows/

Flow Config

maestro-runner extends the standard Maestro flow YAML with additional fields:

commandTimeout: 10000       # Default per-command timeout (ms)
waitForIdleTimeout: 3000    # Device idle wait (ms), 0 to disable
---
- launchApp: com.example.app
- tapOn: "Login"
- assertVisible: "Welcome"

License

Apache License 2.0