Join the webinar on ‘Using HeadSpin APIs to Manage Applications’ on July 23rd.
End-to-End Detox Testing - A Complete Guide

Guide to End-to-End Detox Testing

July 3, 2023
Sreenadh BalasundaramSreenadh Balasundaram
Sreenadh Balasundaram


In the dynamic world of mobile app development, delivering exceptional user experiences and ensuring top-notch quality in React Native applications is essential. Enter Detox automation testing—an invaluable tool designed specifically for React Native. With streamlined testing processes, Detox empowers developers to optimize development cycles and confidently deliver high-performing applications.

This blog explores the immense potential of Detox automation testing for React Native applications using HeadSpin devices. Whether you're a React Native developer or a seasoned QA professional, this blog equips you with the knowledge to harness the power of Detox automation testing effectively.

What is Detox Testing?

Detox testing, a gray box testing framework, empowers developers by automating the testing process for mobile applications. Unlike black box testing, where the internal structure remains a mystery, Detox testing offers a deeper understanding of the app's behavior, making it a top choice for React Native app developers. This method significantly enhances testing accuracy and efficiency, ensuring your app is robust and user-friendly.

Detox testing excels in its ability to replicate a user-like environment, interacting with the app just as a real user would. This real-world applicability is crucial for identifying issues that might escape notice in other types of testing. By incorporating Detox testing into your development process, you're not just testing; you're bolstering the overall quality and reliability of your application.

Steps for Setting up a Detox Testing Project

  • Setting up Detox is a breeze: Run npm install detox --save-dev in your project directory. This command will add Detox as a dev dependency for your project, easily getting you started on your Detox testing journey.
  • Configure Detox: After installation, you need to configure Detox for your project. This involves setting up the test runner and the simulator. The Detox configuration is specified in your package.json file, allowing Detox to understand how to interact with your app.
  • Write Tests: With Detox installed and configured, you can start writing your tests. Detox tests are written in JavaScript and are designed to mimic user interactions with your app. From tapping buttons to entering text, you can script a series of actions to test various features of your application.
  • Run Tests: Running your tests is as simple as executing a command in your terminal. Detox provides a CLI that makes it easy to launch your tests. Once triggered, Detox will interact with your app on the simulator, executing the predefined actions and checking the expected outcomes.
  • Integrate with HeadSpin: To take your Detox testing to the next level, integrate it with HeadSpin devices. This will allow you to run your tests on various real devices, providing invaluable insights into your app's performance in different environments.

Detox Automation Framework: Overview and Key Features

Detox stands out as a robust automation framework in JavaScript mobile testing. Detox's unique integration directly into the application sets it apart, enabling test execution right from the app's launch. This approach ensures fast and robust test execution, eliminating the need for external tools to orchestrate and synchronize tests.

As the demand for high-velocity native mobile development rises, embracing continuous integration workflows becomes crucial. Manual QA reliance must decrease significantly. With the Detox test automation, your mobile app undergoes testing while actively running on a real device for Android or an emulator for Android, or a simulator for iOS, mimicking real user interactions. This comprehensive approach ensures thorough testing coverage.

End-to-end (E2E) tests, the pinnacle of mobile automated testing, often need to be more flexible, introducing uncertainty and hindering reliability. Detox addresses this issue by shifting from black-box testing to a more powerful gray-box testing approach. By gaining deeper insights into the application's internal workings, the Detox automation tool tackles the flakiness of E2E testing head-on, leading to more reliable and consistent test outcomes.

Key Features of Detox Automation Framework

  • Specialized Focus: Detox is purpose-built for Detox React Native applications, providing targeted features and optimizations for this framework.
  • Asynchronous Handling: Detox manages asynchronous operations seamlessly, ensuring accurate and thorough testing of Detox React Native apps.
  • UI Synchronization: Detox synchronizes with the application's UI, promoting stable and consistent test execution, reducing flakiness, and minimizing false positives.
  • Architecture: Detox comprises the Detox server and the Detox client, with the server managing and coordinating the testing process while the client is embedded within the Detox React Native application.
  • Native Automation APIs: Detox utilizes platform-specific automation APIs like Espresso for Android and XCTest-based EarlGrey v1 for iOS to interact with the application's UI elements and simulate user actions.
  • JavaScript Injection: Detox injects a JavaScript bridge into the runtime environment of the Detox React Native application, facilitating communication between the Detox server and client components.
  • Test Runner and Configuration: Detox provides a command-line interface (CLI) and a test runner that orchestrates the execution of test suites. Developers can configure Detox with various options, including device selection, test timeout settings, and custom test environment configurations.
  • Parallel Test Execution: Detox supports running multiple tests simultaneously, significantly reducing testing time and accelerating the overall development cycle.
  • Debugging: With Detox's modern async-await API, breakpoints within asynchronous tests function as expected, enabling developers to troubleshoot and debug their test scripts efficiently.
  • Reporting and Logging: Detox provides detailed reporting and logging features, offering comprehensive insights into test execution and facilitating effective issue identification and troubleshooting.
Learn more: 5 Popular Test Automation Tools for React Native Apps

Most Common Challenges that Developers Face During Detox Test Automation

Understanding the challenges of the Detox automation framework is crucial for effectively utilizing it and ensuring successful test automation. 

Here are some of the common complexities of Detox test automation:

1. Environment Setup

Setting up the test environment for Detox can be complex, involving the installation of various dependencies and configurations. Ensuring the required software, development tools, and mobile device configurations are properly aligned can be time-consuming.

2. Test Maintenance

Test scripts built with Detox may require updates and maintenance as applications evolve and undergo changes. It can be an ongoing effort to maintain test scripts to accommodate UI changes, feature enhancements, or updates to the Detox framework. Keeping test suites up to date and adapting them to new versions of React Native or Detox is necessary to maintain reliable automation.

3. Limited Platform Support

Detox primarily focuses on testing React Native applications on iOS and Android platforms. While it provides excellent support for these platforms, other mobile platforms, such as Windows or specific device models, may have limited or no official support.

4. Test Script Development

Developing test scripts for Detox requires knowledge of JavaScript, React Native, and the Detox framework. Designing comprehensive test cases, implementing synchronization logic, and handling complex scenarios can be challenging for testers new to Detox.

5. Debugging Complex Failures

When complex failures occur during Detox test automation, debugging can be time-consuming. Identifying the root cause of failures, troubleshooting synchronization issues, or addressing intermittent failures may require in-depth analysis and investigation.

Addressing these challenges requires technical expertise, thorough planning, and continuous adaptation. 

Learn more: How React Native Testing Works and Appium's Role in Automating It

Steps for Setting up a Detox Testing Project

Setting up a Detox testing project for a React Native application involves several steps to ensure smooth and efficient test automation. Here are the key steps to get you started:

Install Detox CLI and Dependencies:

First, you need to install Detox CLI globally on your system. Run the following command:

npm install -g detox-cli
Install the required dependencies in your React Native project:
npm install detox --save-dev
npm install jest --save-dev

Configure Detox in Your Project:

Add Detox configuration to your package.json file. Here is an example configuration:

"detox": {
  "configurations": {
    "ios.sim.debug": {
      "binaryPath": "ios/build/Build/Products/Debug-iphonesimulator/",
      "build": "xcodebuild -workspace ios/YourApp.xcworkspace -scheme YourApp -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build",
      "type": "ios.simulator",
      "name": "iPhone 11"

Adjust the binaryPath and build script according to your project setup.

Write Detox Tests:

Create a folder named e2e in the root of your project to store your Detox tests.

Inside the e2e folder, create a test file, for example, firstTest.spec.js, and write your test cases. Here’s a simple test example:

describe('Example', () => {
  beforeAll(async () => {
    await device.launchApp();

  it('should show welcome screen', async () => {
    await expect(element('welcome'))).toBeVisible();

Build the App for Testing:

Before running the tests, build your app using the command specified in your Detox configuration:

detox build --configuration ios.sim.debug

Run Detox Tests:

Once the app is built, you can run your Detox tests using the following command:

detox test --configuration ios.sim.debug

Integrate with CI/CD:

To integrate Detox with your CI/CD pipeline, add the Detox build and test commands to your pipeline configuration. Make sure to include the necessary steps to set up the environment on your CI/CD server.

By following these steps, you can set up a Detox testing project for your React Native application and leverage HeadSpin devices for efficient test execution.

Enhancing Detox Test Automation Capabilities Through the Seamless Integration of HeadSpin Devices

With its AI-driven capabilities, global device infrastructure, and integrations with popular automation tools, HeadSpin provides a robust infrastructure for comprehensive testing of mobile and web applications. By combining the strengths of Detox and HeadSpin (HS) devices, developers can optimize their testing workflows, improve test coverage, and achieve higher efficiency in their automation efforts.

Similar to native Espresso testing, Detox can work over HS Connect, which requires running HS Connect and the Detox server locally. Both methods require installing the app under test and the test module for Detox. Detox commands will be executed against the device over the HS Connect network. Detox requires an additional network connection over a WebSocket to send Detox commands. Running Detox tests on a device connected to a Pbox should work with both methods, and hs connect can solve any issues.


To use Detox with HS devices, follow the given steps:

1. Check and set the HS Connect server configuration.

  • Install the HS CLI tool by checking the following link:

Please note that the instructions given below are applicable for Detox versions 19.13.0 or 20.0.3 and the example project provided by Detox. Different versions may have different Detox configurations, so it is advised to check for configuration changes when using different versions. Refer to the Detox repository on GitHub:

2. Verify the prerequisites.

  • Ensure that Detox CLI is installed globally by running:

npm install detox-cli --global
  • Ensure that Node.js is installed, preferably version 7.6.0 or higher, for native async-await support. If using an older version, you'll need to transpile the tests using Babel.
  •   Install Android SDK Manager and required CLI tools using the Android Studio SDK Manager.
    android studio tools -—> sdk manager -—> sdk tools -—> install cli
  • Accept the Android Studio licenses by running:

'yes | /Users/sreenadh/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager --licenses'


3. Once the prerequisites are set up, follow the steps below to work with a sample project and run Detox:

● Install detox via npm

  • npm install -g detox@<version>

● Clone the Detox repository from GitHub to use the sample project in Detox/examples/demo-react-native here

npm install -g detox@<version>

(Note: The Detox repository is a popular open-source project used for end-to-end testing of mobile apps. It provides a framework for automating tests and simulating user interactions on both iOS and Android platforms.

To get started with Detox, you can use the example project provided in the repository. This example project serves as a template and demonstrates how to set up and configure Detox for your own mobile app.

Here's how you can use the example project from the Detox repository:

  1. Visit the Detox repository on GitHub:
  2. Clone or download the repository to your local machine.
  3. Navigate to the example project directory. In the repository, it is typically located under the examples/ folder.
  4. Open the example project in your preferred IDE or code editor.
  5. Read the README file or any documentation provided with the example project. It will guide you through the necessary steps to install dependencies, configure Detox, and run the example tests.
  6. Make any necessary adjustments to the example project to match your specific mobile app. This may involve modifying the configuration files, test scripts, or any other relevant files.
  7. Once you have set up the example project according to your needs, you can execute the tests by running the appropriate command, typically provided in the documentation.

By using the example project as a starting point, you can understand how Detox works and how to integrate it into your own mobile app testing workflow. It provides a hands-on experience and allows you to adapt the provided setup to match your specific requirements.)

● Connect to an HS device using the command:

hs connect -t <HeadSpin API Token> <HeadSpin Device>

● Update the configuration file examples/demo-react-native/detox.config.js with the appropriate app and device information. The configuration includes details for Android debug and release apps, the build commands, and the attached Android device. Use the following code:

  "apps": {
    "android.debug": {
      "type": "android.apk",
      "binaryPath": "android/app/build/outputs/apk/debug/app-debug.apk",
      "build": "cd android ; ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug ; cd -"
    "android.release": {
      "type": "android.apk",
      "binaryPath": "android/app/build/outputs/apk/release/app-release.apk",
      "build": "cd android ; ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release ; cd -"
  "devices": {
    "android.attached": {
      "type": "android.attached",
      "device": {
        "adbName": ""
  "configurations": {
    "android.att.release": {
      "device": "android.attached",
      "app": "android.release"

● Install the project dependencies in the example project by running:

npm install

● Build the app for the specified configuration by running:

detox build --configuration android.att.release

● Finally, execute the Detox tests with the command:

npx detox test --configuration android.att.release

The adbName specified in the configuration will be used to connect to the HS device.

Wrapping Up

Detox stands out as a robust and purpose-built automation framework that excels in handling asynchronous operations and ensures reliable test outcomes. By adopting a gray-box testing approach, Detox provides deeper insights into application behavior, resulting in more consistent and trustworthy test results.

To enhance the capabilities of Detox automation testing, the HeadSpin Platform's seamless Detox integration provides a powerful solution for efficient React Native App testing at scale. HeadSpin's AI-driven capabilities and global device infrastructure complement Detox, enabling developers to leverage a robust testing environment that ensures compatibility and reliability across various devices. 

Book a trial


Q1. What Does the End-to-End Testing Library in React Native Entail?

Ans: End-to-end tests verify app functionality on a device or simulator from the user's perspective. This involves building the app in release configuration and executing tests to ensure it works as expected.

Q2. What are the steps to install Detox for React Native?

Ans: To set up Detox in Android for your React Native project, follow these steps:

  1. Install the Detox CLI and package by executing the command: npm install detox-cli --global.
  2. Modify the android/build.gradle file to include the necessary configurations.
  3. Make the required changes in the app/build.gradle file to enable Detox integration.
  4. Create a DetoxTest file to define the test settings and configurations.
  5. Configure Detox in the package.json file by specifying the necessary dependencies and scripts.
  6. Edit the test spec file to define the test scenarios and assertions.
  7. Build the debug APK by running the command: ./gradlew assembleDebug.
  8. Execute the tests on the debug APK by using the Detox command: detox test --configuration android.emu.debug.
Share this

Guide to End-to-End Detox Testing

4 Parts


Perfect Digital Experiences with Data Science Capabilities

Utilize HeadSpin's advanced capabilities to proactively improve performance and launch apps with confidence
popup image