一份 YAML 脚本跑通 Android、iOS 与 Web：Maestro UI 自动化测试快速上手指南-育师

一份 YAML 脚本跑通 Android、iOS 与 Web：Maestro UI 自动化测试快速上手指南

【免费下载链接】MaestroPainless E2E Automation for Mobile and Web项目地址: https://gitcode.com/GitHub_Trending/ma/Maestro

如果你同时在维护 Android、iOS 和 Web 三套 UI 测试，多半体会过"同一行断言要抄三遍、一个定位符改动全线崩"的滋味。Maestro 是一个用 YAML 脚本驱动的 UI 自动化测试框架，让同一份 flow 能在模拟器、真机和浏览器里直接跑起来。这篇文章按我实际落地的过程，从装环境到写脚本、从登录演练到排错，尽量给你能照做的步骤，而不是一堆概念名词。

一个改了三遍的登录用例，让我重新看待跨平台测试

去年我们有个电商 App，登录页的"记住密码"复选框偶尔加载慢，点一下就报"元素未找到"。为了压住它，我在三个平台各塞了一堆 sleep：Android 用 Espresso 的 wait、iOS 用 XCTest 的 polling、Web 又回到 Selenium 的 WebDriverWait。三套代码三套等待逻辑，复选框一改版，三处都要动。更麻烦的是，三个平台的定位策略还不一样——Android 认 resource-id、iOS 认 accessibility label、Web 认 CSS 选择器，同一个"登录"按钮我记着三套写法。那种感觉不是"写测试"，是"维护三份翻译稿"。真正卡住效率的，不是写第一条用例，而是第 N 条改动时，你不知道还要同步改几处。

Maestro 是什么：一份 flow，三端复用

Maestro 的思路很克制：把一次 UI 交互写成一行 YAML 命令（launchApp、tapOn、inputText、assertVisible），交给解释器直接执行，不用编译。它不替代底层，而是在 Android、iOS、Web 之上做统一抽象——你写"点击文本为登录的元素"，它负责在各端去匹配对应的控件。等待也是内置的：断言和交互会反复轮询直到元素就绪或超时，所以大多数动态页面不用再手写 sleep。对 Flutter、React Native 这类跨端框架尤其友好，因为它们的控件文本在两端本就一致。

五分钟跑通第一个测试：安装与最小脚本

环境只要一个前置：Java 17 或更高，先java -version确认。安装本身是一条命令，macOS、Linux、Windows（WSL）通用：

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

装完就能跑。我的习惯是先拿一个系统自带的 App 当练手，不依赖自己项目的构建。下面这份最小脚本用 Android 的联系人 App，七行就能验证"点、填、断"是否都通：

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

保存到flow.yaml，然后maestro test flow.yaml。看到流程跑完、断言通过，就说明 CLI、设备、元素匹配这条链路是通的。仓库里 e2e/workspaces/web/ 下还有一批现成的样例 flow 可以直接拿来试，适合你还没写好第一条用例时先照着跑。

三种 YAML 写法：点、等、算

跑通最小脚本后，真正常用的其实是三类写法，各给个短例。

基础交互就是上面那份最小脚本的形态：tapOn按文本（或id:）定位，inputText填进当前焦点框，assertVisible确认出现。定位尽量用用户能看到的文本，而不是内部控件树，这样 UI 迭代时更抗变更。

条件分支用来对付"有时出现、有时不出现"的元素，比如验证码。注意optional: true可以让某一步找不到时不报错：

- if: visible: "验证码" then: - inputText: "123456" else: - tapOn: "跳过"

数据处理解决"每次要一个不同的值"这类需求。Maestro 允许用runScript跑一段脚本，再把结果通过${output.xxx}注入后续步骤，随机邮箱、动态查询词都这么来：

- runScript: scripts/getQuery.js - inputText: ${output.result} - assertVisible: ${output.result}

把登录的正反流程串成一条线

理解了上面三种写法，就能把一条完整的登录链路写下来。正常流程从清状态启动开始，逐项填账号密码，最后断言首页元素，一共不到十行：

appId: com.example.ecommerce --- - launchApp: clearState: true - tapOn: "我的账户" - tapOn: Username - inputText: standard_user - tapOn: Password - inputText: secret_sauce - tapOn: "登录" - assertVisible: "我的订单"

异常流程复用同一段头部，只改账号和最后的断言——这也是"同一份逻辑三端复用"最省事的地方，改动集中在几行：

- tapOn: Username - inputText: locked_out_user - tapOn: "登录" - assertVisible: "您的账户已被锁定"

两段可以拆成两个 flow 文件、用标签区分positive/negative，也可以放进同一个 flow 里顺序执行。我一般拆文件，因为一个失败不该连累另一个的结果统计。

跑不通时，先查这三处

流程报"Element not found"别急着加 sleep，我按这个顺序排查命中率最高：

设备到底连没连上。先maestro list-devices，确认 CLI 看得见目标设备或模拟器；Web 端则要确认页面服务已经起好，否则launchApp会对一个无效端口"成功"，报错却指向无关的元素。
你写的文本和界面真实节点对得上吗。用maestro print-hierarchy把当前视图树打出来，逐字核对你要点的文本、id:是否一致——大小写和全角空格是最常见的坑。
YAML 本身或超时问题。maestro check-syntax flow.yaml先排除语法；确认是"还没加载出来"再加timeout，而不是无限等待。仓库里这些子命令的实现都能在 maestro-cli/src/main/java/maestro/cli/command/ 下对照，排错时能帮你确认参数名没写错。

实在看不出来，maestro record会带你可视化地走一遍，你"看到"的控件就是它要匹配的控件，比对着报错猜要快得多。