一、项目速览

入门 · 1 分钟版

Maestro 是一个用 YAML 写流程、跨 Android / iOS / Web 跑端到端测试的开源框架。它的核心卖点是「像写清单一样写测试」——把点击、滑动、断言写成声明式指令，由解释器逐行执行，省去编译、真机调试、手写 sleep 那一堆麻烦。

如果你正在维护 React Native / Flutter / 原生 App，需要一种比 Appium 更轻、比 Espresso/XCTest 更通用的方案，Maestro 是当前值得花一小时评估的选项。下面 4 个特点决定它值不值得上手。

• 跨平台：一份 YAML 流程能在 Android、iOS、Web 三端复用，覆盖 React Native、Flutter、混合应用
• YAML 声明式：tapOn、assertVisible 等指令可读性接近自然语言，QA 也能 review
• 自动等待：内置 flaky tolerance，动态 UI 不再需要手写 sleep
• 解释执行：流程文件改完即跑，0 编译时间，反馈链极短

作者视角：如果团队里有不会写 Kotlin / Swift 的测试同学，Maestro 的低门槛是关键卖点；反过来，如果已经在 Appium + WebdriverIO 上跑得稳，迁移收益并不明显。

二、核心功能与架构

进阶 · 推荐细读

Maestro 的架构分三层：YAML 流程（人写）→ CLI 解释器（执行）→ 设备驱动（Android 用 UiAutomator、iOS 用 XCUITest 桥、Web 用 Playwright）。先理解这个分层，后面写流才不会踩坑。

YAML 流程：声明式操作清单

它是什么：一份 .yaml 文件，按顺序罗列 launchApp、tapOn、inputText、assertVisible 等指令。它解决什么问题：把测试代码从「脚本」降级到「清单」，QA、产品都能直接 review 和改。谁最该用：维护大型测试集、需要在 PR 里直接 diff 测试逻辑的团队。

appId: com.example.app
---
- launchApp
- tapOn: "登录"
- inputText: "alice"
- assertVisible: "首页"

跨平台驱动：同一份 YAML 多端跑

它是什么：底层对 Android 调用 UiAutomator，对 iOS 调用 XCUITest 的桥，对 Web 调用 Playwright。它解决什么问题：避免 Android 工程师写一套 Espresso、iOS 工程师写一套 XCUITest 的重复劳动。谁最该用：同时维护两端原生或 RN / Flutter 应用的中小团队。

自动等待与稳定性

它是什么：每个 tapOn、assertVisible 默认带 timeout，期间不断轮询元素，直到出现或超时才失败。它解决什么问题：告别「点了没反应就 fail」的 flaky 测试，CI 红绿不再是薛定谔。谁最该用：动态加载、动画多的应用；以及所有被 CI 红色搞得没信心的团队。

解释器架构：改完即跑

它是什么：CLI 启动后按行读 YAML，不编译成字节码，直接驱动设备执行。它解决什么问题：流程改动后 0 编译时间，本地迭代速度提升一个量级。谁最该用：本地频繁调测、追求反馈速度的开发者。

三、动手实践

入门 · 1 分钟版

下面这 5 步可以让你在 10 分钟内跑通第一个跨平台流程。先准备一台已启用的 Android 模拟器或 iOS 模拟器，否则后面会卡在设备识别上。

环境准备

# 1. 确认 Java 17+
java -version

# 2. 安装 Maestro CLI（macOS / Linux / WSL）
curl -fsSL "https://get.maestro.mobile.dev" | bash

# 3. 验证安装
maestro --version

# 4. 启动一台模拟器（Android 示例）
emulator -avd Pixel_7_API_34 &

# 5. 确认设备可见
maestro device list

最小可运行示例

新建 hello.yaml：

appId: com.android.settings
---
- launchApp
- tapOn: "Network & internet"
- assertVisible: "Internet"

跑起来：

maestro test hello.yaml

把 appId 换成你机器上真实装着的应用包名（用 adb shell pm list packages | grep xxx 查），流程就改跑你的 App。把 assertVisible 后面改成你界面上的某个按钮文字，立刻能看到「点 → 验」链路闭环。

常见踩坑

1. 模拟器没启动就先跑测试：maestro test 不会自动启模拟器，要么提前启好，要么在 YAML 头部显式写 - launchApp。
2. 元素文字带换行或 emoji：tapOn: "Sign in" 没问题，但按钮如果是 Sign\nin，需要换成 selector：tapOn: { text: "Sign in" }。
3. iOS 真机首次连接失败：Maestro 需要 libimobiledevice，macOS 用 brew install libimobiledevice；Windows 的 WSL 默认不行，必须用 macOS 或 Linux 物理机。

一句话判断：如果上面的 hello.yaml 第一次跑就过，说明环境已就绪。任何失败先看 ~/.maestro/tests/ 下的截图，比读日志快得多。

四、进阶玩法

深入 · 老手可选

跑通单流程只是开始。下面 3 个用法能让 Maestro 在 CI 里真正干活，从「能跑」升级到「跑得稳、跑得快

项目信息

参考链接

• GitHub 仓库
• 项目主页