Maestro 在真实 iOS 设备上的使用指南

Source: Dev.to

TL;DR
Maestro 并未正式支持实体 iOS 设备。我们构建了 maestro-ios-device 来解决此问题。您现有的 YAML 流程在真实 iPhone 上可以不做任何更改直接运行。

问题

• 您的 Maestro 测试在 iOS 模拟器上通过，但在真实 iPhone 上不通过。
• 官方对物理 iOS 设备的支持预计要到明年才能提供。
• 云服务提供商（例如 BrowserStack）可以在其基础设施上运行 Maestro，但它们需要订阅并将您的应用/数据发送到站外。

当前平台支持（2025年12月）

我们的解决方案：连接真实 iOS 设备的桥梁

功能

• 在真实 iPhone 上运行您现有的 Maestro YAML 流程
• 对您的测试文件 无需任何更改
• 支持在多台设备上并行测试
• 兼容 iOS 16.x – 18.x

功能 不 包含

• 需要云订阅
• 将您的应用或测试数据发送到任何地方
• 改变您编写 Maestro 测试的方式

安装

curl -fsSL https://raw.githubusercontent.com/devicelab-dev/maestro-ios-device/main/setup.sh | bash

启动设备桥

maestro-ios-device --team-id YOUR_TEAM_ID --device DEVICE_UDID

运行你的测试

maestro --driver-host-port 6001 \
       --device DEVICE_UDID \
       --app-file /path/to/app.ipa \
       test flow.yaml

示例 YAML 流程（未更改）

appId: com.example.app
---
- launchApp
- tapOn: "Login"
- inputText: "user@example.com"
- tapOn: "Submit"
- assertVisible: "Welcome"

在多个真实 iOS 设备上进行并行测试

原始的 Maestro 代码库中硬编码了端口限制；我们已经将其移除。

Terminal 1

maestro-ios-device --team-id ABC123 --device IPHONE_12_UDID --driver-host-port 6001

Terminal 2

maestro-ios-device --team-id ABC123 --device IPHONE_14_UDID --driver-host-port 6002

现在可以在设备之间拆分运行测试套件，将 CI 时间缩短一半（甚至更多）。

工作原理

1. 设备检测 – 识别已启用开发者模式的物理设备。
2. XCTest Runner – 将测试驱动构建并部署到实际硬件（需要 Apple 开发者证书）。
3. 端口转发 – 将 localhost 桥接到设备的 HTTP 服务器。
4. 会话管理 – 优雅地处理真实设备的约束（例如，通过重新安装应用实现 clearState）。

支持的命令和状态

背景

• DeviceLab 需要一种方式让团队在自己的实体设备上进行测试。
• Maestro 代码库已经包含了 iOS 设备支持的基础；只缺少最终的集成。
• 我们向上游仓库提交了 PR #2856，但社区 PR 可能需要时间合并，因此我们将 maestro-ios-device 作为独立工具发布。

版本兼容性

Requirements

• macOS with Xcode（用于代码签名，必需）
• Apple 开发者账号（免费层可用于个人设备）
• 已启用开发者模式的 iOS 设备

FAQ

这是一款官方工具吗？
不。这是一个非官方的社区工具，未得到 mobile.dev 或 Maestro 团队的支持。当官方 iOS 设备支持发布时，建议切换到官方工具。

我现有的 YAML 流程还能使用吗？
可以。如果它们能在 iOS 模拟器上运行，也能在真实设备上运行，无需更改。

该工具免费吗？
免费。您只需要一个 Apple Developer 账户（免费层级足以用于个人设备）。

会有任何数据离开我的网络吗？
不会。所有测试都在您办公室的设备上本地运行，不会发送到外部服务。

链接

• 工具:
• PR:
• 原始问题:

由 DeviceLab 构建 —— 将您的设备转变为测试实验室，而无需租用他人的设备。