Welcome to Detox!
In this guide, we will walk you through setting Detox up in your project, one step at a time.
You will find that some steps are longer than the others: some are just one-paragraph long, while for others we have a dedicated multistep guide worked out. Bear with us - it is all necessary, and once set-up, it is easy to move forward with writing tests very rapidly.
Step 1: Environment Setup
v12.0 or above.
There’s more than one way to install Node.js:
- Download from the official download page
- Use Homebrew
nvm- if you need to allow for several versions to be installed on a single machine
The simplest way is to use Homebrew:
brew install node
Tip: Verify installation succeeded by typing in
node -vin the terminal to output current node version.
Install Detox Command Line Tools (
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 your npm scripts.
detox-cli is merely a script that passes commands through to a command line tool shipped inside
detox package (in
npm install -g detox-cli
Install Platform-specific Dependencies, Tools and SDKs
Depending on the platform/s you’re aiming at (iOS, Android), take the time to run through these environment setup guides:
Step 2: Add Detox to Your Project
Install the Detox Node-module
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 in
package.json and then run the following command:
npm install detox --save-dev --no-package-lock
You should now have Detox available in
Tip: Remember to add the
node_modulesfolder to your git ignore file (e.g.
Set Up a Test Runner
Mocha out of the box. You need to choose and set up one of them now, but it is possible to switch later on, should you change your mind.
- Jest is the recommended test runner for use with Detox, since it provides parallel test execution and a complete lifecycle integration with Detox. To set up, follow our comprehensive guide for Jest.
- Mocha, albeit its integration is less complete, is still lightweight, and a bit easier to set up. To set up, follow our guide for Mocha.
Note: Detox is coupled to neither Mocha or Jest, nor with a specific directory structure. Both runners are just a recommendation — with some effort, they can be replaced without touching the internal implementation of Detox itself.
Apply Detox Configuration
If you’ve completed the test-runner setup successfully using
detox init, you should have a
.detoxrc.json file containing a skeletal configuration for Detox to use. This configuration is only half-baked and needs to be set up properly. You now need to either create or edit that file, and apply the actual configuration suitable for your specific project.
Detox scans for a configuration through multiple files. It starts from the current working directory, and runs over the following options, in this order:
If you prefer to use something other than
.detoxrc.json—for example, would like to keep all project configs in one place—you can create a
detox section in your
package.json. If you otherwise prefer separating configs, all of the other options are valid.
For specific configuration options for each supported platform, see:
Step 3: 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 --configuration <your configuration name>
Note: Detox executes the build command you specified in your Detox configuration. If your build fails, make sure to provide the correct build command.
2. Run the Tests
Use the Detox command line tools to test your project easily:
detox test --configuration <your configuration name>
That’s it. Your first failing Detox test is running!
Next, we’ll go over usage and how to make this test actually pass.