在 Limrun iOS 模拟器上配置、运行或调试…

在 Limrun iOS 实例上用 lim CLI 和 @limrun/detox driver 启动并排查 Detox 测试的 app/tester/mediator 连接时适用。

适用场景

解决思路

1. 按三个组件分离进程：Tester 是本地 Node/Jest/Detox 进程；Mediator 是 `detox run-server`，通常位于 agent 本机；App client 由 limulator 通过 `lim ios launch-app --runtime detox` 注入。
2. 运行本次会话未用过的命令前先查看当前帮助：`lim ios tunnel --help`；`lim ios launch-app --help`。
3. 把长期运行的 mediator、tester、tunnel 分别放在独立终端启动。
4. 使用快速路径前，确保项目 `.detoxrc` 读取会话环境变量；Detox 不会自动消费这些变量，例如：`session: { server: process.env.DETOX_SERVER || 'ws://localhost:8099', sessionId: process.env.DETOX_SESSION_ID || 'limrun-detox' }`。
5. 终端 1 启动 mediator：`npx detox run-server -p 8099 -l verbose`。
6. 终端 2 启动 tunnel：`lim ios tunnel --selector localhost:8099 --detach --id <ios-id>`；并设置 `DETOX_SERVER_URL="ws://localhost:8099"`。
7. 终端 3 在 app 连接前启动 tester：`DETOX_SERVER="ws://localhost:8099" DETOX_SESSION_ID=<session-id> npx detox test --no-start`。
8. 然后从终端 2 重新启动 app；当从包含 `node_modules/detox` 的项目运行时，`--detox-version` 可选。
9. 用 `lim ios launch-app <bundle-id> --id <ios-id> --runtime detox --detox-server-url "$DETOX_SERVER_URL" --detox-session-id <session-id> --detox-version <detox-version>` 启动 app。
10. 优先在 app 连接前启动 tester，或使用 limrun-inc/typescript-sdk `examples/detox-ios` 中维护的编排，避免 mediator 出现良性的 cannot forward 噪音。
11. 如果先手动启动 app 再运行 `npx detox test --no-start`，在 tester 连接前出现 mediator 的 cannot forward 消息是预期现象。
12. 如果 tunnel 启动报告已有活动会话，用 `lim ios tunnel status --id <ios-id> --json` 检查；用 `lim ios tunnel stop --id <ios-id>` 停止废弃会话，然后重新启动声明的 mediator selector。
13. 空闲但打开的 tunnel 不算实例活动，因此不会阻止测试运行之间模拟器的 inactivity timeout。
14. `npx detox test --no-start` 仍需要正常的 Detox 项目配置。
15. 从项目传入 Detox 配置文件和 configuration 名称（可参考 limrun-inc/typescript-sdk 的 `examples/detox-ios/.detoxrc.cjs` 布局）。
16. 使用 Limrun 第三方 driver：`type: '@limrun/detox/driver'`。
17. 保持 `DETOX_SERVER` 和 `DETOX_SESSION_ID` 与 mediator 和 launch 命令一致。
18. 当截图或 driver 调用需要实例 API 时，提供 Limrun driver 环境变量，例如 `LIMRUN_IOS_ID`、`LIMRUN_IOS_API_URL`、`LIMRUN_IOS_TOKEN`。
19. 把 limrun-inc/typescript-sdk `examples/detox-ios` 作为精确配置/环境变量接线的维护 happy path。
20. 仅当 `verbose` 日志不够时，才在 `detox run-server` 上使用 `-l trace`。
21. 原生 SwiftUI app 的最小 Detox 配置通常包含：`const server = process.env.DETOX_SERVER || 'ws://localhost:8099'; const sessionId = process.env.DETOX_SESSION_ID || 'limrun-detox'; module.exports = { testRunner: { args: { $0: 'jest' }, jest: { setupTimeout: 120000 } }, session: { server, sessionId, debugSynchronization: 0 }, apps: { ios: { type: 'ios.app', binaryPath: 'unused-by-limrun' } }, devices: { limrun: { type: '@limrun/detox/driver', device: { id: process.env.LIMRUN_IOS_ID } } }, configurations: { 'ios.limrun': { device: 'limrun', app: 'ios', behavior: { init: { reinstallApp: false }, cleanup: { shutdownDevice: false } } } } };`
22. 对于该 SwiftUI 配置，用 `lim ios launch-app <bundle-id> --runtime detox ...` 启动，并运行 `npx detox test --no-start`。
23. 验证 app 已连接：`detox run-server` 日志出现 `role:"app"` 和 `appConnected:true`。
24. 验证 tester 已连接：同一 session 达到 `testerConnected:true, appConnected:true`。
25. 验证 runtime 已加载：app 在 `--runtime detox` 启动后连接到 mediator。
26. 验证 UI 可见：`lim ios element-tree --id <ios-id>` 显示预期 app 屏幕。
27. 不要传任意环境变量、app 参数或可注入路径；使用 `--runtime detox`。
28. `--detox-version` 应匹配 tester 使用的本地 `detox` 包版本；省略时 `lim ios launch-app` 会从当前工作目录解析，在 Detox 项目外运行时应显式传入。
29. 不支持的 bundled Detox 版本应失败并给出清晰的支持版本列表。
30. `Cannot forward the message to the Detox client` 可能只是 app 比 tester 先连接。
31. 对 SwiftUI，优先使用稳定的 accessibility identifiers，例如 `.accessibilityIdentifier("greetingText")` 配合 `by.id('greetingText')`；`by.text(...)` 可能错过 `lim ios element-tree` 中出现的 label。
32. 调试失败时先检查 `lim ios element-tree --id <ios-id>`，再查看 mediator 日志中的 app/tester 连接状态。
33. 清理手动运行：停止 `detox run-server`，运行 `lim ios tunnel stop --id <ios-id>`，并用 `lim ios delete <ios-id>` 删除实例（`delete` 不接受 `--id`）。
34. 注意 Detox 不接管 iOS 生命周期；需单独准备或复用 Limrun 实例。

适用边界 · 注意事项

• 不适用于需要原生 iOS 构建的场景；除非明确要求，应将构建问题分开处理。
• 不适用于不使用 Limrun iOS 实例、lim CLI 或 @limrun/detox driver 的环境。
• 不要期望 Detox 接管 iOS 生命周期；未单独准备或复用 Limrun 实例时不要用此流程。