Detox — Gray-Box E2E Testing for React Native

Introduction

Detox is a gray-box end-to-end testing framework developed by Wix for React Native apps. Unlike black-box tools, Detox monitors the app internally to know when async operations complete, which eliminates arbitrary waits and produces reliable, non-flaky tests. It runs on both iOS simulators and Android emulators.

What Detox Does

• Synchronizes with the app's JS thread, animations, and network requests before each action
• Tests real native builds on iOS simulators and Android emulators
• Provides a Jest-like API for element matching, actions, and expectations
• Supports testing user interactions like taps, swipes, scrolling, and text input
• Runs on CI with headless simulators for automated test pipelines

Architecture Overview

Detox consists of a test runner (Node.js side) and a native server injected into the app binary. The native server instruments the app's run loop, monitors pending async operations (network, animations, timers), and signals readiness back to the test runner. The test runner sends commands (tap, type, assert) via WebSocket. This gray-box synchronization model ensures each action executes only when the app is idle.

Self-Hosting & Configuration

• Requires Xcode (iOS) or Android SDK with emulator images pre-installed
• Configure .detoxrc.js with app build commands, device types, and test runner settings
• Build the app with detox build before running tests
• Set behavior.init.exposeGlobals to control whether Detox APIs are auto-injected
• Use artifacts config to capture screenshots and videos on test failure

Key Features

• Gray-box synchronization eliminates the need for manual sleeps or waits
• First-class React Native support with deep integration into the JS bridge
• Automatic screenshot and video recording for failed tests
• Supports testing deep links, push notifications, and permission dialogs
• Parallel test execution across multiple simulator or emulator instances

Comparison with Similar Tools

• Appium — black-box, cross-platform, supports any mobile app; Detox is gray-box and optimized for React Native
• Maestro — YAML-driven with auto-waiting; Detox offers programmatic control and deeper synchronization
• Espresso — Android-only white-box testing; Detox works across iOS and Android
• XCUITest — Apple's native UI testing; Detox provides a unified JS API for both platforms
• Cypress — web-only E2E testing; Detox is designed for native mobile apps

FAQ

Q: Does Detox work with Expo projects? A: Yes, Detox works with Expo projects that have been ejected or use a custom dev client with native builds.

Q: Can I run Detox tests on real devices? A: Yes, Detox supports real iOS and Android devices, though simulator/emulator testing is more common in CI.

Q: How does Detox handle animations? A: Detox waits for animations to complete by monitoring the native animation queue. You can also disable animations via config for faster tests.

Q: Does Detox support Jest? A: Yes, Jest is the default and recommended test runner for Detox.

Sources

• https://github.com/wix/Detox
• https://wix.github.io/Detox/