maestro-runner CLI
Runs Maestro flows on Android, iOS and in the browser as a single binary without a JVM and installs a skill for the agent.
- 529 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Tests drive devices and emulators: they tap and type in apps.
- Install pipes `curl | bash` and the signed iPhone agent uses your Apple Team ID.
Install
- Works in
Manual install
curl -fsSL https://open.devicelab.dev/install/maestro-runner | bashFirst README install command. Then `maestro-runner skills install` adds the agent skill.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Tests drive devices and emulators: they tap and type in apps.
- Install pipes `curl | bash` and the signed iPhone agent uses your Apple Team ID.
This is third-party code. Review the repository files before installing.
What it does
maestro-runner is an open-source UI test runner for Maestro YAML flows, written in Go. It runs existing flows unchanged on Android emulators and real devices, iOS simulators and iPhones, Chrome over CDP and clouds through Appium. Parallel runs across devices, HTML, JUnit and Allure reports, and JavaScript scripting are built in. `maestro-runner skills install` writes a skill to `~/.claude/skills/maestro-runner/SKILL.md`. It teaches the agent to write flows, run them, inspect the screen hierarchy and read reports. `doctor` and `devices` help diagnose, while `hierarchy` and `screenshot` show what the test sees.
Who it is for. Mobile QA engineers and React Native, Flutter and Expo teams running Maestro UI flows who want an agent to write them.
Good fit when
- Maestro flows are slow on CI and a faster run without a JVM helps.
- A test fails with an unclear error and the agent reads the screen hierarchy to pick a selector.
- One flow set runs across several devices in parallel.
- A run on a real iPhone is needed, not only a simulator.
- A web UI is checked in Chrome with the same YAML flows as the mobile app.
Not a fit when
- You need official Maestro Studio and cloud: this is an independent replacement with its own engine.
- Tests are written in XCUITest, Espresso or Detox and no Maestro YAML is used.
- The run happens on Windows without WSL: binaries exist for macOS and Linux.
Example request
Run `maestro-runner doctor`, show the screen hierarchy on the connected Android and write a login flow for the app.Limitations
Builds exist for macOS and Linux on arm64 and x64 and Windows works through WSL. This is a separate engine reading the Maestro YAML format, so individual commands may behave differently. A real iPhone needs an Apple `--team-id` to sign the agent. The install command pipes a script through `curl | bash`, so read it first. `doctor` shows what is missing: Android SDK, Xcode or a browser.
How to disable. Delete the `maestro-runner` binary (or the `node_modules` package) and `~/.claude/skills/maestro-runner`. Test reports stay in the run folder and go separately.
FAQ
Must I rewrite Maestro flows?
No. Existing YAML runs as is with `maestro-runner test flow.yaml`.
How do I install the skill per repository rather than globally?
Run `maestro-runner skills install --dir .claude/skills/maestro-runner`. The `--print` flag just prints the skill text.
Where can tests run?
On Android (emulators and devices), iOS (simulators and iPhones), in Chrome and in BrowserStack, Sauce Labs and LambdaTest clouds through Appium.
How do I install with npm?
`npx maestro-runner test flows/` runs without installing, and `npm install --save-dev maestro-runner` pins the version in the project.
Which reports exist?
HTML, JUnit XML and Allure-compatible.
Discussion
No questions or reviews yet.
Related
CLI toolsMidscene skills drive a browser, desktop, Android, iOS and HarmonyOS from screenshots and build Vitest E2E tests through Claude Code or OpenClaw
A Playwright-style iOS and Android framework: the agent drives a phone through the accessibility tree and a skill writes tests.
Natural-language CLI for iOS, Android and web screens. A saved session becomes a trail that CI replays.
CLI, MCP server and typed Node.js API so an agent can verify its changes in a live mobile app on iOS, Android and more
An MCP server for end-to-end testing: the agent sees a running Flutter, React Native, Electron or other app and drives it
The noqa-testing skill teaches an agent to test iOS and Android: read the screen, tap, write cases and run them on a real phone
README in short
The README shows install (curl, npm), the first run with `doctor` and `devices`, run commands for three platforms, a section on AI agents and the driver and feature list.