limrun-detox-testing

Limrun Detox

将此内容用于 Limrun iOS 上的 Detox 运行时工作。除非用户明确要求原生构建，否则请将构建相关事项分开处理。

组件

• 测试器：本地 Node/Jest/Detox 进程。
• 中介：detox run-server，通常在 Agent 机器本地运行。
• 应用客户端：由 limulator 通过 lim ios launch-app --runtime detox 注入。

CLI 流程

运行本次会话中未使用过的命令前，请先查看当前帮助信息：

lim ios tunnel --help
lim ios launch-app --help

请在不同终端中分别运行长驻的中介、测试器和隧道。 使用此快捷流程前，请确保项目的 .detoxrc 会读取会话环境变量。 Detox 不会自动读取这些变量：

session: {
  server: process.env.DETOX_SERVER || 'ws://localhost:8099',
  sessionId: process.env.DETOX_SESSION_ID || 'limrun-detox',
}

完整配置见下文的 Detox 测试设置。

终端 1：

npx detox run-server -p 8099 -l verbose

终端 2：

lim ios tunnel \
  --selector localhost:8099 \
  --detach \
  --id <ios-id>
DETOX_SERVER_URL="ws://localhost:8099"

终端 3 在应用连接前启动测试器：

DETOX_SERVER="ws://localhost:8099" \
DETOX_SESSION_ID=<session-id> \
  npx detox test --no-start

然后从终端 2 重新启动应用。若在包含 node_modules/detox 的项目中运行，--detox-version 为可选项。

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>

建议在应用连接前启动测试器，或使用 limrun-inc/typescript-sdk examples/detox-ios 中维护的编排流程，以避免出现无害的中介“cannot forward”噪声。 如果手动启动应用后再运行 npx detox test --no-start，那么在测试器连接前出现该中介消息是正常的。

如果启动隧道时提示有活动会话，请使用 lim ios tunnel status --id <ios-id> --json 检查。使用 lim ios tunnel stop --id <ios-id> 停止过时会话，然后重新启动已声明的中介选择器。 空闲的开放隧道不计为实例活动，因此不会阻止模拟器在测试运行间隔期间触发不活动超时。

Detox 测试设置

npx detox test --no-start 仍需要常规 Detox 项目配置：

• 使用项目中的 Detox 配置文件和配置名称（参考 examples/detox-ios/.detoxrc.cjs in limrun-inc/typescript-sdk 中的布局）。
• 使用 Limrun 第三方驱动：type: '@limrun/detox/driver'。
• 确保 DETOX_SERVER 和 DETOX_SESSION_ID 与中介及启动命令保持一致。
• 当截图或驱动调用需要实例 API 时，提供 Limrun 驱动环境变量，例如 LIMRUN_IOS_ID、LIMRUN_IOS_API_URL 和 LIMRUN_IOS_TOKEN。

精确的配置和环境变量接线方式，请使用 limrun-inc/typescript-sdk examples/detox-ios 中维护的推荐流程。只有在详细日志仍不够时，才对 detox run-server 使用 -l trace。

对于原生 SwiftUI 应用，最简 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 } },
    },
  },
};

然后使用 lim ios launch-app <bundle-id> --runtime detox ... 启动，并运行 npx detox test --no-start。

验证信号

• 应用已连接：detox run-server 日志显示 role:"app" 和 appConnected:true。
• 测试器已连接：同一会话显示 testerConnected:true, appConnected:true。
• 运行时已加载：使用 --runtime detox 启动后，应用连接到中介。
• UI 可见：lim ios element-tree --id <ios-id> 显示预期的应用屏幕。

注意事项

• 不要传入任意环境变量、应用参数或可注入路径。请使用 --runtime detox。
• --detox-version 应与测试人员使用的本地 detox 包版本一致。如果省略，lim ios launch-app 会从当前工作目录解析该版本；在 Detox 项目外运行时，请显式传入。
• 不支持的内置 Detox 版本应明确列出受支持的版本并报错。
• Cannot forward the message to the Detox client 可能只是表示应用在测试人员连接之前就已连接。
• 对于 SwiftUI，优先使用稳定的辅助功能标识符，例如 .accessibilityIdentifier("greetingText") 搭配 by.id('greetingText')；by.text(...) 可能无法找到出现在 lim ios element-tree 中的标签。
• 调试失败时，先检查 lim ios element-tree --id <ios-id>，然后查看中介程序日志，确认应用和测试人员的连接状态。
• 清理手动运行时，停止 detox run-server，运行 lim ios tunnel stop --id <ios-id>，并使用 lim ios delete <ios-id> 删除实例（--id 不能用于 delete）。
• 这不会让 Detox 接管 iOS 生命周期；请单独准备或重用 Limrun 实例。