Detox/docs/Introduction.GettingStarted.md

id, title

id	title
Introduction.GettingStarted	Getting Started

This guide is focused on iOS. For installing Detox for Android, be sure to also go over the Android guide.

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

Prerequisites

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)

• A working React Native app you want to test

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.

• Jest

npm install jest --save-dev

Read the Jest integration guide for more details and gotchas.

• Mocha

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/example.app",
      "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", example.app 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.