Setting up Detox in a React Native project connects the app build, simulator or emulator target, and Jest runner so end-to-end tests can install the app and drive real UI screens. It is useful after the native project already builds from the command line and before a larger Detox test suite is written.

Detox keeps this wiring in .detoxrc.js and an e2e/ test folder. The initializer creates starter files for Jest, apps, devices, and named configurations, but the generated app names, binary paths, build commands, and device names still need to match the project.

Using npm and the local Detox binary through npx avoids a global Detox CLI install. An iOS simulator debug build proves one local configuration without turning project setup into a full Android native patching workflow.

Related: How to set up an Android emulator environment for Detox
Related: How to write a first Detox test
Related: How to run Detox tests locally

Steps to set up Detox in a React Native project:

  1. Open a terminal in the React Native project root.
  2. Install Jest and Detox as development dependencies. 
    $ npm install "jest@^29" detox --save-dev
added 387 packages, and audited 388 packages in 13s

##### snipped #####

Run `npm audit` for details.

    The Jest 29 range follows the current Detox project setup recommendation and avoids older lockfile-pinned Jest releases.

  3. Create the Detox starter configuration and test files. 
    $ npx detox init
Created a file at path: .detoxrc.js
Created a file at path: e2e/jest.config.js
Created a file at path: e2e/starter.test.js
  4. Confirm that the initializer wrote the expected project files. 
    $ ls -la .detoxrc.js e2e/jest.config.js e2e/starter.test.js
-rw-r--r--  1 user  staff  2153 Jun 18 12:50 .detoxrc.js
-rw-r--r--  1 user  staff   407 Jun 18 12:50 e2e/jest.config.js
-rw-r--r--  1 user  staff   629 Jun 18 12:50 e2e/starter.test.js
  5. Replace the generated iOS app placeholders in .detoxrc.js.
    .detoxrc.js
    /** @type {Detox.DetoxConfig} */
module.exports = {
  testRunner: {
    args: {
      '$0': 'jest',
      config: 'e2e/jest.config.js'
    },
    jest: {
      setupTimeout: 120000
    }
  },
  apps: {
    'ios.debug': {
      type: 'ios.app',
      binaryPath: 'ios/build/Build/Products/Debug-iphonesimulator/Example.app',
      build: 'xcodebuild -workspace ios/Example.xcworkspace -scheme Example -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build'
    }
  },
  devices: {
    simulator: {
      type: 'ios.simulator',
      device: {
        type: 'iPhone 15'
      }
    }
  },
  configurations: {
    'ios.sim.debug': {
      device: 'simulator',
      app: 'ios.debug'
    }
  }
};

    Replace Example with the actual app scheme and product name. If the project does not use CocoaPods, change -workspace to the matching Xcode project path.

  6. List installed iOS simulator device types before keeping the generated device name. 
    $ xcrun simctl list devicetypes
== Device Types ==
iPhone 14 (com.apple.CoreSimulator.SimDeviceType.iPhone-14)
iPhone 15 (com.apple.CoreSimulator.SimDeviceType.iPhone-15)
iPhone 15 Pro (com.apple.CoreSimulator.SimDeviceType.iPhone-15-Pro)
##### snipped #####
  7. Update the simulator device type if the generated type is not installed.
    .detoxrc.js
    devices: {
  simulator: {
    type: 'ios.simulator',
    device: {
      type: 'iPhone 15'
    }
  }
}

    Use one of the device type names printed by xcrun simctl list devicetypes.

  8. Build the selected Detox configuration. 
    $ npx detox build --configuration ios.sim.debug
detox[build] running command: xcodebuild -workspace ios/Example.xcworkspace -scheme Example -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build
##### snipped #####
** BUILD SUCCEEDED **

    Run pod install in ios/ first when the app uses CocoaPods and the workspace or Pods project is missing.

  9. Start Metro in a second terminal so the debug build can load its JavaScript. 
    $ npm start
  10. Run the generated starter test to confirm that Detox can launch the app. Example output: 
    $ npx detox test --configuration ios.sim.debug
 FAIL  e2e/starter.test.js (25.916 s)
  Example
    ✕ should have welcome screen (662 ms)
    ✕ should show hello screen after tap (236 ms)
    ✕ should show world screen after tap (236 ms)

  ● Example > should have welcome screen

    Test Failed: No elements found for “MATCHER(id == “welcome”)”
##### snipped #####

    A No elements found failure on the unchanged e2e/starter.test.js means the setup works: Detox launched the app and reached sample IDs such as welcome and hello_button, which the app does not define yet.
    Related: How to write a first Detox test

Share this guide