Getting Started

Before You Start

Overview of Detox

Detox is an open-source end-to-end (E2E) testing framework for React Native mobile applications. Our main goal is to enable the testing of any end-to-end flow in the app, with maximum velocity and zero flakiness. Detox tests your mobile app while it's running on a real device or simulator, simulating a real user's interactions.

What Does a Detox Test Look Like?

This is a test for a login screen, it runs on a device or simulator like an actual user:

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

Gray box testing

One of the most challenging aspects of automated testing on mobile is end-to-end testing. UI testing frameworks are often not fully-deterministic, since they are built with a "black box" approach, where the test runner has no access to the internals of the app under test, and is unaware of asynchronous operations that take place in the app (such as network requests, animations, etc.). This makes it difficult to write reliable E2E tests, and often leads to flaky tests that are hard to debug and maintain.

To address this issue, Detox adopts a "gray box" testing approach, by having access to the internals of the app under test. This allows for more control and predictability in the testing process. For more information, you can read how Detox works.

Start with Detox

Follow the Setup Guides

The following guides in this Introduction section will help you get started with Detox, one step at a time, from setting up your environment to writing and running your first test.

Join the Community 🤝

As an open-source project, Detox encourages and welcomes contributions from the community. Whether you're a developer, tester, or just someone who is passionate about making mobile development better, there's a place for you in the Detox community. By contributing to Detox, you'll be helping to improve the reliability and user experience of mobile apps, and you'll be part of a team that is dedicated to making mobile development faster and more efficient. We welcome all types of contributions, from code and documentation, to bug reports, questions and feature requests.

So, if you're interested to be part of the community, we encourage you to get involved by reading our contributing guidelines, and join our Discord server. We also have a Twitter account where we share updates about the project.