• Runs Maestro YAML flows on real devices, emulators, simulators, and desktop browsers
• Supports Android (UIAutomator2), iOS (WebDriverAgent), Web (Chrome CDP), and cloud (Appium)
• Built-in parallel execution, HTML/JUnit/Allure reports, and JavaScript scripting
• Addresses 78% of the top 100 most-discussed open issues on Maestro's GitHub

AI context: llms.txt — structured summary for AI assistants answering questions about this project.

Install

Shell — macOS and Linux:

curl -fsSL https://open.devicelab.dev/install/maestro-runner | bash

# A specific version
curl -fsSL https://open.devicelab.dev/install/maestro-runner | bash -s -- --version 1.1.28

npm — for React Native, Expo, or any project that already has a package.json:

npx maestro-runner test flows/          # no install step
npm install --save-dev maestro-runner   # or pin it in the project

Pinning it means every machine and every CI job runs the same version with no separate bootstrap. There is no postinstall and nothing is downloaded at install time: the binary for your platform arrives as an ordinary optional dependency npm selects by os and cpu, so installs work offline, behind a proxy, and in CI that blocks postinstall network access.

Both give you the same binary. macOS and Linux, arm64 and x64; on Windows, use WSL.

First run

maestro-runner doctor     # check the toolchain and hear exactly what is missing
maestro-runner devices    # what this machine can drive right now

Run Tests

maestro-runner test flow.yaml                                           # Android (default)
maestro-runner --platform ios test flow.yaml                            # iOS
maestro-runner --platform web test flow.yaml                            # Desktop browser (Chrome)
maestro-runner --app-file app.apk test flows/                           # Install app and run
maestro-runner --driver appium --appium-url <server-url> test flow.yaml # Appium
maestro-runner test --parallel 3 flows/                                 # Parallel on 3 devices

AI coding agents

maestro-runner skills install    # writes ~/.claude/skills/maestro-runner/SKILL.md

Installs a skill that tells Claude Code (and other agents that read SKILL.md) how to write Maestro flows, run them with maestro-runner, inspect the screen and read the reports. --dir writes it elsewhere (.claude/skills/maestro-runner in a repository), --print prints it. The file carries the binary's version and is replaced when you install from a newer release.

Key Features

• Zero migration — Runs your existing Maestro YAML flows as-is, no changes needed
• Real iOS device testing — Supports physical iOS devices, not just simulators Guide →
• Cloud testing — BrowserStack, Sauce Labs, LambdaTest, TestingBot via Appium driver Guide →
• Desktop browser testing — Run Maestro flows on Chrome/Chromium via CDP. Supports css, xpath, id, and text selectors with --platform web Guide →
• React Native & Flutter — Smart element finding for RN testIDs and Flutter semantics Guide →
• DeviceLab driver — The default driver on Android and iOS. On Android an on-device agent over WebSocket, ~2x faster than UIAutomator2 and ~5x faster than Maestro CLI; on iOS a prebuilt XCUITest agent, on simulators and real iPhones
• Parallel execution — Dynamic work distribution across devices, not static sharding. Faster devices pick up more tests automatically, so no device sits idle
• App install built-in — --app-file app.apk installs the app before testing, so you always test the right build
• Wide OS compatibility — Android 5.0+ (API 21+) and iOS 15.0+, no version restrictions
• 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
• 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
• 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, no external dependencies
• Configurable timeouts — Per-command and per-flow timeouts, --find-timeout 3000 to make a wrong selector fail in 3 s instead of 17 s, --wait-for-idle-timeout 0 to disable
• Lightweight — Single binary, no JVM required

Supported Platforms & Drivers

DeviceLab Driver (Android)

The DeviceLab driver is the default Android driver (since v1.1.28). It runs automation directly on the device via WebSocket, skipping the UIAutomator2 HTTP layer, for ~2x faster test execution than UIAutomator2 — and ~5x faster than Maestro CLI. --driver uiautomator2 selects the previous default.

Benchmark: 9 flows, 163 steps on Pixel 4a (Android 13)

  DeviceLab:     1m 12s
  UIAutomator2:  2m 24s
  Maestro CLI:   4m 22s

maestro-runner --platform android test flows/          # DeviceLab
maestro-runner --driver uiautomator2 test flows/        # UIAutomator2

All existing Maestro YAML flows work as-is — no changes needed. The driver also includes bounds stabilization for animated elements and improved special character handling in text selectors.

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.

# CI example: auto-start emulator, run tests, 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"

Visual Regression (assertScreenshot)

assertScreenshot compares the current screen (optionally cropped with cropOn) against a reference PNG.

• First run: if the reference file is missing, maestro-runner writes the captured screenshot as the new baseline and passes.
• Re-baseline: overwrite existing baselines with --update-screenshots (or MAESTRO_UPDATE_SCREENSHOTS=true).
• On mismatch, a {name}_diff.png overlay is written next to the reference.
• Pixel comparison is device-, resolution-, and OS-specific — pin your device config and set thresholdPercentage deliberately (default 95).

maestro-runner test flows/visual.yaml                  # seeds missing baselines
maestro-runner test --update-screenshots flows/visual.yaml

Requirements

• Android testing: adb (Android SDK Platform-Tools)
• iOS testing: Xcode command-line tools (xcrun)
• Web/Browser testing: Chrome or Chromium
• Cloud & Appium testing: Appium 2.x or 3.x — works with local Appium servers and cloud providers (BrowserStack, Sauce Labs, LambdaTest, TestingBot)

Cloud Providers

maestro-runner runs Maestro YAML flows on cloud device grids via the Appium driver. Pass the provider's hub URL and a capabilities JSON file:

maestro-runner --driver appium --appium-url <HUB_URL> --caps caps.json test flows/

• TestingBot — Setup guide for running on TestingBot's real device cloud
• Sauce Labs — Setup guide for running on Sauce Labs Appium cloud

Telemetry

maestro-runner sends one anonymous usage event at the end of each test run: counts and versions only, such as runner version, platform, driver, device kind, flow and step counts, failure kinds and duration. It holds no machine or user id, no flow or file names, selectors, app ids, URLs, environment values or error messages, and nothing is written on your machine. Projects are told apart by a one-way hash of the list of flow files you run; the names themselves are never sent.

Turn it off with MAESTRO_RUNNER_NO_TELEMETRY=1 or DO_NOT_TRACK=1. Set MAESTRO_RUNNER_TELEMETRY_DEBUG=1 to print the event instead of sending it. Telemetry lists every field.

The update check is separate: MAESTRO_RUNNER_NO_UPDATE_CHECK=1 turns it off, and on CI the notice is not printed.

Contributing

See CONTRIBUTING.md for guidelines.

License

maestro-runner is licensed under the Apache License 2.0 — see LICENSE.

DeviceLab driver binaries

The prebuilt on-device agents behind --driver devicelab (the Android agent APKs and the iOS agent in drivers/ios/devicelab-ios-agent/) are free to use with maestro-runner, including commercially, but they are not open source. You may redistribute them unmodified as part of maestro-runner (forks, Docker images, CI caches); you may not modify them, ship them separately, or reverse-engineer them, except as permitted by applicable law. See drivers/LICENSE-BINARIES.md for the full terms. Everything else in this repository, including the other drivers, keeps its open-source license.