Maestro移动UI自动化完整指南：五分钟内跑通第一个E2E流程
【免费下载链接】MaestroPainless E2E Automation for Mobile and Web项目地址: https://gitcode.com/GitHub_Trending/ma/Maestro
Maestro 是一个开源移动UI自动化测试框架，覆盖 Android、iOS 和 Web 三个平台。测试写成 YAML 流程文件，用一条命令在模拟器、真机或浏览器上执行。本文从安装、写流程到接入 CI，给出可以直接复制执行的步骤。
🎯 Maestro移动UI自动化解决什么场景
多端应用的 E2E 测试过去通常要维护三套代码：Android 用 Espresso，iOS 用 XCTest，Web 用 Selenium。同一场景要写三遍，还要处理等待和重试。
Maestro 的思路是只用一套 YAML 语法描述流程，执行引擎按平台分发。Android 端由 maestro-client/ 里的驱动实现接管，Web 端基于 Selenium（项目锁定 4.43.0 版本）。
另一个痛点是测试不稳定。动态 UI 里手动sleep()既慢又不可靠。Maestro 的每条命令自带等待逻辑，元素没出现会按超时重试，而不是立即报错。
⚡ 三步完成Maestro安装与首次运行
第一步，确认环境并安装 CLI。Maestro 要求 Java 17 或更高版本：
java -version curl -fsSL "https://get.maestro.mobile.dev" | bashmacOS、Linux、Windows WSL 都用这一条命令。装完后maestro --version能输出版本号即成功。
第二步，写一个最小流程文件flow_contacts_android.yaml，测试系统联系人应用新建联系人：
appId: com.android.contacts --- - launchApp - tapOn: "Create new contact" - tapOn: "First Name" - inputText: "John" - tapOn: "Save"第三步，启动一个装了联系人应用的 Android 模拟器，执行：
maestro test flow_contacts_android.yaml终端逐行打印每条命令的执行结果，全部通过则退出码为 0。这就是一个可验证的起点：流程跑通，退出码为 0。
⚙️ Maestro YAML流程核心机制速览
元素定位：text、id 与 optional 容错
每条命令通过选择器找元素，支持text、id、index等字段组合。找不到的元素默认失败，标记optional: true则跳过。仓库里的 e2e/workspaces/wikipedia/onboarding-android.yaml 就混合用了两种定位：
- tapOn: id: "org.wikipedia:id/fragment_onboarding_forward_button" - tapOn: text: "Non existent view" optional: trueid定位不受界面语言影响，跨环境更稳定；optional用于处理版本间可能不存在的视图。
子流程、脚本与环境变量
长流程用runFlow拆成子文件复用，runScript执行 JS 生成动态数据，${...}注入环境变量或脚本输出。官方样本 e2e/workspaces/wikipedia/android-advanced-flow.yaml 的结构如下：
- runFlow: subflows/onboarding-android.yaml - runScript: scripts/getSearchQuery.js - inputText: ${output.result} - launchApp: clearState: truerunFlow把引导页操作收进subflows/目录，主流程保持可读；clearState: true重启应用并清空状态，保证每次执行从初始界面开始。命令模型定义在 maestro-orchestra-models/src/main/java/maestro/orchestra/MaestroCommand.kt，想确认某条命令的字段时查这里即可。
📱 两个真实场景：跑通搜索流程与Web登录流程
场景一：Android 端 Wikipedia 搜索
背景：需要验证搜索框输入到结果展示的完整链路，且搜索词每次要不同。
操作：使用上面提到的 advanced flow。它先runFlow走引导页，再点search_container，通过runScript生成随机搜索词，inputText输入后assertVisible断言该词出现在结果页。
结果：整个流程带android和passing标签，在 e2e 套件中按通过用例断言执行，每次运行搜索词不同但断言逻辑不变。
场景二：Web 端 saucedemo 登录
背景：同一个团队还要测 Web 应用，希望不换语法。
操作：Web 流程把appId换成url字段，其余命令完全一致。样本 e2e/workspaces/web/simple.yaml 登录 saucedemo，断言商品列表可见后点进商品页。本地运行前先起静态服务：
e2e/ensure_fixtures maestro --platform web test e2e/workspaces/web/simple.yaml结果：ensure_fixtures在 7357 端口启动 fixture 服务并等待其真正应答，避免流程在服务器未就绪时以"元素未找到"报错。CI 环境加--headless参数即可无头运行。
📁 仓库关键目录对照表
| 目录路径 | 一句话职责 |
|---|---|
| maestro-cli/ | CLI 入口，test、report等命令与 MCP 实现 |
| maestro-orchestra/ | 流程解析与执行引擎，YAML 到设备操作的调度 |
| maestro-orchestra-models/ | 命令、选择器、配置等 YAML 模型定义 |
| maestro-client/ | 驱动层，Android、iOS、Web 三端设备通信 |
| e2e/workspaces/ | 官方样本流程：wikipedia、web、simple_web_view |
| e2e/ | 框架自测脚本，run_tests按平台分跑全部用例 |
框架本身用 Kotlin 2.2.0 构建，模块依赖统一在 gradle/libs.versions.toml 中声明。
🔁 把Maestro移动UI自动化接入CI流水线
最小接入方式是 GitHub Actions 三步：检出代码、装 CLI、跑流程。退出码决定构建成败，failing标签的反向断言由 e2e 脚本 e2e/run_tests 处理，保证"该失败的用例通过"也会被识别为故障：
name: Maestro Tests on: [push] jobs: e2e: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Install Maestro run: curl -fsSL "https://get.maestro.mobile.dev" | bash - name: Run flows run: maestro test ./tests/本地想跑框架自带的全套 e2e，按 e2e/README.md 的顺序执行download_apps、install_apps、run_tests <android|ios|web>即可。
✅ 从这里开始：三条可立即执行的动作
- 装好并验证：执行安装命令，用
maestro test跑通一个 5 行流程，确认退出码为 0 - 读一遍样本：对照 e2e/workspaces/ 里的 wikipedia 和 web 两组流程，弄清
runFlow、optional、${...}三种写法 - 接入构建：把上面 11 行的 Actions 配置放进你的仓库，先让一条登录流程在 CI 里稳定跑绿
【免费下载链接】MaestroPainless E2E Automation for Mobile and Web项目地址: https://gitcode.com/GitHub_Trending/ma/Maestro
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
