Maestro移动UI自动化测试：3分钟从零跑通第一条YAML流程

Maestro移动UI自动化测试：3分钟从零跑通第一条YAML流程

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

当你想验证 App 里"点按钮→出结果"这条链路，通常要先配好真机、写测试代码、再盯着日志看结果。Maestro 把这件事压缩成一段 YAML：几行命令描述操作，它替你执行并逐步给出判定。

它到底能帮你做什么

用YAML命令替代测试代码

场景：每次发版前都要重复"登录→下单→返回"这套操作。 做法：写一个.yaml文件，每行一个动作，比如launchApp启动应用、tapOn: "搜索"点击按钮、assertVisible: "购物车"断言页面出现某文本。 效果：文件不需要编译，改完直接maestro test重跑，几秒内重新执行，迭代远快于写单元测试。

自动等待替代sleep

场景：页面有网络加载，固定sleep要么浪费时间要么赶不上加载。 做法：assertVisible这类命令会持续轮询，元素出现即通过，超时才判失败（默认等待上限可调）。 效果：网络波动导致的偶发失败大幅减少，同一脚本在不同速度的设备上都能稳定跑。

一套脚本覆盖Android、iOS和Web

场景：同一个功能要分别测 Android 和 iOS 版本。 做法：命令语法相同，换掉文件头的appId或url即可；仓库里 e2e/workspaces/web/ 和 e2e/workspaces/wikipedia/ 目录放了现成样例，可以直接抄结构。 效果：一份流程逻辑维护两个平台，不用各学一套 API。

快速上手

📦 环境要求一句话：系统装有 Java 17 及以上（java -version检查），其余靠下面的命令装。

git clone https://gitcode.com/GitHub_Trending/ma/maestro cd maestro ./gradlew :maestro-cli:installDist

构建完成后，CLI 产物在maestro-cli/build/install/maestro/bin/下。把它加进 PATH，终端里敲maestro --version能看到版本号，就说明安装成功。不想自己构建的话，仓库自带 scripts/install.sh 也提供了一键安装。

跟着一个真实任务走一遍

🎬 我们用仓库里的 Web 登录样例（参考 e2e/workspaces/web/simple.yaml）走一遍完整流程。任务：用账号密码登录测试站点，确认商品页出现。

第一步，建一个login.yaml，内容如下：

- launchApp - tapOn: Username - inputText: standard_user - tapOn: Login - assertVisible: Products

第二步，执行maestro test login.yaml。终端会逐行打印每一步的结果：

• 看到每行命令后跟着绿色PASS，说明该步成功；
• 最后输出FLOW PASSED即整条流程通过；
• 若某步失败，该行标红，并自动截图存到项目下.maestro/screenshots/目录，仓库里 e2e/demo_app/.maestro/screenshots/ 就留着这类断言失败的截图，点进去看"失败时画面长什么样"很直观。

逐条理解这五行：

第三步，把验证做严一点。把最后一行换成两条断言：assertVisible: Products和assertNotVisible: Login（登录框应已消失）。两条都过，才算真正跳转成功。

进阶技巧与避坑

💡点击可能"静默失败"。现象：tapOn没报错，但页面根本没跳转，流程卡住。做法：包一层retry重试，再跟一条assertNotVisible确认旧元素已消失。仓库里 e2e/workspaces/simple_web_view/webview.yaml 就是这个写法，注释里还解释了"tap 可能被加载中的 runner 吞掉"的根因。

💡别手写 sleep，用extendedWaitUntil显式等待。现象：某个页面特别慢，默认超时不够。做法：用extendedWaitUntil指定"等哪个元素可见 + 自定义超时"，例如该样例文件里的timeout: 90000。判断成功的标志是输出里出现你写的label文案，失败时会给出"等待超时"而不是笼统的报错。

💡文本重名时改用更精确的选择器。现象：页面有两个"取消"按钮，tapOn: "取消"点到第一个就停了。做法：在 flow 里给tapOn加条件（如按id定位），或组合多个条件缩小范围；也可以传正则表达式做模糊匹配，比如assertVisible: '.*sleek.*'能匹配任意含 "sleek" 的行。

💡公共步骤抽成子流程。现象：每个流程开头都要重复"清状态→启动→过引导页"。做法：把这段单独存成一个 yaml，用subFlow引用。e2e/workspaces/wikipedia/subflows/ 里就分平台存了launch-clearstate-android.yaml这类复用片段。

常见问题

Q：断言失败，怎么定位是哪一步、当时屏幕是什么样？看终端输出定位到标红的那一行；同一时刻的截图在项目根目录.maestro/screenshots/下，失败时一定会生成，直接打开对照即可。

Q：改了一行 YAML，需要重新编译什么吗？不需要。flow 是解释执行的，保存后重新maestro test即可，这也是它比"先编译测试再跑"的框架快的原因。

Q：Android 和 Web 的 flow 有什么差别？只有头部不同：Android/iOS 写appId: com.android.contacts，Web 写url:。命令本体（tapOn、inputText、断言）完全一致。

Q：终端提示 java 相关错误？先跑java -version。低于 17 会导致 CLI 构建或运行失败，升级到 17 或 21 再执行安装脚本即可。

写在最后

Maestro 适合需要"少写代码、多跑回归"的移动端和 Web 团队，以及想先建立 E2E 测试习惯的新手。下一步建议直接打开 e2e/workspaces/ 目录，挑一个最接近你业务的样例改造成自己的第一条正式流程。

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