Guide · Open source

How to use Detox: set up, write and run mobile E2E tests

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Detox is an open-source framework for end-to-end testing of mobile apps. It runs your app on a device or simulator, taps buttons and types into fields the way a user would, then checks that the expected screens appear. This guide is for developers with a React Native project who want automated tests, and it covers what you need before starting, how a test is written, and where Detox fits compared with other tools.

Detoxwix/Detox · ★ 12.1k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm you have Node.js, a React Native project and an Android or iOS simulator, emulator or device.
2Confirm your React Native version. Make sure your version is in the officially supported range listed in the README.
3Follow the Getting Started Guide. Open the official guide and set up Detox for your project and platform.
4Write a test. Create a JavaScript test that uses element, by matchers and actions such as typeText and tap.
5Add assertions. Use expect with toBeVisible or not.toExist to check that the right screen appears.
6Run on a simulator or device. Run the test against your app on the emulator, simulator or device you prepared.
7Connect to CI. Add the test run to your CI system, such as Travis CI, Circle CI or Jenkins, using the official docs.

What do you need before you use Detox?

The README lists four prerequisites: Node.js, a React Native project, and an Android or iOS simulator, emulator or device. Detox is written mainly for React Native projects in JavaScript, so tests are written in JavaScript too.

The README says Detox is built to support React Native projects and officially covers RN v0.77.x through v0.84.x, which use React Native's New Architecture. Newer versions may work but are not thoroughly tested by the team, and older versions are not officially supported.

Node.js installed
An existing React Native project
An Android or iOS simulator, emulator or physical device
Check that your React Native version falls in the officially supported range

Install Detox and get started

Detox is installed through a package manager. The README points to the Getting Started Guide on the official documentation site for the full setup steps, which should take less than 10 minutes according to the README.

The README's only install command in the source is the one that clones the repository. Use the Getting Started Guide for the package setup steps for your project.

Read the Getting Started Guide at https://wix.github.io/Detox/docs/introduction/getting-started
Follow the steps for your platform (Android or iOS) and your project setup

git clone https://github.com/wix/Detox.git

How does a Detox test work?

A Detox test describes a user flow. The README example tests a login screen: it reloads the React Native app before each test, types an email and password, taps the Login button, and then checks that the button no longer exists and that a 'Welcome' label is visible.

Tests find elements with matchers such as by.id, by.text and by.label. The API uses async and await, so you can set breakpoints inside asynchronous tests, according to the README.

device.reloadReactNative() restarts the app before each test
element(by.id(...)).typeText(...) types into a field
tap() presses an element
expect(...).toBeVisible() and expect(...).not.toExist() check the result

describe('Login flow', () => {
  beforeEach(async () => {
    await device.reloadReactNative();
  });

  it('should login successfully', async () => {
    await element(by.id('email')).typeText('john@example.com');
    await element(by.id('password')).typeText('123456');

    const loginButton = element(by.text('Login'));
    await loginButton.tap();

    await expect(loginButton).not.toExist();
    await expect(element(by.label('Welcome'))).toBeVisible();
  });
});

Why does Detox wait for the app before checking results?

Many end-to-end tests fail randomly, which is called flakiness. The README says Detox reduces this by monitoring the app's asynchronous operations, so a check runs after background work has finished rather than at a fixed time.

The README describes this approach as gray box testing: Detox has some knowledge of the app's internals, as opposed to pure black box testing that only sees the screen.

Can Detox run on CI?

The README says Detox is made for continuous integration and lists Travis CI, Circle CI and Jenkins as platforms where you can run E2E tests. It also says Detox works with Jest out of the box, and provides APIs that can be used with other test runners.

The README does not give CI configuration steps, so check the official documentation for setup on your CI system.

Travis CI, Circle CI and Jenkins are named in the README
Jest integration comes built in
Other test runners can be used through Detox's APIs

What are the limits of Detox?

Detox is not a no-code tool, since tests are written in JavaScript. It is also not aimed at native-only apps, because the README focuses on React Native support and does not describe other stacks.

The README notes one known React Native issue on Android, a visibility edge case, and says device testing is not yet supported on iOS.

Tests are written in JavaScript, so non-developers will need help
Focused on React Native; native-only apps are not covered in the README
Visibility edge case on Android linked to a React Native issue
Running on a device is not yet supported on iOS, according to the README

What people use it for

Automating a login flow that types credentials, taps a button and checks the welcome screen
Running end-to-end tests on every change through CI systems such as Travis CI, Circle CI or Jenkins
Using Jest to organise and run Detox tests in a React Native project
Testing the same React Native user flows on both Android and iOS

Frequently asked questions

Is Detox free to use?

Yes. The README says Detox is released under the MIT License, which is a permissive open-source licence. Check the LICENSE file in the repository for the full terms.

What do I need to install Detox?

The README lists Node.js, a React Native project, and an Android or iOS simulator, emulator or device. Follow the Getting Started Guide on the official site for the setup steps.

Which React Native versions does Detox support?

The README says the officially supported range is RN v0.77.x through v0.84.x, with full New Architecture compatibility. Newer versions may work but are not thoroughly tested, and older versions are not officially supported.

Does Detox work with Jest?

Yes. The README says Detox comes with Jest integration out of the box. It also provides APIs that can be used with other test runners.

Can I use Detox without writing JavaScript?

No. The README says tests are written in JavaScript for React Native apps, so Detox is not a no-code testing tool.

How does Detox compare with Appium, Maestro, Espresso or XCUITest?

This source does not compare Detox with those tools, so it cannot tell you which is better. The README's main points are gray box testing, automatic synchronisation with app async work, and a focus on React Native. Try each tool on a small flow from your app to see which fits your stack.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Detox suits React Native teams that want JavaScript end-to-end tests which wait for the app to settle, and that run on CI. Pick another tool if your app is native-only, you need a no-code tool, or your React Native version falls outside the officially supported range.

Install options & downloads