Switch branches/tags
CFRunLoopPerformBlock DITests DisableTouchIndicators GenerateUIDeviceAPI InlineRequirePlayground RefineWXRNLoadIdlingResource StreamlinedMatchers Xcode10 add_aar_archive additionalWindow android_layout androidNativeE2E buttonIdlingFix danielmschmidt/ast-based-java-parser danielmschmidt/danielmschmidt/move-expect-to-generated-code-second-try danielmschmidt/eslint-enable-on-ci danielmschmidt/expect-to-generated-second danielmschmidt/generated-documentation danielmschmidt/ios-driver-to-generated-code danielmschmidt/move-cli-to-gluegun-second-try danielmschmidt/move-cli-to-gluegun danielmschmidt/move-expect-to-generated-code-2 danielmschmidt/move-expect-to-generated-code danielmschmidt/move-ios-driver-to-generated-code danielmschmidt/platform-parity-object-oriented danielmschmidt/replace-commander-with-argparse danielmschmidt/use-git-submodule-instead-of-downloading-files docs/e2e-update dp_testPasteBoard feat/take-screenshot gh-pages kotlin-rntimer-idling-resource make-use-of-template-literal master matchOnlyVisibleViews mbardauskas-patch-1 newFunctionalityForDatePickerIOS noomorph/artifacts/alternative-simulator-log-plugin noomorph/cleanup-temporary-files-on-start noomorph/draft/detox-runner-modules noomorph/fix-crlf-grep-issue noomorph/fix-stability-android noomorph/fix/artifacts-with-launch-app-false noomorph/issue-853 poc-uniform-interface publishFatJar test_default_api_emulator timers-ir-skip-over-repeat website/side-by-side website/versions yedidyak-patch-1
Nothing to show
Find file Copy path
178 lines (112 sloc) 6.21 KB
id title
Getting Started

This is a step-by-step guide for adding Detox to your React Native project.

TIP: You can also check out this awesome tutorial on Medium with video by @bogomolnyelad


Running Detox (on iOS) requires the following:

  • Mac with macOS (at least macOS El Capitan 10.11)

  • Xcode 8.3+ with Xcode command line tools

TIP: Verify Xcode command line tools is installed by typing gcc -v in terminal (shows a popup if not installed)

Step 1: Install dependencies

1. Install the latest version of Homebrew

Homebrew is a package manager for macOS, we'll need it to install other command line tools.

TIP: Verify it works by typing in terminal brew -h to output list of available commands

2. Install Node.js

Node is the JavaScript runtime Detox will run on. Install Node 8.3.0 or above

brew update && brew install node

TIP: Verify it works by typing in terminal node -v to output current node version, should be 8.3.0 or higher

3. Install applesimutils

A collection of utils for Apple simulators, Detox uses it to communicate with the simulator.

brew tap wix/brew
brew install applesimutils

TIP: Verify it works by typing in terminal applesimutils to output the tool help screen

4. Install Detox command line tools (detox-cli)

This package makes it easier to operate Detox from the command line. detox-cli should be installed globally, enabling usage of the command line tools outside of your npm scripts. detox-cli is merely a script that passes commands through to a the command line tool shipped inside detox package (in node_modules/.bin/detox).

npm install -g detox-cli

Step 2: Add Detox to your project

1. Install detox

If you have a React Native project, go to its root folder (where package.json is found) and type the following command:

npm install detox --save-dev

If you have a project without Node integration (such as a native project), add the following package.json file to the root folder of your project:

  "name": "<your_project_name>",
  "version": "0.0.1"

Now run the following command:

npm install detox --save-dev

TIP: Remember to add the "node_modules" folder to your git ignore.

2. Install a test runner

You can use any JavaScript test runner. Detox CLI supports Jest and Mocha out of the box.

npm install jest --save-dev

Read the Jest integration guide for more details and gotchas.

npm install mocha --save-dev

3. Add Detox config to package.json

The basic configuration for Detox should be in your package.json file under the detox property:

"detox": {
  "configurations": {
    "ios.sim.debug": {
      "binaryPath": "ios/build/Build/Products/Debug-iphonesimulator/",
      "build": "xcodebuild -project ios/example.xcodeproj -scheme example -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build",
      "type": "ios.simulator",
      "name": "iPhone 7"

In the above configuration example, change example to your actual project name. Under the key "binaryPath", should be <your_project_name>.app. Under the key "build", example.xcodeproj should be <your_project_name>.xcodeproj and -scheme example should be -scheme <your_project_name>.

For iOS apps in a workspace (eg: CocoaPods) use -workspace ios/example.xcworkspace instead of -project.

Also make sure the simulator model specified under the key "name" (iPhone 7 above) is actually available on your machine (it was installed by Xcode). Check this by typing xcrun simctl list in terminal to display all available simulators.

TIP: To test a release version, replace 'Debug' with 'Release' in the binaryPath and build properties. For full configuration options see Configuration under the API Reference.

Step 3: Create your first test

Detox has detox init convenience method to automate a setup for your first test.
At the moment, such scaffolding is supported for two test runners:

  • detox init -r mocha
  • detox init -r jest

In itself, detox init makes a few steps which you can reproduce manually:

  • Create an e2e folder in your project root
  • Inside e2e folder create mocha.opts (for mocha) or config.json (for jest). See examples: mocha.opts, config.json
  • Inside e2e folder create init.js file. See examples for Mocha and Jest.
  • Inside e2e folder create firstTest.spec.js with content similar to this.
  • If you use jest, add "test-runner": "jest" to detox section in your package.json (see example).

TIP: Detox is not tightly coupled to Mocha and Jest, neither to this specific directory structure. Both are just a recommendation and are easy to replace without touching the internal implementation of Detox itself.

Step 4: Build your app and run Detox tests

1. Build your app

Use a convenience method in Detox command line tools to build your project easily:

detox build

TIP: Notice that the actual build command was specified in the Detox configuration in package.json .
See "build": "xcodebuild -project ..." inside ios.sim.debug configuration (step 2.3).

2. Run the tests (finally)

Use the Detox command line tools to test your project easily:

detox test

That's it. Your first failing Detox test is running!

Next, we'll go over usage and how to make this test actually pass.