Apps

The format of Detox config allows you to define inside it multiple app configs in a key-value manner, i.e.:

Location

You can define the app config in two ways: aliased and inlined (per a configuration):

.detoxrc.js

/** @type {Detox.DetoxConfig} */
module.exports = {
  apps: {
    appKey: {
      /* … app config … */
    }
  },
  /* … */
  configurations: {
    'example.aliased': {
      /* … */
      app: 'appKey', // (1)
    },
    'example.inlined': {
      /* … */
      app: { // (2)
        /* … app config … */
      },
    },
  },
};

Examples

ios.app

{
  "type": "ios.app",
  "binaryPath": "ios/build/Build/Products/Debug-iphonesimulator/example.app",
  "build": "xcodebuild -project ios/example.xcodeproj -scheme example -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build"
}

android.apk

{
  "type": "android.apk",
  "binaryPath": "path/to/myApp.apk",
  "build": "cd android && ./gradlew …"
}

Properties

An app config can have the following params:

Configuration Params	Details
type	Mandatory property to discern app types: ios.app, android.apk.
name	Use only when working with multiple apps within the same configuration. See an example below.
binaryPath	Relative path to the ipa/app/apk due to be tested (make sure you build the app in a project relative path)
build	[optional] Build command, which can be called using detox build CLI as a convenience.
start	[optional] Start command, which will be called before detox test CLI starts, or explicitly via detox start command.
testBinaryPath	(optional, Android only): relative path to the test app (apk)
launchArgs	[optional] An object specifying arguments (key-values pairs) to pass through into the app, upon launching on the device. For more info, refer to the dedicated launch-arguments guide.
reversePorts	(optional, Android only) An array of TCP ports to reverse, so that the network requests to localhost:{port} on Android device are going to be forwarded to the host machine.
arch	(optional, iOS only) Launch architecture for the simulator: x86_64 or arm64. Passes --arch to xcrun simctl launch, selecting which slice of a universal binary to run. Requires Xcode 26+ Universal simulator runtime for x86_64 on Apple Silicon.

Multiple apps

To work with multiple apps within the same configuration you should be giving each app its name, e.g.:

{
  "apps": {
    "driver.ios.release": {
      "type": "ios.app",
      "name": "driver",
      "binaryPath": "path/to/driver.app"
    },
    "passenger.ios.release": {
      "type": "ios.app",
      "name": "passenger",
      "binaryPath": "path/to/passenger.app"
    }
  },
  "configurations": {
    "ios.release": {
      "device": "simulator",
      "apps": ["driver", "passenger"],
      "build": "scripts/build-both-apps.sh",
      "start": "scripts/start-both-apps.sh"
    }
  }
}

After that, you can change the current app in your tests via device API:

await device.selectApp('driver');
await device.launchApp();
// ... run tests ...
await device.selectApp('passenger');
await device.launchApp();
// ... run tests ...

As shown in the example above, you can override app build and start commands with a single, configuration-scoped one. This may be useful when you have smart scripts for building and starting multiple apps at once.