limrun-detox-testing

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:

lim ios reverse --help
lim ios launch-app --help

Typical sequence:

# 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 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 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 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:

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.