Maestro 移动 UI 自动化测试入门教程本文带你从零开始掌握 Maestro —— 一款开源的跨平台移动 UI 自动化测试框架。涵盖安装配置、YAML 测试流编写、核心命令、选择器、高级用法及实战案例让你 10 分钟写出第一条自动化测试。一、Maestro 是什么Maestro 是一款开源的端到端移动 UI 自动化测试框架支持Android、iOS 和 Web应用包括 React Native、Flutter 和混合应用。它的核心理念是拥抱不稳定性通过人类可读的 YAML 语法和解释型执行引擎让测试编写变得简单高效。与传统自动化框架如 Appium、XCUITest相比Maestro 最大的优势在于极低的上手门槛—— 你不需要编写复杂的代码只需用 YAML 描述用户操作即可。核心特性特性说明跨平台一套 YAML 语法同时测试 Android、iOS 和 Web 应用人类可读的 YAML用launchApp、tapOn、assertVisible等命令表达交互内置抗抖动自动等待 UI 稳定无需手动写sleep()解释型执行无需编译修改即运行快速迭代智能元素定位默认使用 Accessibility Tree模拟真实用户视角JavaScript 集成在 YAML 中内嵌 JS 处理复杂逻辑、调用外部 API测试录制自动将执行过程录制成 MP4 视频Maestro Studio可视化测试构建器支持录制交互、检查元素为什么选择 Maestro学习曲线低5 分钟写出第一条测试无需编程经验维护成本低YAML 语法直观测试即文档稳定性高内置智能等待机制减少 flaky tests生态完善支持本地测试、CI/CD 集成、云端测试二、环境准备与安装2.1 前置条件安装 Maestro 前请确保系统已安装Java 17 或更高版本。验证 Java 版本java-version如果未安装 Java推荐使用 Temurin JDK 或 Oracle JDK 安装。确保JAVA_HOME环境变量指向 Java 17 的安装路径。2.2 安装 Maestro CLImacOS 安装方式一使用 curl 脚本安装curl-fsSLhttps://get.maestro.mobile.dev|bash方式二使用 Homebrew 安装brew tap mobile-dev-inc/tap brew trust--formulamobile-dev-inc/tap/maestro brewinstallmobile-dev-inc/tap/maestromacOS 用户还需安装最新版 Xcode 和 Xcode Command Line Tools用于 iOS 模拟器测试。Windows 安装前往 Maestro GitHub Releases 下载最新的maestro.zip解压到稳定目录如C:\maestro将 Maestro 的bin目录添加到系统 PATHsetx PATH%PATH%;C:\maestro\bin重启终端使配置生效Linux 安装curl-fsSLhttps://get.maestro.mobile.dev|bash安装完成后默认安装路径为$HOME/.maestro/bin。如果maestro命令不可用手动添加 PATHexportPATH$PATH:$HOME/.maestro/bin2.3 验证安装运行以下命令若显示帮助信息则安装成功maestro--help2.4 准备测试设备Maestro 需要一个正在运行的设备或模拟器来执行测试。Android 测试打开 Android Studio进入 Virtual Device Manager启动一个虚拟设备如 Pixel 8等待设备启动到主屏幕iOS 测试打开 Xcode启动 iOS 模拟器如 iPhone 15确保模拟器处于运行状态三、第一个测试10 分钟快速上手3.1 创建测试文件创建一个新目录并新建contacts.yaml文件appId:com.google.android.contacts----launchApp:clearState:true-tapOn:Allow-tapOn:Create contact-tapOn:First name-inputText:John-tapOn:Last name-inputText:Doe-tapOn:Company-inputText:Maestro-tapOn:1-inputText:111-111-1111-tapOn:Save-back3.2 运行测试确保模拟器正在运行然后执行maestrotestcontacts.yamlMaestro 会连接到模拟器按顺序执行每个步骤。终端会显示实时进度报告你可以在模拟器上看到自动化操作的过程。3.3 测试录像在 Flow 中加入录像命令执行后会在当前目录生成recording.mp4appId:com.google.android.contacts----launchApp:clearState:true-startRecording:recording# 开始录像-tapOn:Create contact-tapOn:First name-inputText:John-tapOn:Last name-inputText:Doe-tapOn:Save-stopRecording# 停止录像生成 recording.mp4四、Flow 结构详解Maestro 的测试文件称为Flow使用 YAML 格式编写。一个标准的 Flow 由两部分组成用---分隔# 配置区 appId:com.example.app# 必填被测应用的包名/Bundle IDname:登录测试# 选填Flow 的自定义名称tags:# 选填标签用于筛选测试-smoke-test-loginenv:# 选填环境变量USERNAME:userexample.comPASSWORD:123456---# 命令区 -launchApp# 启动应用-tapOn:Username# 点击用户名输入框-inputText:${USERNAME}# 输入环境变量-tapOn:Password-inputText:${PASSWORD}-tapOn:Login# 点击登录-assertVisible:Welcome# 断言欢迎信息可见配置区字段说明字段必填说明appId是被测应用的包名Android或 Bundle IDiOSname否Flow 的显示名称会出现在测试报告中tags否标签列表配合--include-tags/--exclude-tags使用env否环境变量映射在命令区通过${变量名}引用五、核心命令速查5.1 常用命令一览命令说明示例launchApp启动应用- launchAppkillApp强制关闭应用- killApptapOn点击元素- tapOn: 登录doubleTapOn双击元素- doubleTapOn: 头像longPressOn长按元素- longPressOn: 消息inputText输入文本- inputText: helloeraseText删除文本- eraseText: 10swipe滑动操作- swipe: { direction: UP }scroll滚动- scrollscrollUntilVisible滚动直到元素可见- scrollUntilVisible: { element: 加载更多 }back返回Android- backpressKey按键- pressKey: EnterhideKeyboard隐藏键盘- hideKeyboardassertVisible断言元素可见- assertVisible: 欢迎assertNotVisible断言元素不可见- assertNotVisible: 错误takeScreenshot截图- takeScreenshot: resultwaitForAnimationToEnd等待动画结束- waitForAnimationToEndopenLink打开链接- openLink: https://example.com5.2 命令详细用法launchApp —— 启动应用# 基本启动-launchApp# 启动并清除应用状态重新开始-launchApp:clearState:true# 启动并清除权限设置-launchApp:clearState:trueclearKeychain:truetapOn —— 点击元素# 通过文本点击-tapOn:登录# 通过 ID 点击-tapOn:id:login_button# 通过文本点击指定第几个匹配项-tapOn:text:删除index:2# 多条件组合定位-tapOn:text:提交enabled:truebelow:个人信息inputText —— 输入文本# 直接输入-inputText:hello world# 输入环境变量-inputText:${USERNAME}# 输入数字-inputText:13800138000swipe —— 滑动操作# 方向滑动-swipe:direction:UP# 指定百分比区域滑动-swipe:start:50%,80%end:50%,20%# 元素间滑动-swipe:from:id:item_1to:id:item_5assertVisible —— 断言元素可见# 简单断言-assertVisible:登录成功# 带超时的断言-extendedWaitUntil:visible:欢迎页面timeout:10000# 可选断言不通过也不会失败-assertVisible:text:弹窗广告optional:true六、选择器Selectors选择器是 Maestro 定位 UI 元素的核心机制。Maestro 默认使用Accessibility Tree无障碍树从用户视角来识别界面元素。6.1 选择器类型文本选择器最常用# 简写形式-tapOn:Login# 完整形式-tapOn:text:Logintext默认支持正则表达式可用于匹配动态文本。ID 选择器最稳定-tapOn:id:submit_buttonID 是 Accessibility Identifier不受语言切换影响适合多语言应用。索引选择器当有多个匹配元素时用index指定第几个从 0 开始-tapOn:text:删除index:1# 点击第 2 个删除按钮坐标选择器-tapOn:point:50%,50%6.2 关系选择器当元素本身没有唯一标识时可以用相对位置来定位# 点击密码下方的元素-tapOn:below:密码# 点击标题上方的元素-tapOn:above:标题# 点击某个父容器内的元素-tapOn:text:删除childOf:id:list_item6.3 状态选择器# 只在元素可点击时操作-tapOn:text:提交enabled:true# 检查勾选状态-assertVisible:text:记住密码checked:true# 检查焦点状态-assertVisible:text:搜索框focused:true6.4 选择器最佳实践场景推荐策略有固定文本的按钮/标签使用text选择器直观且自文档化图标、图片等无文字元素使用idAccessibility Identifier跨语言稳定动态文本或无唯一标识用关系选择器above/below锚定位置文本部分变化使用正则text: 订单.*成功等待异步加载完成在选择器中加enabled: true自动等待可交互状态七、高级用法7.1 子 FlowSubflows将通用操作抽取为子 Flow实现复用。例如创建login.yaml# login.yamlappId:com.example.app----tapOn:用户名-inputText:${USERNAME}-tapOn:密码-inputText:${PASSWORD}-tapOn:登录-assertVisible:首页在其他 Flow 中调用# main_flow.yamlappId:com.example.app----launchApp-runFlow:login.yaml# 调用子 Flow-tapOn:我的订单-assertVisible:订单列表7.2 条件执行使用runFlow配合when条件来控制执行逻辑-runFlow:when:visible:升级提示commands:-tapOn:稍后7.3 循环-repeat:times:3commands:-tapOn:下一个-assertVisible:图片7.4 JavaScript 集成在 YAML 中直接执行 JavaScript处理复杂逻辑appId:com.example.app----evalScript:${output.date new Date().toISOString()}-tapOn:日期-inputText:${output.date}发起 HTTP 请求-evalScript:${output.response http.get(https://api.example.com/test-data)}-inputText:${output.response.body.id}7.5 重试机制对不稳定操作使用retry-retry:maxRetries:3commands:-tapOn:刷新-assertVisible:数据加载完成八、CLI 命令参考8.1 常用命令命令说明maestro test flow.yaml执行测试maestro test -c flow.yaml连续模式文件变更自动重跑maestro test --include-tagssmoke .只运行带smoke标签的 Flowmaestro test --formatJUNIT .生成 JUnit 格式报告maestro start-device --platformandroid启动 Android 模拟器maestro list-devices列出本地可用设备maestro record flow.yaml录制测试执行过程maestro download-samples下载官方示例maestro hierarchy打印当前应用的视图层级8.2 test 命令常用选项选项说明-c, --continuous连续模式监控文件变化自动重跑-e, --envKEYVALUE设置环境变量--include-tagstags只运行包含指定标签的 Flow--exclude-tagstags排除包含指定标签的 Flow--formatFORMAT报告格式JUNIT、HTML、NOOP--outputPATH指定报告输出路径--deviceUDID指定运行的设备 ID--platformPLATFORM指定平台android、ios、web-s, --shardsCOUNT并行分片执行8.3 实用示例# 运行单个 Flowmaestrotestlogin.yaml# 运行目录下所有 Flowmaestrotest./flows/# 只运行冒烟测试maestrotest--include-tagssmoke ./flows/# 连续开发模式maestrotest-clogin.yaml# 生成 HTML 报告maestrotest--formatHTML--outputreport.html ./flows/# 传入环境变量maestrotest-eUSERNAMEtesttest.com-ePASSWORD123456login.yaml# 在指定设备上运行maestro--deviceemulator-5554testlogin.yaml# 启动设备maestro start-device--platformandroid --device-osandroid-34九、实战案例登录功能测试下面通过一个完整的登录测试场景综合运用前面学到的知识。9.1 测试场景启动应用处理首次启动的权限弹窗输入用户名和密码点击登录验证登录成功退出登录9.2 测试文件# login_test.yamlappId:com.example.myappname:登录功能测试tags:-smoke-loginenv:USERNAME:testuserexample.comPASSWORD:Test1234---# 启动应用清除状态-launchApp:clearState:true# 处理可能出现的权限弹窗-runFlow:when:visible:允许commands:-tapOn:允许# 进入登录页面-tapOn:登录# 输入用户名-tapOn:id:username_input-inputText:${USERNAME}# 输入密码-tapOn:id:password_input-inputText:${PASSWORD}# 点击登录按钮-tapOn:text:登录index:1enabled:true# 验证登录成功-assertVisible:首页-takeScreenshot:login_success# 退出登录-tapOn:我的-scroll-tapOn:退出登录-tapOn:确认-assertVisible:登录9.3 运行测试# 基本运行maestrotestlogin_test.yaml# 生成 JUnit 报告用于 CI/CDmaestrotest--formatJUNIT--outputreport.xml login_test.yaml# 连续模式开发调试maestrotest-clogin_test.yaml十、Maestro Studio 可视化工具Maestro Studio 是一个轻量级的可视化测试构建工具帮助你快速编写测试。启动 Maestro Studiomaestro studio核心功能功能说明视觉流构建器点击界面元素自动生成对应命令元素检查器查看元素的 ID、文本、层级等属性实时预览在模拟器上操作实时生成 YAMLAI 辅助用自然语言描述操作AI 生成命令对于初学者推荐先用 Maestro Studio 录制操作生成基础 Flow再手动优化 YAML。十一、测试优化与最佳实践11.1 减少测试 flaky善用enabled: true在点击按钮前确保它可交互使用optional: true对可能出现的弹窗做可选断言避免硬等待用assertVisible代替sleep合理使用retry对网络相关操作加重试# 处理可能出现的弹窗-runFlow:when:visible:更新提示commands:-tapOn:稍后提醒# 等待元素可点击再操作-tapOn:text:提交enabled:true11.2 测试组织结构推荐的目录结构project/ ├── config.yaml # 全局配置 ├── flows/ │ ├── login/ # 按功能模块分组 │ │ ├── login_success.yaml │ │ └── login_failure.yaml │ ├── search/ │ │ └── search_flow.yaml │ └── checkout/ │ └── checkout_flow.yaml ├── subflows/ # 可复用的子 Flow │ ├── login.yaml │ └── navigate_home.yaml └── reports/ # 测试报告输出11.3 使用 config.yaml 统一配置在项目根目录创建config.yaml设置全局行为# config.yamlappId:com.example.myapp# 测试执行配置flowOrder:-subflows/login.yaml-flows/# 全局环境变量env:API_BASE_URL:https://test-api.example.com运行时指定配置文件maestrotest--configconfig.yaml ./flows/11.4 CI/CD 集成在 GitHub Actions 中集成 Maestro# .github/workflows/test.ymlname:Maestro Testson:[push,pull_request]jobs:test:runs-on:macOS-lateststeps:-uses:actions/checkoutv4-uses:reactivecircus/android-emulator-runnerv2with:api-level:34script:|curl -fsSL https://get.maestro.mobile.dev | bash export PATH$PATH:$HOME/.maestro/bin maestro test --formatJUNIT --outputreport.xml ./flows/-uses:actions/upload-artifactv4with:name:test-reportpath:report.xml十二、常见问题Q1元素找不到怎么办使用maestro hierarchy命令查看当前界面的视图层级用 Maestro Studio 的元素检查器查看元素属性尝试使用不同的选择器text、id、关系选择器检查元素是否在 WebView 或 Flutter 渲染层中Q2测试运行超时设置启动超时环境变量exportMAESTRO_DRIVER_STARTUP_TIMEOUT180000Q3如何测试 Flutter 应用Maestro 原生支持 Flutter。确保 Flutter 应用启用了语义信息Semantics然后在 Flow 中正常使用选择器即可。Q4如何处理系统弹窗使用runFlow条件执行来处理-runFlow:when:visible:Allowcommands:-tapOn:AllowQ5如何在多台设备上并行测试使用--shards选项maestrotest--shards3./flows/总结Maestro 以其简洁的 YAML 语法、内置的抗抖动机制和跨平台支持大幅降低了移动 UI 自动化测试的门槛。本文涵盖了从安装到实战的完整流程安装配置一行命令完成安装Java 17 即可运行快速上手YAML 描述操作maestro test一键执行核心命令launchApp、tapOn、inputText、assertVisible等选择器文本、ID、关系、状态等多维定位策略高级用法子 Flow 复用、条件执行、循环、JS 集成工程化标签筛选、报告生成、CI/CD 集成对于想要快速建立移动 UI 自动化测试体系的团队Maestro 是一个非常值得尝试的选择。建议从简单的冒烟测试开始逐步扩展到完整的回归测试套件。官方资源官方文档https://docs.maestro.devGitHub 仓库https://github.com/mobile-dev-inc/Maestro社区 Slackhttps://slack.maestro.dev