Skip to content

Latest commit

 

History

History
194 lines (124 loc) · 6.89 KB

Introduction.GettingStarted.md

File metadata and controls

194 lines (124 loc) · 6.89 KB
Raw

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 High Sierra 10.13.6)

  • Xcode 10.2+ 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.

To ensure everything needed for Homebrew tool installation is installed, run

xcode-select --install

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. 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",
      "device": {
        "type": "iPhone 11 Pro"
      }
    }
  }
}

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 React Native 0.60 or above, or any other 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 device.type (e.g. iPhone 11 Pro 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.

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

1. Install a test runner 🏃‍♂️

Detox CLI supports Jest and Mocha out of the box. You need to choose one now, but it is possible to replace it later on.

Do note that:

  • Jest is more complex to set up, but it's the only one that supports parallel tests execution. In Detox 12.7.0, we've made Jest more suitable for e2e testing in terms of logging and usability.
  • Mocha is easy to set up and is lightweight.

Jest:

npm install jest --save-dev

Mocha:

npm install mocha --save-dev

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.

2. Set up test-code scaffolds (automated) 🏗️

The Detox CLI has a detox init convenience method to automate a setup for your first test. Depending on your test runner of choice, run one of these commands:

Jest:

detox init -r jest

Mocha:

detox init -r mocha

For a Jest-based environment, please pause and run through the comprehensive Jest setup guide.

Note: detox init runs these steps, which you can reproduce manually:

  • Creates an e2e/ folder in your project root
  • Inside e2e folder, creates mocha.opts (for mocha) or config.json (for jest). See examples: mocha.opts, config.json
  • Inside e2e folder, creates init.js file. See examples for Mocha and Jest.
  • Inside e2e folder, creates firstTest.spec.js with content similar to this.

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.

Step 5: Android Setup

If you haven't already done so - now is the time to set Android up using the Android guide.