03、Maestro 安装与使用指南

1. Maestro 简介

Maestro 是一个轻量、开源的移动端 UI 自动化测试框架，支持 Android / iOS / Web。

核心特点：

使用简单 YAML 语法编写测试（Flow）
支持 Maestro Studio（图形化桌面工具，可视化录制/点选生成 YAML，几乎零代码）
稳定、执行快，适合回归测试、冒烟测试

2. 安装 Maestro

2.1 推荐方式：curl 一键安装

curl -fsSL "https://get.maestro.mobile.dev" | bash

安装完成后验证：

maestro --versionmaestro --help

2.2 Java 环境要求

最低要求： Java 17 或更高（官方推荐 Java 17 LTS）

2.3 Android 测试必备工具

brew install android-platform-tools # 提供 ADB

手机设置：

开启 USB 调试：设置 → 关于手机 → 点版本号 7 次 → 开发者选项 → USB 调试
USB 线连接 Mac，首次授权时选择"始终允许"

3. 安装 Maestro Studio（图形化工具）

4. Maestro Studio 录制回放流程

4.1 打开 & 连接设备

打开 Studio → 选择或新建一个 Workspace（普通文件夹，用于保存 .yaml 测试文件）
顶部点击 "No device connected" → 选择你的 Android 手机（ADB 自动检测）
连接成功后，右侧出现手机实时屏幕镜像（live view）

4.2 创建新测试（Flow）

点击 New Flow 或 Create a new test
输入 Flow 名称（如 LoginTest）和 App ID（package name，如 com.yourapp.package）

4.3 交互式录制（Inspect 模式）

点击 Inspect Screen（放大镜图标）
在手机镜像上直接点击 App 中的元素（按钮、输入框等）
弹出菜单后，选择 Run and Insert（执行并插入命令）或 Insert
Maestro 自动生成 YAML 步骤（如 tapOn: "登录"、inputText: "testuser"）
继续操作下一个元素（点击、滑动、输入等）

4.4 结束 & 保存

不再点选元素即可"结束录制"
Inspect 模式卡住时：再次点击 Inspect Screen（toggle）或按 Esc 键
点击 Save 保存 Flow

4.5 回放测试

点击 Run / Play / Run Locally
手机自动执行所有步骤，实时高亮显示
失败时显示截图、日志和 hierarchy

4.6 实用技巧

元素定位： 优先使用 text（按钮文字）或 label，避免依赖混淆后的 id: "0_resource_name_obfuscated"
添加等待： 使用 extendedWaitUntil 或 assertVisible
录制视频： YAML 开头加 - startRecording: myvideo，结尾加 - stopRecording

5. Maestro CLI 常用命令

maestro test your_flow.yaml          # 执行单个 Flowmaestro test flows/                  # 执行整个文件夹maestro hierarchy                    # 查看当前屏幕元素结构（调试用）maestro studio                       # 启动 Studio（浏览器版，旧方式）maestro --help                       # 查看所有命令

6. 常见问题 & 解决

问题	解决方案
brew 下载失败（openjdk / maestro.zip）	优先用 curl 方式安装
`Element not found: 0_resource_name_obfuscated`	App 开启了代码混淆。改用 `tapOn: "按钮文字"`（text selector），或临时关闭 debug 构建的 `minifyEnabled`
设备连不上	运行 `adb devices` 检查；重启 ADB：`adb kill-server && adb start-server`；重新授权 USB 调试
Java 相关报错	切换到 Java 17
Inspect Screen 点击无反应	确保 App 在前台；重连设备；重启 Studio

7. 官方文档

快速开始：https://docs.maestro.dev/get-started/quickstart
CLI 安装：https://docs.maestro.dev/maestro-cli/how-to-install-maestro-cli
Studio 使用：https://docs.maestro.dev/maestro-studio/
完整文档首页：https://docs.maestro.dev/

8. 实战示例：完整自测 Flow

以下是一个完整的 Maestro 自测用例，覆盖了一个贷款类 App（BCredit）的主要功能模块：OTP 登录、授信申请（表单填写 + 证件上传）、授信报告查看、Budget 记账、Account 设置、密码登录等。

用途说明： 这个 Flow 仅用于开发自测，验证 App 主流程是否正常运行。更多功能和高级用法（条件判断、循环、环境变量等）需要自行探索，遇到问题可以直接问 AI 解答。


appId: fri.adisu.ravi---# ============================================================# 1. 启动 App（清除状态，确保每次从全新状态开始）# ============================================================- launchApp:    clearState: true

# 2. 密码登录流程（验证设置的密码可正常登录）# ============================================================- tapOn: Login with password # 切换到密码登录方式- waitForAnimationToEnd # ⏳ 等待登录表单加载- tapOn: Enter phone number- inputText: "8665486654"- tapOn: Enter your password- inputText: "147258"- tapOn: Login # 登录# ⏳ 等待登录完成、首页加载- waitForAnimationToEnd

提示：
以上示例仅覆盖了 App 的登陆流程。Maestro 还支持条件判断、循环、环境变量、子 Flow 引用等高级功能，更多用法请参考官方文档自行探索。遇到任何问题，可以直接官网或问ai咨询。