Maestro README

The project's README from github.com/mobile-dev-inc/Maestro. As one markdown file: README.md.

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

Maestro logo

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.

A Maestro flow in plain YAML running on the Twitch Android app in an emulator

 

Table of Contents

 

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.

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.

 

Maestro MCP – Agentic UI Testing

A coding agent checking its work on an Android emulator through Maestro MCP, with every command shown live in the Maestro Viewer

Maestro MCP ships inside the Maestro CLI and works with Claude Code, Cursor, Codex, Gemini CLI, Copilot, Grok Build, or any MCP client. It gives your agent a live device (an emulator, simulator, or physical Android device), and Maestro Viewer embeds that device inside your coding agent, showing every MCP command as it runs.

With Maestro MCP, your agent can control the app directly: inspect the screen, tap, scroll, and assert. While it builds or changes a feature, it checks its own work on the device.

Your agent can also write tests. Ask for an end-to-end flow and it writes plain YAML, runs it until it passes, and the flow stays in your repo as a deterministic test for CI.

Setup for each coding agent is in the Maestro MCP docs.

 

Maestro Studio – Test IDE

Maestro Studio Desktop is a lightweight IDE that lets you design and execute tests visually — no terminal needed. It is also free, even though Studio is not an open-source project. So you won't find the Maestro Studio code here.

Download Maestro Studio

 

Maestro Cloud – Parallel Execution & Scalability

When your test suite grows, run hundreds of tests in parallel on dedicated infrastructure, cutting execution times by up to 90%. Includes built-in notifications, deterministic environments, and complete debugging tools.

Pricing for Maestro Cloud is completely transparent and can be found on the pricing page.

👉 Start your free 7-day trial

 

Resources & Community

 

Contributing

Maestro is open-source under the Apache 2.0 license — contributions are welcome!

If you find Maestro useful, ⭐ star the repository to support the project.

  Built with ❤️ by Maestro.dev

Maestro (mobile-dev-inc/Maestro)

Searching Database…

16.1K ·GitHub
Maestro
这是做什么用的?Maestro 是一个开源框架,用于对 Android、iOS 和 Web 应用做 UI 测试和端到端测试。你可以用简单的 YAML 命令来描述测试流程,在命令行里运行,在 Maestro Studio 里可视化搭建,或者让 AI 编程助手通过 MCP 来驱动它们。
它和 Appium、Selenium 这类工具有什么不同?它吸收了前代工具的经验教训:Maestro 通过系统自带的辅助功能层来驱动应用,只安装一个单独的可执行文件,不需要驱动或 SDK,并且每个测试都是一段平铺的 YAML 命令,直接解释执行——没有编译这一步。
我该怎么写第一个测试?在 macOS、Linux 或 Windows (WSL) 上用一行命令安装 CLI(文档里也介绍了 Windows 的常规安装方式),然后手写一个 YAML 流程。README 说第一个测试五分钟内就能搞定。
除了 Maestro 本身,我还需要装什么?只需要 Java 17 或更高版本。没有驱动、SDK 或其他依赖——所有东西都打包在这一个 CLI 文件里。
所有带 Maestro 名字的东西都是开源的吗?不是。这个框架基于 Apache 2.0 协议开源,但 Maestro Studio Desktop 虽然免费却不开放源码(它的代码不在这个仓库里),Maestro Cloud 则是付费服务。
我的 React Native 或 Flutter 应用能用它吗?可以——它对框架没有要求:React Native、Flutter、原生 iOS 和 Android、Ionic 以及混合应用用的都是同一套命令。Meta 自己就用 Maestro 来测试 React Native,Expo 也把它作为首选的 E2E 测试平台。
我的流程实际能跑在什么上面?任何模拟器、浏览器,或者真实的 Android 设备——一套流程语法同时覆盖 Android、iOS 和 Web。
Claude Code 这类 AI 编程助手能用 Maestro 吗?可以。CLI 里自带 Maestro MCP——运行 'maestro mcp' 就行,不用再装别的——并且支持 Claude Code、Cursor、Codex、Gemini CLI、Copilot、Grok Build 或任何 MCP 客户端。AI 助手会得到一台可以实时查看、点击、滚动和断言的设备,还能编写 YAML 流程,把它们留在你的仓库里,作为 CI 的确定性测试。
遇到加载慢或有动画的页面,我需要自己加等待吗?不需要——Maestro 内置了容错机制和自动等待,动态界面不用手动写 sleep() 调用就能处理。
不用命令行也能搭建测试吗?可以——Maestro Studio Desktop 是一个免费的轻量 IDE,支持 macOS、Windows 和 Linux,你可以在里面录制操作、查看元素、可视化地搭建流程。
测试套件变得很大之后会怎样?Maestro Cloud 可以在专用基础设施上并行运行数百个测试,把执行时间最多缩短 90%,还自带通知和调试工具。它是付费服务,提供 7 天免费试用。
What are similar projects?agent-device, e2e, Detox, playwright, midscene, appium, agentic-playwright, NativeScript
Which topics is it in?ui-automation, e2e-testing, testing-tools, flutter, yaml, react-native, kotlin, ci, testing, java, mobile, ios
Creator
mobile-dev-inc
Size
1 GB
Stars
16.1K
Updated
CommitOct 16Releasecli-2.11.0Sep 29
Age
4y
Commits · 90 Days