企业官网建设流程全解析

Maestro 移动 UI 自动化测试：5 个环节拆解 YAML 工作流

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

Maestro 用声明式 YAML（一种用缩进和列表描述数据结构的脚本格式）编写移动 UI 自动化测试，同一份脚本可以直接跑在 Android 与 iOS 上。这篇文章不按学习阶段组织，而是按"编写 → 执行 → 调试 → 复用 → 扩展"的真实工作流拆解它的核心能力：从最小可运行脚本，到等待策略、录制回放、runFlow（子流程调用）复用与 MCP 集成，全部以仓库内真实的 e2e 用例为依据，示例集中在 e2e/workspaces/ 下。

编写：最小可运行 YAML 脚本与断言写法

Maestro 脚本的最小单元是一条扁平的命令序列，平台差异被引擎封装掉，你只描述"做什么"。

launchApp 前置块与基础命令序列

下面这段取自仓库内的 Web 登录示例，演示一条最小可运行的脚本长什么样：

appId: https://www.saucedemo.com/ # Web 测试时 appId 也可以直接写 URL --- - launchApp - tapOn: Username - inputText: standard_user # 直接打入上一次 tap 聚焦到的输入框 - tapOn: Login - assertVisible: Products

关键参数：appId对原生应用是包名，对 Web 页面可以换成 URL；inputText作用于当前聚焦的输入框，所以前面不需要再指定元素。

元素定位：id、text 与断言组合

定位的稳定性排序通常是id>text> 视觉特征，仓库里的 iframe 测试展示了嵌套容器下的定位与断言组合：

# 断言目标是 iframe 内部的元素，证明查询能穿透嵌套容器 - assertVisible: id: "echo-output" text: Potato - assertNotVisible: "Type here..." # 占位符被输入替代后消失，断言"消失"比断言"出现"更稳

关键参数：id在 Android 侧对应资源 id、iOS 侧对应 accessibility identifier，是最稳定的定位锚点；assertNotVisible这类否定断言适合验证"占位符消失""弹窗关闭"这类状态迁移。

执行：等待策略与 retry 兜底的 YAML 写法

偶发失败几乎都来自时序问题，解法是把等待显式写进脚本，而不是靠调大默认超时。

extendedWaitUntil 处理长时异步加载

仓库里 WebView 加载用例对慢加载页面给出了长超时等待的写法：

# 慢加载页面：显式给出 90 秒上限，并写明人类可读的标签 - extendedWaitUntil: visible: Login timeout: 90000 label: Wait for Login page to load

关键参数：timeout单位为毫秒；label会出现在报告里，超时时能直接定位到卡在哪个语义步骤，而不是一个匿名等待。

retry 包裹不稳定交互

点击被静默吞掉、动画未完成这类问题，用重试包裹比加等待更干净：

# 温设备上的点击可能被静默吞掉：重试 + 否定断言，确认导航确实发生 - retry: maxRetries: 2 commands: - tapOn: Open Login Page - assertNotVisible: Open Login Page

关键参数：maxRetries是额外重试次数；注意commands内要以断言收尾，否则重试无法判断上一次尝试是否真正成功。

调试：studio 单步、record 录制与层级导出

失败时最贵的成本是复现，Maestro 把单步调试、操作录制和元素树导出都做进了 CLI。

maestro studio 与 record 的分工

💡 调试路径按问题类型选：怀疑逻辑顺序用 studio，怀疑"当时屏幕上长什么样"用 record：

maestro studio e2e/workspaces/web/simple.yaml # 单步调试：图形界面逐步执行，失败即停 maestro record # 录制真实手势操作，回放生成可复现脚本 maestro printHierarchy # 导出当前屏幕元素树，核对定位依据

关键参数：studio接收一个流程文件，可在界面上逐步执行并查看每步匹配到的元素；printHierarchy作用于当前连接的设备，输出的层级结构是排查"点错元素"的第一手材料。

printHierarchy 导出元素树排查定位

元素定位失败时，先跑一次printHierarchy，确认目标元素的id/text在当前设备上是否真实存在、文案是否与脚本一致。仓库的调试类命令（PrintHierarchyCommand、StudioCommand、RecordCommand）都集中在 maestro-cli/src/main/java/maestro/cli/command/ 下，需要深挖实现时直接看这里。

复用：runFlow 子流程拆分与变量传递模式

重复代码是测试套件腐化的起点，runFlow 把公共步骤拆成可独立维护的子流程。

跨平台分支：按平台拆分 subflows

Wikipedia 示例的流程文件把平台差异收敛到子流程：主流程只写runFlow: subflows/onboarding-android.yaml或onboarding-ios.yaml，引导页、清状态等步骤各自独立成文件，放在 e2e/workspaces/wikipedia/subflows/ 下。另一招是optional: true——元素不存在时跳过该步而非报错，用它吸收两个平台版本间的 UI 漂移。

runScript 注入动态数据

搜索类用例需要每次生成不重复的查询词，仓库的进阶流程展示了脚本返回值的传递方式：

- runFlow: subflows/onboarding-android.yaml # 公共引导步骤抽成子流程，多处复用 - runScript: scripts/getSearchQuery.js # JS 在运行时生成随机搜索词 - inputText: ${output.result} # 把脚本返回值带入下一步 - assertVisible: ${output.result}

关键参数：output是脚本写出的内置变量，用${output.xxx}引用；runFlow的路径相对于当前流程文件所在目录解析。

扩展：Web 端测试与 MCP 集成

Maestro 的能力边界不止于原生 UI 命令，脚本钩子和 Web 驱动把测试接进了更大的生态。

同一套 YAML 跑 Web 端

e2e/workspaces/web/下的用例证明了同一套命令可以驱动浏览器：appId换成 URL 后，tapOn、inputText、assertVisible语义不变，SPA 路由跳转（spa_navigation.yaml）和同源 iframe 内的输入（iframe_same_origin.yaml）都有对应用例覆盖。

MCP：LLM 直接驱动设备的协议

MCP（Model Context Protocol，一种让 LLM 调用外部工具的标准协议）集成后，LLM 可以直接读取屏幕状态、执行点击与断言，把"探索式测试"接进现有流程。相关实现位于 maestro-cli/src/main/java/maestro/cli/mcp/，配合 CLI 的 mcp 子命令即可把 Maestro 注册为模型可驱动的设备端点。

能力边界速览

Maestro 擅长声明式 UI 层 E2E：跨平台脚本复用、元素与视觉断言、录制回放调试，以及通过 MCP 把 LLM 接进测试流程；它不擅长设备内部状态——网络延迟、崩溃堆栈、性能指标和纯业务逻辑验证，这些仍需仪器化测试或真机实验室补齐。对 Web 端它能覆盖常规交互与断言，但深层 DOM 操作能力弱于专用浏览器自动化工具。

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