# wix/Detox: gray box end-to-end testing for React Native apps

> Detox runs JavaScript E2E tests against a real simulator or device and synchronizes them with your app's async work. It suits React Native teams fighting flaky UI tests, and it is a poor fit for anything that is not a React Native app.

**wix/Detox** — Gray box end-to-end testing and automation framework for mobile apps

- Repository: https://github.com/wix/Detox
- Website: https://wix.github.io/Detox/
- Stars: 12,027 · Forks: 1,911
- Language: JavaScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/en/projects/wix-detox

## The flakiness problem Detox was built around

The README is blunt about the motivation: the hardest part of mobile automation is the top of the testing pyramid, and the core problem with E2E tests is that they are usually not deterministic. A black box test drives the UI and waits on timers, so it passes or fails depending on how fast the device happened to be that run. Detox's answer is to move from black box to gray box testing, which means the framework has visibility into the app rather than only into the screen. The audience is React Native teams that want continuous integration without leaning on manual QA, and the README frames that reliance on manual QA as something that has to drop significantly as development velocity rises. If your app is not React Native, most of this design does not apply to you.

## How Detox synchronizes with your app instead of sleeping

The mechanism the README names is automatic synchronization: Detox monitors asynchronous operations in your app and stops flakiness at the core by doing so. In practice that means the test API is built around awaiting interactions and assertions rather than arbitrary waits, and the README states the async-await API is designed so breakpoints in asynchronous tests work as expected. The test runner is not baked in. Detox exposes a set of APIs that work with any test runner, and it ships Jest integration out of the box, so Jest is a default rather than a requirement. The repository layout reflects a monorepo: the package.json declares workspaces for detox, detox-cli, detox/test and examples/*, so the published framework and its CLI live in separate packages. ARCHITECTURE.md sits at the repository root for anyone who wants the internals rather than the usage guide.

## What a Detox test actually looks like

The README's own example is a login flow, and it is worth reading closely because it shows the vocabulary you will use every day. Elements are located by id, by text or by accessibility label, and assertions are expressed as expectations on those elements rather than on raw coordinates.

```js
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();
  });
});
```

The example comes straight from the README. Two details matter for adoption: the tests are written in JavaScript, and the assertions describe user-visible outcomes (the button is gone, the welcome label is visible) rather than internal state.

## Installing Detox and running a first test

The README points to the getting started guide at wix.github.io/Detox/docs/introduction/getting-started and claims it will get Detox running on your app in less than 10 minutes. The repository does not inline an install command in the README, so the honest instruction is to follow that guide; what the repository does show is how the project is built and tested. The root package.json declares the workspaces and the scripts used to exercise Detox itself, which is the closest thing to a runnable command set in the repository.

```json
{
  "packageManager": "yarn@4.12.0",
  "workspaces": [
    "detox",
    "detox-cli",
    "detox/test",
    "examples/*",
    "generation",
    "website"
  ],
  "scripts": {
    "test:e2e:ios": "cd detox/test && yarn e2e:ios",
    "test:e2e:android": "cd detox/test && yarn e2e:android"
  }
}
```

Those two scripts run the framework's own end-to-end suites from the repository root, so they are how the maintainers validate Detox, not how you would run tests in your own app. The published packages are the detox and detox-cli workspaces, distributed on npm. Once the getting started guide is followed, your first real use is a test file in the shape of the login example above, with element(by.id(...)) selectors matching identifiers you already put on your components.

## Where Detox is the wrong tool

The README states plainly that device support is not yet available on iOS, so iOS runs happen on a simulator. If your release process requires validating on physical iOS hardware, that is a gap you have to plan around. The supported React Native range is also narrower than the framework's ambitions: the README says Detox was built to support React Native projects and that official compatibility is provided for RN v0.77.x through v0.84.x on the New Architecture, with newer versions possibly working but not thoroughly tested by the Detox team. Older versions are not officially supported either, though the README says the team does its best to stay compatible. There is a known Android visibility edge case that the README links to a React Native issue for, which is the kind of thing that turns into a flaky assertion in a specific screen. And none of this helps a native iOS or Android app that is not React Native, or a web app, because the element selectors and synchronization assume the React Native runtime.

## Detox compared with black box mobile automation

The alternative most teams reach for is a black box driver such as Appium, which automates the app from the outside through platform automation APIs and knows nothing about your JavaScript. The difference is not cosmetic. A black box test has to wait for the app to become idle using heuristics, so it either waits too long and slows the suite or waits too little and fails intermittently. Detox, by monitoring asynchronous operations inside the app, can decide when the app is actually settled. The cost is coupling: your tests are JavaScript, they run against a React Native app, and the supported version range is a real constraint. A black box driver can test a React Native app and a fully native app with the same tooling, which matters if your organization ships both. Detox trades that generality for determinism, and the README is explicit that this trade is the whole point of the project.

## Maintenance, releases and the MIT licence

Detox is not archived and the last push to the repository was on 2026-09-07. Recent releases listed are 20.51.3 on 2026-05-30, 20.51.1 on 2026-05-03 and 20.50.2 on 2026-04-21, so release cadence on the 20.51 line has been roughly monthly over that window. The project is licensed under the MIT License, which the README states directly and which the repository confirms with a LICENSE file at the root. MIT is permissive: it allows commercial use and modification, and it requires that the licence and copyright notice be preserved. That is the licence text, not legal advice, and if your organization has policies about third-party dependencies you should route the LICENSE file through them. Upgrade cost is dominated by the React Native compatibility range rather than by Detox's own version number, because a React Native upgrade can move you outside the officially tested window. The repository has a contributing guide and a Discord server linked from the README, which is where the project says to raise problems with unsupported React Native versions.

## Conclusion

Adopt Detox if you ship a React Native app and your current E2E suite is flaky because tests race the app's async work; the official compatibility statement covers RN v0.77.x through v0.84.x on the New Architecture, so check your version first. Do not adopt it for a native iOS or Android app written outside React Native, or for web testing, because the API is built for React Native projects. Before committing, verify your exact React Native version against the supported range, confirm your CI can run simulators or emulators, and read the getting started guide at wix.github.io/Detox/docs/introduction/getting-started rather than guessing at configuration.

## FAQ

### How do I install wix/Detox?

The README does not list install commands inline; it directs readers to the getting started guide at wix.github.io/Detox/docs/introduction/getting-started, which it says will get Detox running on your app in less than 10 minutes. The package is published on npm as detox, and the repository also contains a separate detox-cli workspace.

### Which React Native versions does wix/Detox officially support?

The README states that RN v0.77.x through v0.84.x are fully compatible with React Native's New Architecture. Newer versions might work but have not been thoroughly tested by the Detox team, and older versions are not officially supported.

### Does wix/Detox work on real iOS devices?

The README says Detox runs on a device or simulator just like a real user, but adds in the same list item that this is not yet supported on iOS. For iOS, plan on simulators.

### What test runners can I use with wix/Detox?

Detox is test runner agnostic: the README says it provides a set of APIs usable with any test runner and comes with Jest integration out of the box. Jest is therefore the default path, not a hard requirement.

### What licence is wix/Detox released under?

The README states that Detox is licensed under the MIT License, and the repository contains a LICENSE file at the root. MIT permits commercial use and modification provided the licence and copyright notice are preserved.

## Sources

- [License: MIT](https://github.com/wix/Detox/blob/master/LICENSE)
- [Project website](https://wix.github.io/Detox/)
- [README](https://github.com/wix/Detox/blob/master/README.md)
- [Releases](https://github.com/wix/Detox/releases)
- [wix/Detox on GitHub](https://github.com/wix/Detox)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/en/projects/wix-detox