框架全解系列 · 第 7 篇（前 6 篇：Selenium / Playwright / Cypress / Espresso / Appium / XCUITest）
事实版本：Maestro CLI 2.10.0（2026-08-31 发布）｜开源、Kotlin、15.7k+ stars｜本地核心能力免费

开篇：先把 Maestro 在系列里的位置摆正

读这篇之前，先记住三个"混血"事实，它们是全文的主线：

1. 位置和 Appium 同侧：Maestro 从设备外部"驾驶"UI，不侵入 App 进程、不要求加测试依赖、不编译测试 APK——这点和 Espresso / XCUITest 完全相反。
2. 写法和 Cypress 神似：你只描述"我要做什么结果"（点"登录"、看见"欢迎"），不描述"怎么等、怎么重试"。等待、轮询、容错由框架默认接管。
3. 载体是 YAML 而不是代码：没有编译器、没有测试框架脚手架，解释执行、改完即跑，手工测试、产品、开发都能写。

一句话本质

01 Maestro 完整工作原理（结合架构图）

一句话本质：CLI 解释 YAML，通过设备无障碍/输入系统从外部"按下真实拇指"

┌──────────────────────────── Maestro CLI（单个 JVM 二进制）────────────────────────────┐
│                                                                                        │
│   Flow 解释器        执行编排引擎 Orchestrator        自动同步 Scheduler                │
│  ┌──────────┐      ┌──────────────────────┐      ┌──────────────────────────┐         │
│  │ YAML 解析│ ───▶ │ 命令 → 设备动作映射   │ ───▶ │ 每步前：等 UI 空闲/元素   │         │
│  │ 变量/条件│      │ runFlow/JS/tags 调度  │      │ 出现 settle，失败自动重试 │         │
│  └──────────┘      └──────────┬───────────┘      └─────────────┬────────────┘         │
│                              │                                 │                       │
│                     ┌────────▼─────────┐              ┌────────▼─────────┐            │
│                     │  语义选择器解析   │              │  视图树轮询/截图  │            │
│                     │ text/id/关系定位 │              │ (hierarchy dump) │            │
│                     └────────┬─────────┘              └────────┬─────────┘            │
└──────────────────────────────┼────────────────────────────────┼──────────────────────┘
                               │ 注入真实输入事件                │ 反复抓取视图树
              ┌────────────────┴───────────────┐
              ▼ Android                          ▼ iOS
   ┌────────────────────┐            ┌──────────────────────────┐
   │ adb / input 事件注入 │            │ idb / simctl 驱动模拟器   │
   │ UiAutomator 无障碍   │            │（底层复用 XCUITest 能力） │
   │ 真机 + 模拟器均支持   │            │ 本地：模拟器；真机走 Cloud │
   └────────────────────┘            └──────────────────────────┘
              ▼ Web
   ┌────────────────────────────┐
   │ 内置 Chromium / 连接浏览器 │
   └────────────────────────────┘

图注：上图从左到右是"YAML 进、设备动作出"的数据流；下方按 Android / iOS / Web 三个驱动分叉。编号 ①~⑧ 的运行时序见下表。

Maestro 在移动测试体系里的位置

关键设计取向：Maestro 主动拥抱"移动 UI 不稳定"这个前提。官方文档原话是"Maestro embraces the instability of mobile applications and devices and tries to counter it"（拥抱不稳定性并设法抵消）。这与白盒派"我和 App 同步、所以我快且稳"的思路是两条哲学。

一次点击的完整时序（图中编号 ①~⑧）

以 - tapOn: "Login" 为例，从 CLI 启动到点击落地：

④→⑥ 的"抓树—匹配—等待—再抓树"循环，就是 Maestro 自动等待和抗 flaky 的物理实现；它替代了 Appium 里你手写的 WebDriverWait 和满屏的 sleep。

Android / iOS 底层各靠什么驱动

Maestro 和 Appium 到底差在哪（同为黑盒，最容易被问）

一句话：Appium 给你最大自由度，代价是把"等待和稳定"的责任留给你；Maestro 收走自由度，把"等待和稳定"变成默认值。

02 核心语法与定位策略

Flow 文件解剖：两段式，用 --- 分隔

# ===== 配置区（--- 之上）=====
appId: com.example.app          # 必填：被测 App 的包名/BundleId
name: 登录冒烟用例               # 可选：Flow 名称
tags:                           # 可选：标签，用于筛选运行
  - smoke
  - login
env:                            # 可选：环境变量
  USERNAME: "test@example.com"
  PASSWORD: "Test@1234"
---
# ===== 命令区（--- 之下）=====
- launchApp
- tapOn: "用户名"
- inputText: ${USERNAME}
- tapOn: "密码"
- inputText: ${PASSWORD}
- tapOn: "登录"
- assertVisible: "欢迎回来"

语义选择器：tapOn 的匹配优先级

Maestro 不鼓励坐标和 XPath，优先用语义信息（这也是它抗布局变化的关键）：

- tapOn:
    text: "立即购买"
    below: "商品详情"
    retryTapIfNoChange: true

设计意图：tapOn: "Email" 命中的是"文字或无障碍标签"，因此一次改版只要按钮意思没变，脚本就不会挂；而坐标/XPath 在布局微调时立刻失效。

断言与自动等待

- assertVisible: "订单提交成功"
- assertNotVisible: "加载中"

常用命令速查表

条件、循环、子流程、参数

# 条件分支：权限弹窗出现才点
- runFlow:
    when:
      visible: "允许"
    commands:
      - tapOn: "允许"

# 循环输入多组数据（配合 env/参数）
- runFlow:
    when:
      platform: Android
    commands:
      - tapOn: "仅在安卓点的元素"

子流程复用（runFlow 引用文件）：

- runFlow: login.yaml
- runFlow:
    file: add_to_cart.yaml
    env:
      PRODUCT: "矿泉水"

命令行注入参数（双端不同 appId 的常用做法）：

maestro test -e APP_ID=com.example.android flow.yaml
maestro test --env APP_ID=com.example.ios flow.yaml

appId: ${APP_ID}
---
- launchApp

JS 兜底：YAML 不够用时的逃生口

- evalScript: { script: "output.dynamicText = '总价 ' + (2 * 3) + ' 元'" }
- assertVisible: "${output.dynamicText}"

经验：90% 的移动端场景 YAML 足够；只有复杂计算、动态字符串、特殊数据构造才请 JS 出场。这和 Appium"一切皆代码"形成鲜明对比。

03 完整实战：YAML 走通"登录 → 浏览商品 → 加购 → 下单断言"

Step 1：工程准备（一次性）

Step 2：主流程 + 可复用子流程

flows/login.yaml（登录子流程，带参数）：

appId: ${APP_ID}
---
- tapOn: "用户名"
- inputText: ${USER}
- tapOn: "密码"
- inputText: ${PASS}
- tapOn: "登录"
- assertVisible: "首页"

flows/smoke_order.yaml（主流程：组合 + 业务动作）：

appId: ${APP_ID}
name: 下单冒烟全链路
tags:
  - smoke
env:
  USER: "test@example.com"
  PASS: "Test@1234"
---
- launchApp:
    clearState: true            # 干净起步，避免缓存导致 flaky

- runFlow:                       # 复用登录
    file: login.yaml
    env:
      APP_ID: ${APP_ID}
      USER: ${USER}
      PASS: ${PASS}

- tapOn: "搜索"
- inputText: "矿泉水"
- pressKey: Enter
- scrollUntilVisible:            # 滚到目标商品
    element: "天然矿泉水 550ml"
    direction: DOWN
- tapOn: "天然矿泉水 550ml"
- assertVisible: "商品详情"
- tapOn: "加入购物车"

- runFlow:                       # 可能的加购弹窗，条件点掉
    when:
      visible: "继续购物"
    commands:
      - tapOn: "去结算"

- tapOn: "购物车"
- tapOn: "去结算"
- assertVisible: "确认订单"
- tapOn: "提交订单"
- assertVisible: "订单提交成功"
- screenshot: order_success

运行：

maestro test --format junit -e APP_ID=com.shop.android flows/smoke_order.yaml

场景延伸 1：跨 App / 系统设置（Maestro 的强项）

白盒框架最头疼的"操作设备本身"，在 Maestro 里就是普通命令：

- toggleAirplaneMode
- toggleWifi
- tapOn: "飞行模式"            # 直接操作系统设置页
- openLink: "shop://product/123"   # 深链拉起

场景延伸 2：WebView 混合页与 Web

url: https://example.com
---
- launchApp
- tapOn: "More information..."
- assertVisible: "Further Reading"

场景延伸 3：复杂列表与滚动

- scrollUntilVisible:
    element: "已到底部"
    direction: DOWN
    timeout: 20000
    visibility: 90%        # 元素可见比例达到才算命中

场景延伸 4：CI 集成（GitHub Actions 示例）

name: Maestro E2E
on: [push]
jobs:
  android-e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install & run
        uses: mobile-dev-inc/action-maestro-cloud@v1
        with:
          api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}
          app-file: app/build/outputs/apk/debug/app-debug.apk
          flow-file: flows

AI 时代的玩法：让 AI 写并运行 Flow

Maestro CLI 内置了一个 MCP Server，AI 编程助手可以直接操作真实设备：

claude mcp add maestro -- maestro mcp

支持 Claude Code、Cursor、Copilot、Gemini 等。典型用法：你说"登录、把巴黎加入收藏、重启后确认还在"，AI 写 Flow、真机执行、选择器失效时自己 inspect 后修正。Maestro Studio 内也有 AI 辅助（MaestroGPT）。

04 环境搭建与版本演进

环境清单（本地最容易翻车的几样）

CLI 安装

# macOS / Linux
curl -Ls "https://get.maestro.mobile.dev" | bash

# 升级
maestro upgrade

Studio / Viewer / Cloud 三件套

版本演进与商业模式

数据来自 Maestro 官方 benchmark / insights 页面，引用时建议标注"官方口径"。

05 稳定性治理：自动抗 flaky 的能力边界

自动等待是 Maestro 的招牌，但它不是万能。这一章讲清楚边界，避免"以为写了 YAML 就不会 flaky"。

1. 自动同步的边界

2. 语义定位 vs XPath/坐标

3. 重试与超时配置

- tapOn:
    text: "提交"
    retryTapIfNoChange: true   # 点击后界面没变则重试
    timeout: 10000
- extendTimeout: 30000          # 单步延长超时

4. 用 clearState 做隔离

- launchApp:
    clearState: true      # 等同 adb shell pm clear，给"首次安装"状态

5. iOS 物理机限制（必须提前知道）

如果团队强依赖"本地插真机调试 iOS"，这条限制要在选型时就摆上桌。

6. 常见坑速查

06 优势与劣势

优势

劣势

07 选型建议：什么项目该用 Maestro

决策表

系列 7 框架总选型表

表外补充：Detox 专做 React Native（iOS/Android、灰盒、JS/TS），状态同步更贴合 RN，RN 重度团队可单独评估，不属于本系列 7 篇主线。

一句话结论

Maestro 的本质不是"更简单的 Appium"，而是把"等待、重试、同步"这些本该由框架负责的事从测试者手里收回去——你只负责描述意图，剩下的交给它。 在 AI 写测试成为常态的 2026 年，这种"声明意图 + 机器执行"的形态，反而比"人写命令式代码"更顺。

参考资料