Maestro 移动 UI 自动化测试入门指南：从 YAML 流程到 AI 断言-平芜编程栈

Maestro 移动 UI 自动化测试入门指南：从 YAML 流程到 AI 断言

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

Maestro 是一个开源的移动与 Web 端 UI 自动化测试框架。你用 YAML 写测试步骤，它负责在 Android 模拟器、iOS 模拟器或浏览器里执行，并帮你处理动态界面的等待问题。对于不熟测试框架的开发者，它把"写定位代码"这件事替换成了"写人话命令"，这是本文要带你跑通的全部链路。

📦 项目速览：一条 YAML 就能驱动真机

Maestro 的核心是"人类可读的 YAML 流程 + 解释执行引擎"。一条测试就是一个 flow 文件，步骤是launchApp、tapOn、inputText、assertVisible这样的命令。流程文件即时解释、无需编译，改完即跑；仓库自身就用同一套 YAML 对自己的 Android、iOS、Web 驱动做端到端自测。

🔍 核心能力拆解

用 flow 文件描述测试步骤

一个 flow 文件由appId加一串命令组成。下面的例子来自仓库 README：启动 Android 联系人应用，新建联系人 John Snow 并保存。

appId: com.android.contacts --- - launchApp # 启动应用 - tapOn: "Create new contact" - tapOn: "First Name" - inputText: "John" - tapOn: "Save"

appId指定被测应用，命令之间按顺序执行。仓库的 e2e/demo_app/.maestro/ 目录里放了几十条现成 flow，覆盖输入、手势、权限、截图对比等场景，是理解每条命令最快的样本库。

用自然语言做 AI 断言

有些界面用text选择器不好写，Maestro 提供两条 AI 命令：assertWithAI接受一句自然语言断言，由大模型判断当前截图是否满足；assertNoDefectsWithAI则检查布局错乱、元素重叠这类视觉缺陷。命令定义在 maestro-orchestra-models 的 Commands.kt，模型对接与调用逻辑在 maestro-ai 模块。

- launchApp: clearState: true # 启动前清空应用状态 - assertWithAI: optional: true # 断言失败不终止流程 assertion: 登录界面可见，包含用户名和密码输入框

适用场景：文案频繁变更的界面、视觉回归检查，以及你还不确定该用哪个选择器时的兜底验证。

同一套写法覆盖 Android、iOS 与 Web

平台差异被收敛在仓库内部的驱动层——maestro-android/、maestro-ios-xctest-runner/和maestro-web/分别对接各自平台，maestro-client/提供统一入口。对你的意义是：同一个 flow 可以在三个平台各跑一遍。仓库 e2e/workspaces/wikipedia/ 下的android-flow.yaml与ios-flow.yaml就是同一业务流程的双平台对照写法。

🏃 实战：从零跑通第一条测试

目标 1：装上 CLI。Maestro 要求 Java 17 及以上。

git clone https://gitcode.com/GitHub_Trending/ma/maestro cd maestro ./gradlew :maestro-cli:installDist # 构建出 CLI 可执行文件

目标 2：写一个最小 flow。新建flow.yaml，把appId换成你装在模拟器里的应用包名，内容可以照抄上文联系人示例。

目标 3：执行。

maestro test flow.yaml # 指定模拟器或设备后运行

运行结束后终端会逐步打印每条命令的执行结果，失败时附带当时截图路径，你不需要额外配置报告工具。想不开终端写测试，也可以装官方免费的 Maestro Studio，它提供可视化 flow 编辑器和元素检查。

⚙️ 进阶：两个决定测试稳定性的机制

显式等待。移动端 UI 加载速度不定，Maestro 内置自动等待与重试，不需要手写sleep()。当默认行为不够时，用extendedWaitUntil显式声明等待条件：

- extendedWaitUntil: timeout: 10000 # 最长等 10 秒 visible: text: 'Gesture Tester'

对使用者的意义：CI 上偶发失败时，先检查失败命令处的waitToSettleTimeoutMs和超时设置，而不是盲目加长 sleep。命令的重试与生命周期由 maestro-orchestra 模块统一调度。

MCP 服务器与 LLM 评估。Maestro CLI 内置一个 MCP 服务器，把list_devices、take_screenshot、inspect_screen、run等 8 个工具暴露给大模型，让 AI Agent 可以对话式地驱动测试。项目自己用另一个 LLM 当"裁判"（LLM-Judge）来判定工具调用是否正确，评估配置见 maestro-cli 的 MCP 评估文件。这说明它的 AI 能力路径是被持续量化验证的，而不是演示性质。