limrun-maestro-testing

Limrun iOS 上的 Maestro

在远程 Limrun iOS 模拟器上运行上游原版 Maestro CLI。 lim ios maestro 会将 maestro test 透明地连接到实例：必要时，它会在模拟器上安装并启动 Maestro XCTest 运行器，然后将驱动程序流量路由到该运行器。无需分叉 Maestro，无需本地模拟器，也无需本地 Xcode。

前提条件

• lim CLI 0.22.0 或更高版本：npm install --global lim。认证方式为 lim login 或 LIM_API_KEY（即使 .env 和 shell 中看不到，用户环境中也可能已经设置；索取之前请先检查）。
• PATH 中有 Maestro CLI：curl -fsSL https://get.maestro.mobile.dev | bash。 Maestro 需要 Java 17+（使用 java -version 检查）。Maestro 2.5.x 和 2.6+ 均可使用；lim 会自动适配已安装的版本。

CLI 是权威信息来源：如果某个标志报错，或者你需要使用此处未列出的标志，请查看 lim ios <subcommand> --help，不要猜测。

验证设置

在操作用户的应用之前，请先使用内置的 Settings 应用运行一个 flow，以验证整个流程； 无需安装应用、建立隧道或进行构建：

ID=$(lim ios create --install-asset appstore/maestro-ios-runner-2.5.1.tar.gz \
  --no-open --quiet --json | jq -r .metadata.id)

cat > hello-flow.yaml <<'EOF'
appId: com.apple.Preferences
---
- launchApp
- assertVisible: General
- takeScreenshot: settings-check
EOF

lim ios maestro --id "$ID" test hello-flow.yaml

三个步骤都报告 COMPLETED，表示 Maestro、运行器和远程连接均正常工作；此后出现的任何故障都与应用或 flow 有关，而非设置问题。

运行 flow

lim ios maestro test flow.yaml
lim ios maestro test flows/
lim ios maestro --id <ios-id> test flow.yaml

不带 --id 时，目标为当前工作区中最近创建的 iOS 实例（工作区对应于你所在的 git 仓库或 worktree）；在脚本、Agent 中，或从其他目录运行时，请传入 --id <ios-id>（放在 test 之前）。实例上的首次运行需要多花几秒启动运行器（如果尚未预装，还需要安装）；之后的运行会跳过这一步。额外的 Maestro 标志放在 -- 之后：

lim ios maestro -- test flow.yaml --include-tags smoke --test-output-dir artifacts

请勿传入 --platform、--device、--udid、--no-reinstall-driver 或 --driver-host-port；这些选项由 lim 自行设置，并会拒绝重复指定。 Maestro 的实际退出码和报告都会保留，因此 CI 配置可以像使用本地 Maestro 一样工作。

实例设置

任何正在运行的 iOS 实例都可以；首次使用时会安装运行器。创建实例时预装运行器即可跳过这一步：

lim ios create --install-asset appstore/maestro-ios-runner-2.5.1.tar.gz --no-open

--no-open 会跳过在浏览器中打开流 URL（这对无头机器和 CI 机器很重要）。上方的运行器资源名称是唯一已发布的名称，且与版本无关：同一个运行器适用于 Maestro 2.5.x 到 2.7.x，因此不要寻找与 Maestro 版本相匹配的资源。

照常安装待测应用（使用 lim ios create --install app.ipa、 lim ios install-app 或构建技能），然后在 flow 中通过 appId: 引用其 bundle id。若要测试 Expo Go，还需预装 appstore/Expo-Go-54.0.6.tar.gz，并使用 openLink 打开项目 URL（环境变量必须以 MAESTRO_ 为前缀，才能在 flow 中使用）：

MAESTRO_EXPO_URL='exp://<tunnel-host>' lim ios maestro test flow.yaml

Expo dev-client 构建

Expo Go 是最快的方式，但 dev-client 构建也同样可用。launchApp 会打开 dev 启动器，而不是你的应用，因此请改为打开 dev-client URL：先执行 - stopApp，然后执行 - openLink: <scheme>://expo-development-client/?url=<url-encoded-metro-url>。 使用 limrun-expo-development 构建 dev client、启动 Metro 并生成该 URL。

Limrun 上的流程注意事项

• 不支持 startRecording/stopRecording YAML 命令（模拟器位于远程）。请在运行流程前后进行录制：lim ios record start --id <ios-id> 会立即返回（录制在实例上进行），流程结束后，lim ios record stop --id <ios-id> -o video.mp4 会将视频下载到本地路径。
• takeScreenshot 可正常使用，并会像原版 Maestro 一样将 PNG 保存到工作目录（或 --test-output-dir）。
• 不支持 addMedia 以及引用模拟器本地文件路径的流程命令。
• runScript/evalScript 发出的 HTTP 调用必须使用 https:// URL。普通的 http:// 调用会被拒绝（访问驱动程序本身的请求除外），因为 Maestro 的普通 HTTP 流量会经由本地桥接，仅转发到远程模拟器。
• 如果要对已打开的应用（例如 Expo Go）重新运行流程，请在 openLink/launchApp 前使用 - stopApp 启动流程；处于前台过程中的应用可能会丢弃深层链接，而过期界面会导致前置断言失败。
• 设备群差异：请基于稳定的无障碍标识符和文本编写断言，不要依赖时序。首次加载应用时，请使用 extendedWaitUntil 并设置充足的超时时间。
• 文本选择器会匹配元素的无障碍标签；在 iOS 上，标签通常会合并同级元素的内容（图标名称、相邻文本）或包含不换行空格。编写选择器前，请使用 lim ios element-tree 读取准确标签，不要根据屏幕显示内容猜测。

验证信号

• Running maestro <version> against <ios-id>... 后接 Running on Limrun iPhone - iOS ...：驱动程序已端到端连接。
• Launching the Maestro runner...：此实例上的首次使用。 只有在创建实例时未包含 runner 资源的情况下，才会另外显示 Installing the Maestro runner...。后续运行会跳过这两项。
• Maestro 本身每次运行都会输出数条 JDK WARNING 行（涉及反射、原生访问）；这些是无害的上游噪声，并非 Limrun 错误。
• 流程失败时会输出 Maestro 自身的调试输出目录，其中包含屏幕截图和 UI 层级；调试选择器时，lim ios element-tree --id <ios-id> 会显示实时屏幕。

清理

完成后请删除实例：lim ios delete <ios-id>（delete 不支持 --id）。lim ios maestro 启动的连接会在命令退出时拆除。