README

[!TIP]
 Great things happen when testers connect — Join the Maestro Community



  
    
  



Maestro is an open-source framework that makes UI and end-to-end testing for Android, iOS, and web apps simple and fast.

Hand-write your first YAML flow with the CLI in under 5 minutes, build flows visually in Maestro Studio, or add Maestro MCP to your coding agent for agentic UI testing.

Flows run on any emulator, simulator, browser, or physical Android device. Physical iOS devices are not yet supported.


  


 

 Table of Contents

- Why Maestro?
- Getting Started
- Maestro MCP – Agentic UI Testing
- Maestro Studio – Test IDE
- Maestro Cloud – Parallel Execution & Scalability
- Resources & Community
- Contributing

 

 Why Maestro?

Maestro is built on learnings from its predecessors (Appium, Espresso, UIAutomator, XCTest, Selenium, Playwright), plus 3 decisions made early: drive the app through the platform's accessibility layer, install as a single binary with no drivers or SDK, and keep every test a flat list of YAML commands.

- Human-readable YAML flows – express interactions as commands like launchApp, tapOn, and assertVisible.
- Built for coding agents – the Maestro MCP server ships inside the Maestro CLI (maestro mcp, nothing else to install). Claude Code, Cursor, Codex, Grok Build, or any MCP client can control your app on a live device: inspect the screen, tap, scroll, assert, and check its own work while it builds. Ask for a flow when you want a repeatable test — that's agentic UI testing.
- Framework agnostic – React Native, Flutter, native iOS and Android, Ionic, and hybrid apps all use the same commands. Meta uses Maestro to test React Native itself, and Expo supports Maestro as its preferred E2E testing platform.
- Cross-platform coverage – one flow syntax for Android, iOS, and web, on emulators, simulators, browsers, and physical Android devices.
- Resilience & smart waiting – built-in flakiness tolerance and automatic waiting handle dynamic UIs without manual sleep() calls.
- Fast iteration & simple install – one install line, no drivers, no SDK, no dependencies; flows are interpreted, so there's no compilation step. First test in 5 minutes.

Simple Example:

 flow_contacts_android.yaml

appId: com.android.contacts
---
- launchApp
- tapOn: "Create new contact"
- tapOn: "First Name"
- inputText: "John"
- tapOn: "Last Name"
- inputText: "Snow"
- tapOn: "Save"


 

 Getting Started

Maestro requires Java 17 or higher to be installed on your system. You can verify your Java version by running:


java -version


Installing the CLI:

Run the following command to install Maestro on macOS, Linux or Windows (WSL):


curl -fsSL "https://get.maestro.mobile.dev" | bash


The links below will guide you through the next steps.

- Installing Maestro (includes regular Windows installation)
- Add Maestro MCP to your coding agent
- Run your first test with the Maestro CLI (or just ask your agent to do it for you)

 

 Maestro MCP