• 在真实设备、模拟器、模拟器和桌面浏览器上运行 Maestro YAML 流量
• 支持Android (UIAutomator2), iOS (WebDriverAgent), Web (Chrome CDP),和云 (Appium)
• 内建并行执行, HTML/J Unit/ Allue 报告, 以及 JavaScript 脚本
• 地址 78%的前100个讨论最多的未决问题 在大师的GitHub上

大赦国际: llms.txt 为AI助理提供结构化摘要,回答关于这个项目的问题.

安装

贝壳 - macOS 和 Linux :

curl -fsSL https://open.devicelab.dev/install/maestro-runner | bash

# A specific version
curl -fsSL https://open.devicelab.dev/install/maestro-runner | bash -s -- --version 1.1.28

无 ——用于反应原生,博览会,或任何已有项目 package.json数字 :

npx maestro-runner test flows/          # no install step
npm install --save-dev maestro-runner   # or pin it in the project

Pinning意味着每台机器和每台CI工作运行一个版本,没有单独的"靴子". 没有邮站,安装时没有下载任何信息: 您平台的二进制是普通可选依赖 npm 选择的 os 财务报告和审定财务报表 cpu,所以安装工作离线, 在代理后, 和在CI 中阻断邮购网络访问.

都给你同样的二进制. macOS和Linux,arm64和x64;在Windows上,使用WSL.

首发

maestro-runner doctor     # check the toolchain and hear exactly what is missing
maestro-runner devices    # what this machine can drive right now

运行测试

maestro-runner test flow.yaml                                           # Android (default)
maestro-runner --platform ios test flow.yaml                            # iOS
maestro-runner --platform web test flow.yaml                            # Desktop browser (Chrome)
maestro-runner --app-file app.apk test flows/                           # Install app and run
maestro-runner --driver appium --appium-url <server-url> test flow.yaml # Appium
maestro-runner test --parallel 3 flows/                                 # Parallel on 3 devices

AI 编码代理

maestro-runner skills install    # writes ~/.claude/skills/maestro-runner/SKILL.md

安装一个能告诉 Claude Code( 和其他代理读取) 的技能 SKILL.md)如何写出"大师流",用"大师跑"来运行,检查屏幕并阅读报告. --dir 写在别处(.claude/skills/maestro-runner 在一个仓库里, --print 打印出来。 文件带有二进制的版本,从更新的版本安装时被替换.

关键特性

• 零移徙 — 运行您已有的 YAML 大师流
• 真正的 iOS 设备测试 ——支持物理iOS设备,而不仅仅是模拟器 页:1
• 云测试 — 浏览器Stack, Sauce Labs, Lambda Test, 通过 Appium 驱动程序测试Bot 页:1
• 桌面浏览器测试 ——通过CDP运行大师流于Chrome/Chrome. 支助 css, (中文(简体) ), xpath, (中文(简体) ), id,以及 text 选择器为 --platform web 页:1
• 反应原生和蝶形 ——RN测试ID和蝶语义的智能元素查找 页:1
• 设备实验室驱动程序 ——Android和iOS上的默认驱动程序. 在Android上,一个通过WebSocket的在线设备代理,~2x比UIAutomator2快,~5x比Maestro CLI快;在iOS上,一个预建的XCUITest代理,在模拟器和真iPhone上
• 并行执行 ——动态工作在器件之间的分布,不是静态的硬化. 更快的设备自动取取更多测试, 所以设备不会闲置
• App 安装内置 —— 说 --app-file app.apk 在测试前安装应用程序, 所以你总是测试正确的构建
• 宽OS相容性 ——Android 5.0+(API 21+)和iOS 15.0+,没有版本限制
• 报告 —— HTML, JUnit XML, 和 Allure 兼容的报告出框
• 清除错误消息 —— 说 element not found: text="Login" 改为 io.grpc.StatusRuntimeException: UNKNOWN
• 飞行前验证 ——在执行前抓取流量错误,循环依赖,并丢失文件
• 快速元素查找 – 原生选择器,可点击的父反转, regex 匹配,更聪明的能见度
• 可靠的文本输入 ——有 Unicode 支持的直接 ADB 输入,没有丢弃字符
• 卷轴不透视 ——可靠地找到屏幕外要素的原生滚动执行
• 相对选择者 - 按位置查找要素:下面、以上、左、右、子
• Java 脚本脚本 ——嵌入JS运行时间与HTTP客户端进行动态测试逻辑,没有外部依赖性
• 可配置的超时 每个指挥官和每流暂停, --find-timeout 3000 在3 s 而不是17 s 中使一个错误的选择器失败, --wait-for-idle-timeout 0 无法禁用
• 轻巧 - 单一二进制,不需要JVM

支持的平台和驱动程序

设备Lab 驱动程序 (Android)

DuiceLab驱动程序是默认的Android驱动程序(自v1.1.28起). 它通过WebSocket直接在设备上运行自动化,跳过UIAutomator2 HTTP层,用于~2x比UIAutomator2快的测试执行——和~5x比Maestro CLI快. --driver uiautomator2 选择上一个默认值.

Benchmark: 9 flows, 163 steps on Pixel 4a (Android 13)

  DeviceLab:     1m 12s
  UIAutomator2:  2m 24s
  Maestro CLI:   4m 22s

maestro-runner --platform android test flows/          # DeviceLab
maestro-runner --driver uiautomator2 test flows/        # UIAutomator2

所有现有的YAML大师流是可行的——不需要改变。 驱动程序还包括对动画元素的限定稳定,并改进了文本选择器中的特殊字符处理.

CI/CD 一体化

maestro-runner为CI/CD管道所建——单二进制,无JVM启动,内存足迹低. 与GitHub Actions,GitLab CI,Jenkins,CircleCI合作,以及任何支持Android模拟器或iOS模拟器的CI系统.

# CI example: auto-start emulator, run tests, shutdown after
maestro-runner --auto-start-emulator --parallel 2 flows/

流程配置

maestro-runner 扩展标准 Maestro 流 YAML 附加字段 :

commandTimeout: 10000       # Default per-command timeout (ms)
waitForIdleTimeout: 3000    # Device idle wait (ms), 0 to disable
---
- launchApp: com.example.app
- tapOn: "Login"
- assertVisible: "Welcome"

视觉回归( E)assertScreenshot(中文(简体) )

assertScreenshot 比较当前屏幕( 可选择裁剪到 cropOn),以PNG为参考.

• 首发: 如果参考文件缺失, 首席执行官将抓取的截图写成新的基线并经过.
• 重新基线 : 覆盖现有基线 --update-screenshots (或 MAESTRO_UPDATE_SCREENSHOTS=true) (中文(简体) ).
• 在不匹配时, a {name}_diff.png 复数被写在引用旁边 .
• 像素比较是设备—— 分辨率—— 和OS—— 设定设备配置 thresholdPercentage 故意( 默认) 95) (中文(简体) ).

maestro-runner test flows/visual.yaml                  # seeds missing baselines
maestro-runner test --update-screenshots flows/visual.yaml

所需资源

• 安卓测试: adb (Android SDK平台-工具)
• iOS 测试 : Xcode 命令行工具 (xcrun(中文(简体) )
• 网页/浏览器测试 : 铬或铬
• 云和 Appium 测试 : Appium 2.x 或 3.x – 与本地 Appium 服务器和云提供商( BrowserStack, Sauce Labs, Lambda Test, Testing Bot)合作

云提供商

maestro-runner通过Appium驱动程序在云设备网格上运行Maestro YAML流. 通过提供者的中枢 URL 和功能 JSON 文件 :

maestro-runner --driver appium --appium-url <HUB_URL> --caps caps.json test flows/

• 测试程序 ——测试运行的设置指南 瓶子真正的装置云
• 苏塞实验室 用于运行于 Sauce Labs Appium 云的设置指南

遥测

maestro- runner 在每个结尾发送一个匿名使用事件 test 运行 : 仅计数和版本,例如跑步版本、平台、驱动程序、设备 类型、流和步数、失败类型和持续时间。 它没有机器或 用户 id, 没有流程或文件名称, 选择器, app ids, URL, 环境值或 错误消息, 您的机器上没有写任何信息 。 项目被告知 除以您运行的流程文件列表的单向散列; 名称 他们没有被派遣.

把它关掉 MAESTRO_RUNNER_NO_TELEMETRY=1 或者说 DO_NOT_TRACK=1设置 MAESTRO_RUNNER_TELEMETRY_DEBUG=1 以打印事件而不是发送. 遥测 列出每个字段.

更新检查是分开的: MAESTRO_RUNNER_NO_UPDATE_CHECK=1 关掉, 通知书上没有印出.

捐款

见 捐款额 准则.

许可证

apache 许可证 2.0 —— 见 自由主义。 。 。 .

设备Lab 二进制

后面的预建设备 --driver devicelab (Android代理 APKs和iOS代理在 drivers/ios/devicelab-ios-agent/)可以自由使用,包括商业操作,但他们 非开源。 你可以再分配它们 作为主运行者的一部分(叉子,多克图像, CI 缓存;除经允许外,不得修改、单独运送或倒置 适用法。 见 司机/司机 全部条件. 这个寄存处的其他一切,包括其他驱动程序,都保留了开源许可证.