Apps

March 20, 2026 · View on GitHub

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

import Location from './partials/_location-dictionaries.mdx';

Apps

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

Examples

{
  "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"
}

{
  "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.