Detox
Gray-box end-to-end testing for React Native. More reliable than black-box tools by synchronising with the app's JavaScript thread.
Overview
Detox, created by Wix in 2017, is an end-to-end testing framework specifically designed for React Native applications. Unlike black-box tools like Appium that interact with the UI from the outside, Detox is a gray-box framework that synchronises with the React Native JavaScript thread. This means Detox waits for the app to be idle before executing the next test step, eliminating the flakiness caused by race conditions.
Detox has become the standard E2E testing tool for React Native teams that outgrow Appium or need more reliable test execution.
What it's used for
Detox is ideal when:
- React Native app: Purpose-built for React Native with deep framework integration.
- Test flakiness is a problem: Gray-box synchronisation dramatically reduces flaky tests.
- CI reliability needed: Tests that pass locally also pass in CI without timing tweaks.
- Fast feedback loop: Hot-reload support during test development.
Pros & Cons
Pros
- Gray-box synchronisation eliminates timing flakiness
- Built specifically for React Native
- Fast test execution with hot-reload support
- Cross-platform: tests run on both iOS and Android
- Active community with regular updates
Cons
- React Native only — not for native Android/iOS or Flutter
- Requires some native build knowledge for setup
- Debugging failing tests can be complex
- Smaller ecosystem than Appium
- iOS setup requires macOS
Platforms & Integrations
Detox runs on macOS (for iOS tests) and Windows/Linux (for Android tests). It requires Node.js, React Native CLI, and native development tools.
Pricing
| Tier | Cost | Includes |
|---|---|---|
| Open Source | Free | Full framework, all features, community support |
NZ Context
Detox is popular among NZ React Native teams, particularly in startups using cross-platform mobile development. Companies like Serko (travel tech) have used Detox for mobile app testing. For NZ teams choosing between Appium and Detox for React Native, Detox is generally preferred for reliability.
Alternatives
- Appium — More flexible (works with any mobile stack) but less reliable for React Native.
- Maestro — Modern cross-platform testing with simpler setup than Appium.
- XCUITest / Espresso — Native frameworks for iOS/Android. Best for native-only teams.
When to choose Detox
A quick decision guide for NZ teams evaluating mobile testing options.
| Choose Detox when… | Choose something else when… | Combine with… |
|---|---|---|
| Your app is built in React Native and flaky E2E tests are slowing down releases | Your team builds native iOS (Swift/Obj-C) or native Android (Kotlin/Java) — use XCUITest or Espresso instead | Jest for unit tests and React Native Testing Library for component tests — Detox covers only the E2E layer |
You need CI-reliable mobile tests without per-run timing hacks or sleep() calls |
Your app is Flutter — Detox has no Flutter support; use the Flutter integration test package or Maestro instead | Bitrise or GitHub Actions for CI — Detox's iOS runner requires macOS agents, so factor that into your pipeline costs |
| Your team already knows JavaScript/TypeScript and you want tests in the same language as the app code | You need to test multiple platforms (web + iOS + Android) from a single suite — Playwright with mobile emulation or Appium covers more ground | Allure or a custom Jest reporter for test reporting — Detox outputs JUnit XML natively but raw output is sparse |
| The app has complex async flows (navigation, animations, network calls) that cause race conditions under Appium | Your QA team has no JavaScript experience and you cannot afford onboarding time — Maestro's YAML syntax has a lower entry barrier | MSW (Mock Service Worker) or WireMock for API mocking — isolates E2E tests from backend flakiness without touching Detox itself |
What I would do
Practitioner judgment on tool adoption, team onboarding, and when to swap.
The bottom line: Detox is the right default for React Native — but "default" does not mean "always." The framework wins on reliability, not flexibility. If your mobile stack is anything other than React Native, evaluate Maestro or native-platform tools before committing to Detox.
Interview questions
Questions you are likely to get if you list Detox on your CV — with what interviewers are really testing for.
What is the difference between a gray-box and a black-box testing approach, and why does it matter for Detox?
What they’re really testing: Whether you understand Detox at a conceptual level or just copied test scripts without knowing how the framework works.
Strong answer covers: Black-box tools (Appium, Espresso) drive the UI from the outside and rely on polling or fixed sleeps; gray-box means Detox has access to the app’s internals and synchronises directly with the React Native JS thread, so it only acts when the app is genuinely idle. That synchronisation is why Detox tests are far less flaky in CI than Appium equivalents.
When would you choose Detox over Appium for a mobile testing project?
What they’re really testing: Whether you can make a reasoned tool-selection decision rather than defaulting to whatever you used last.
Strong answer covers: Detox is the right choice when the app is React Native and test flakiness is a problem; Appium wins when the team needs to cover native iOS, native Android, or multiple platforms from a single suite. Also worth noting: Detox requires macOS agents for iOS in CI, which adds pipeline cost — a real trade-off for NZ teams running lean infrastructure budgets.
You’re joining ListRight’s mobile QA team. They have a React Native app and an Appium suite that fails 25% of runs on iOS due to timing issues. How would you approach migrating to Detox?
What they’re really testing: Whether you can plan a realistic migration without burning existing test coverage or disrupting active releases.
Strong answer covers: Start with the highest-value journeys (login, search, checkout) rather than a full rewrite; run both suites in parallel for two sprints so you have a green-rate comparison before retiring any Appium tests; set a threshold (e.g. 95% green in CI for two consecutive sprints) before decommissioning; keep the Appium suite as a reference, not immediately as debt to discard.
Your Detox tests pass reliably on your MacBook but fail intermittently on the GitHub Actions iOS runner in CI. How do you debug this?
What they’re really testing: Whether you have real CI troubleshooting experience or only run tests locally.
Strong answer covers: First check if the CI runner uses the same simulator device and iOS version — mismatches cause subtle rendering differences. Enable Detox’s verbose logging (--loglevel verbose) to see where synchronisation stalls. Check for network-dependent tests that should be mocked with MSW or WireMock. Review CI agent specs (CPU/RAM) — underpowered agents cause animation-sync timeouts that never reproduce locally. Finally, inspect artifact screenshots Detox captures on failure before assuming the test is wrong.
How would you structure a Detox test suite for a React Native app that covers both iOS and Android, and scales as the team grows?
What they’re really testing: Whether you think about test architecture and long-term maintainability, not just individual test scripts.
Strong answer covers: Organise by user journey (auth, onboarding, core flows, edge cases) not by screen; use a single Detox config file with separate device configurations for iOS simulator and Android emulator so the same test files run on both platforms; abstract selectors into a page-object or screen-object layer so a UI change only requires one fix; run platform suites in parallel on separate CI agents (macOS for iOS, Linux for Android) to keep pipeline time under control; tag tests by criticality so smoke tests can run on every PR without waiting for the full suite.