Skip to main content
Version: 19.x

Detox for iOS

Detox for iOS

1. Preliminary

Run through the basic steps of the Getting Started guide, such as the environment and tools setup.

2. Apply Detox Configuration

Whether you’ve selected to apply the configuration in a .detoxrc.json or bundle it into your project’s package.json (under the detox section), this is what the configuration should roughly look like for iOS:

"devices": {
"simulator": {
"type": "ios.simulator",
"device": {
"type": "iPhone 12 Pro Max"
"apps": {
"ios.release": {
"name": "YourProject",
"type": "",
"binaryPath": "ios/build/Build/Products/Release-iphonesimulator/",
"build": "xcodebuild -project ios/YourProject.xcodeproj -scheme YourProject -sdk iphonesimulator -derivedDataPath ios/build"
"configurations": {
"ios.sim.release": {
"device": "simulator",
"app": "ios.release"

For a comprehensive explanation of Detox configuration, see our dedicated API-reference guide.

In the above configuration example, make sure to provide the correct information for your project/app. Under the key "binaryPath", you should provide the path of the .app bundle to use. Normally, this is the path where the "build” command would output this bundle. Under the key "build", specify the xcodebuild command for your project.


If your app uses CocoaPods, pass -workspace in your xcodebuild command, for example:

"build": "xcodebuild -workspace ios/YourProject.xcworkspace -scheme YourProject -sdk iphonesimulator -derivedDataPath ios/build"

For more information on using the xcodebuild command, visit Apple Docs.

Also, make sure the simulator model specified under the key device.type (e.g. iPhone 12 Pro Max above) is actually available on your machine (it was installed by Xcode). Check this by typing applesimutils --list in Terminal to display all available simulators.

For a complete, working example, refer to the Detox example project configuration.