Maestro 端到端自动化实战指南：从第一行 YAML 到团队级工程化
【免费下载链接】MaestroPainless E2E Automation for Mobile and Web项目地址: https://gitcode.com/GitHub_Trending/ma/Maestro
Maestro 是一款面向移动端和 Web 的端到端（E2E）自动化测试框架，用类人可读的 YAML 描述操作流程，就能在 Android 模拟器、iOS 模拟器和浏览器上跑起来——官方承诺 5 分钟内写出第一个测试。这篇文章不按"新手/高手"分级，而是沿着"单个命令 → 组合工作流 → 团队级工程化"三个层次递进，每一层给出可直接照做的最小示例和仓库内的真实参照。
一、第一层：单命令——先搞懂基础交互词汇
1.1 装好环境并验证
Maestro 依赖 Java 17 以上，先运行java -version确认版本，然后用仓库自带的安装脚本完成部署：
git clone https://gitcode.com/GitHub_Trending/ma/maestro cd maestro ./scripts/install.sh装完执行maestro --version，能打印版本号就说明 CLI 可用。对应脚本就在 scripts/install.sh。
1.2 六个高频命令覆盖 80% 场景
你日常写流程，绝大多数行都是下面这几个动词：
launchApp：拉起被测应用（可带包名）tapOn：按可见文本点击元素inputText：向当前聚焦的输入框写入文本pressKey：模拟物理按键，如 Enter、BackassertVisible/assertNotVisible：断言元素出现与否scrollTo：滚动列表直到目标可见
一个关键设计值得单独说：所有命令都内建智能等待。你不需要写sleep或手动轮询——assertVisible: "Welcome"会自己等元素出现直到超时，这是 Maestro 相对 Appium 时代手搓等待的一大减负。
二、第二层：组合工作流——把命令拼成一条完整链路
2.1 最小可用用例：登录并断言结果
一个完整的 flow 就是"头部元信息 + 命令序列"。以仓库里 Web 示例 simple.yaml 的逻辑为例，移动端写法如下：
appId: com.example.shop --- - launchApp - tapOn: "登录" - inputText: "user@example.com" - tapOn: "密码" - inputText: "123456" - tapOn: "确定" - assertVisible: "商品列表"它做的事：启动应用、走完登录表单、断言进入主页面。用maestro test flow.yaml即可执行，失败时会截图并指出是哪一步、哪个元素没找到。
2.2 让流程"有脾气"：条件、重试与脚本
真实应用不是静态的：Android 和 iOS 的弹窗文案不同、网络偶发变慢。三个手段对应三种情况：
- 条件执行：命令支持
when条件，可判断platform、环境变量，不同系统走不同分支 - 重试：
retry包住不稳定的步骤，失败后自动再来一次 - runScript：内嵌 JavaScript 做动态计算，比如根据当前时间拼接一个必然唯一的用户名，避免用例互相污染
2.3 用 runFlow 消灭重复代码
"登录"几乎每条用例都要写一遍。把它抽成独立文件，主流程用runFlow引入并传变量：
- runFlow: file: common/login.yaml variables: username: "testuser" password: "testpass"这一步是"写用例"和"工程化用例库"的分水岭——仓库自己的 Wikipedia 示例 就是这么组织的：主流程负责业务断言，subflows/里放"启动并清状态""新手引导跳过"这类公共步骤，按 Android / iOS 各一份。
三、第三层：团队级工程化——跨平台、Web 与 AI 协同
3.1 一套用例，双端运行
跨平台策略的核心不是"写两套"，而是"共用一套，差异处用条件分流"。典型做法：
- runFlow: file: onboarding-android.yaml when: platform: android - runFlow: file: onboarding-ios.yaml when: platform: ios把启动、清状态、引导页这些平台强相关的步骤封装进 subflow，主流程保持干净。仓库 e2e/workspaces/wikipedia/ 下的android-flow.yaml、ios-flow.yaml及其subflows/目录就是一个完整参照。
3.2 同一套引擎跑 Web
Maestro 的驱动层不挑平台：把头部从appId换成url，同样的tapOn/inputText/assertVisible直接作用于浏览器页面。e2e/workspaces/web/ 里的示例覆盖了日期输入、iframe 同源/跨域、SPA 路由跳转等场景，iframe_cross_origin.yaml值得重点读——它展示了 Web 端元素定位和移动端的细微差别。
3.3 让 AI 直接操作设备：MCP Server
Maestro CLI 内置了 MCP（Model Context Protocol）服务，一条maestro mcp启动后，LLM 就能把"点某个按钮""跑某个 flow 目录"当成工具来调用——既能直接操控设备，也能代写、校验并执行 flow 代码。这意味着你可以把"根据这版 UI 变更帮我更新登录用例"交给模型完成，人只负责 review。实现细节见 MCP 模块，其中 README 还说明了如何扩展新工具。
四、任务清单：对照检查你到了哪一层
| 能力层 | 你应该能独立完成 | 仓库内参照 |
|---|---|---|
| 单命令 | 安装 CLI，对任意外卖/联系人 App 写一条含 5 个命令的线性 flow 并跑通 | install.sh |
| 组合工作流 | 把登录抽成带变量的 subflow；用 retry 处理一个偶发失败步骤；用 when 区分一次平台差异 | Wikipedia 示例集 |
| 团队级工程化 | 同一业务在 Android / iOS / Web 三端各有一条可运行 flow；flow 接入 CI 定时执行；能用 MCP 让模型代写一条 flow | Web 示例集、e2e 说明 |
三层之间没有严格门槛，但有个实用建议：卡在"用例写了一堆、改一处要动十个文件"时，说明你该进入第二层的 runFlow 练习了；"双端各维护一份、漂移严重"时，说明该学第三层的平台分流了。
延伸阅读可以从 e2e/workspaces/ 开始，每个 yaml 都很短，是学语法最快的材料；再看 e2e/README.md 了解仓库自身如何用 Maestro 测试 Maestro——自己吃自己的狗粮，往往是能力边界最诚实的展示。
【免费下载链接】MaestroPainless E2E Automation for Mobile and Web项目地址: https://gitcode.com/GitHub_Trending/ma/Maestro
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
