Detox/docs/config/apps.mdx

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

## Location

<Location sectionName="apps" propertyName="app" />

## Examples

<Tabs groupId="mobileOS">
  <TabItem value="ios.app" label="ios.app" default>

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

  </TabItem>
  <TabItem value="android.apk" label="android.apk">

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

  </TabItem>
</Tabs>

## 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](../guide/launch-args.md).                                                                      |
| `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.:

```js
{
  "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](../api/device.md):

```js
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.

[`detox build`]: ../cli/build.md
[`detox start`]: ../cli/start.md
[`detox test`]: ../cli/test.md