---
name: limrun-detox-testing
description: 在 Limrun iOS 模拟器上配置、运行或调试 Detox。用于为应用挂接 Limrun Detox 运行时、连接 Detox mediator 或经反向隧道校验应用/测试器连接。
en_description: Configure, run, or debug Detox on Limrun iOS simulators. Use when attaching the Limrun Detox runtime to an app, wiring Detox mediator connectivity, or validating app/tester connections over reverse tunnels.
zh_displayName: Limrun Detox 测试
category: 移动端开发
en_category: Mobile Dev
user-invocable: true
---
# Limrun Detox

Use this for Detox runtime work on Limrun iOS. Keep build concerns separate unless the user explicitly asks for a native build.

## Components

- Tester: local Node/Jest/Detox process.
- Mediator: `detox run-server`, usually local to the agent machine.
- App client: injected by limulator through `lim ios launch-app --runtime detox`.

## CLI Flow

Check current help before running commands you have not used in this session:

```bash
lim ios reverse --help
lim ios launch-app --help
```

Typical sequence:

```bash
# Start the Detox mediator locally.
npx detox run-server -p 8099 -l verbose

# Expose the mediator to the simulator.
lim ios reverse 57091:8099 --id <ios-id>

# Relaunch the app with the managed Detox runtime. Use the remote endpoint
# printed by `lim ios reverse`, not 127.0.0.1 on the user machine.
# --detox-version is optional when running from the project with node_modules/detox.
lim ios launch-app <bundle-id> \
  --id <ios-id> \
  --runtime detox \
  --detox-server-url ws://<reverse-remote-host>:57091 \
  --detox-session-id <session-id> \
  --detox-version <detox-version>

# Run the tester with the same server/session.
npx detox test --no-start
```

Prefer starting the tester before the app connects, or use the maintained orchestration in [limrun-inc/typescript-sdk `examples/detox-ios`](https://github.com/limrun-inc/typescript-sdk/tree/main/examples/detox-ios), to avoid benign mediator "cannot forward" noise.
If you manually launch the app before `npx detox test --no-start`, that mediator message is expected until the tester connects.

If `lim ios reverse` reports the port is `already in use`, first kill any leftover `lim ios reverse` process from an earlier run; a port whose session died uncleanly frees on its own within about two minutes, so wait and retry rather than switching ports. An open idle tunnel does not count as instance activity, so it will not stop the instance's inactivity timeout between runs.

## Detox Test Setup

`npx detox test --no-start` still needs the normal Detox project configuration:

- Pass the Detox config file and configuration name from your project (see [`examples/detox-ios/.detoxrc.cjs` in limrun-inc/typescript-sdk](https://github.com/limrun-inc/typescript-sdk/blob/main/examples/detox-ios/.detoxrc.cjs) for a reference layout).
- Use the Limrun third-party driver: `type: '@limrun/detox/driver'`.
- Keep `DETOX_SERVER` and `DETOX_SESSION_ID` aligned with the mediator and launch command.
- Provide Limrun driver env such as `LIMRUN_IOS_ID`, `LIMRUN_IOS_API_URL`, and `LIMRUN_IOS_TOKEN` when screenshots or driver calls need the instance API.

Use [limrun-inc/typescript-sdk `examples/detox-ios`](https://github.com/limrun-inc/typescript-sdk/tree/main/examples/detox-ios) as the maintained happy path for exact config/env wiring. Use `-l trace` on `detox run-server` only when verbose logs are not enough.

For native SwiftUI apps, a minimal Detox configuration usually looks like:

```js
module.exports = {
  testRunner: { args: { $0: 'jest' }, jest: { setupTimeout: 120000 } },
  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 } },
    },
  },
};
```

Then launch with `lim ios launch-app <bundle-id> --runtime detox ...` and run `npx detox test --no-start`.

## Validation Signals

- App connected: `detox run-server` logs `role:"app"` and `appConnected:true`.
- Tester connected: the same session reaches `testerConnected:true, appConnected:true`.
- Runtime loaded: the app connects to the mediator after the `--runtime detox` launch.
- UI visible: `lim ios element-tree --id <ios-id>` shows the expected app screen.

## Gotchas

- Do not pass arbitrary env vars, app args, or injectable paths. Use `--runtime detox`.
- `--detox-version` should match the local `detox` package version used by the tester. If omitted, `lim ios launch-app` resolves it from the current working directory; pass it explicitly when running outside the Detox project.
- Unsupported bundled Detox versions should fail with a clear supported-version list.
- `Cannot forward the message to the Detox client` can simply mean the app connected before the tester did.
- For SwiftUI, prefer stable accessibility identifiers, e.g. `.accessibilityIdentifier("greetingText")` with `by.id('greetingText')`; `by.text(...)` can miss labels that appear in `lim ios element-tree`.
- Debug failures by checking `lim ios element-tree --id <ios-id>` first, then mediator logs for app/tester connection state.
- Cleanup manual runs by stopping `detox run-server`, stopping `lim ios reverse`, and deleting the instance with `lim ios delete <ios-id>` (`--id` is not valid for delete).
- This does not make Detox own the iOS lifecycle; prepare or reuse the Limrun instance separately.