How do you test a React Native app with Maestro, and when should you choose it over Detox?

Sources checked on 12 November 2026.

This guide is for the person responsible for the quality of a company React Native app who wants to add automated E2E tests or is choosing between Maestro and Detox. It describes preparing the app, the first flows, test data and running in CI.

The short version: Maestro lets you describe user flows quickly with no changes to app code apart from testID. Its limits: the Maestro documentation lists only simulators on iOS, so do not plan on testing physical iPhones, and the tool has no view of the state inside the app. Before you write dozens of tests, check on two or three flows that they run stably in your CI.

According to the Maestro documentation, the tool treats the app as a black box and simulates user actions on the screen. Tests are declarative, written in YAML, and run without compilation.

Maestro waits for content to load and animations to finish on its own, so tests do not need manual pauses. It can also go beyond the app, for example into system settings or notifications.

Tests can be written in an editor or in the Maestro Studio app, which lets you create them visually on a connected device.

Both tools test a React Native app on a device or simulator, but they take different approaches. A comparison based on the documentation of both projects:

Detox describes itself as a gray box testing framework for React Native: tests are written in JavaScript, and Detox monitors asynchronous operations in the app to reduce flakiness. Testing on physical iOS devices is not yet supported.

The choice depends on the team and the app. Maestro makes it easier to start for people who do not write code every day. Detox gives developers tests in the same language as the app and tighter synchronisation with its state.

Maestro can find an element by its visible text, but such a test breaks when the label or translation changes.

The Maestro page on React Native recommends the testID property, which Maestro maps to a unique element identifier. The test then refers to the identifier, not the text, so it also works in other language versions.

Agree on a naming convention (for example screen_element) and add testID to buttons, form fields and elements the test has to check. In Expo Go the app is opened through a link (openLink) rather than launchApp with your own app identifier, so for CI it is better to use a standalone build, where plain launchApp works.

A hypothetical example: a login test in a store app. Each step is one command in a YAML file:

Such a flow is short, but it checks several layers at once: the screen, form validation, the connection to the backend and the move to the next view. That makes it a good first test in CI.

1. launchApp: start the app.
2. tapOn with the email field identifier, then inputText with the test account address.
3. tapOn with the password field identifier and inputText with the test account password.
4. tapOn with the login button identifier.
5. assertVisible with the identifier of a home screen element.

E2E tests are slower and costlier to maintain than unit tests, so start with the flows whose failure is the costliest:

• Login and sign-up, including password recovery.
• Purchase or order: cart, delivery, payment in the provider's test environment.
• System permissions: consent to notifications, location or camera.
• First launch: onboarding and consent screens.
• The feature customers download the app for, for example a loyalty card or order history.

If the company also has an online store, the browser purchase path is worth testing with a separate tool. We describe it in our guide to ecommerce E2E testing with Playwright.

Flaky E2E tests come not only from the tool but also from data. A test that logs into an account with a different cart state on every run will pass one time and fail the next.

Prepare a separate backend environment with test accounts, fixed products and the payment provider's test mode. Each test should start from a known app state and not depend on the result of another test.

Do not store access credentials in YAML files in the repository. Pass them as environment variables from the CI system's secrets.

Maestro's default waiting is enough for screens that load in a few seconds. For longer operations the documentation provides separate commands.

According to the description of Maestro wait commands, extendedWaitUntil is meant for slow network responses, such as payment processing, and waitForAnimationToEnd for elements that are visible but still moving. The documentation advises against a long timeout on every step, because it hides performance regressions.

If a test passes on some runs and fails on others, do not raise the timeouts straight away. First check the test data, animations and whether the test depends on execution order.

Before choosing infrastructure, check where Maestro can run. The list of Maestro supported platforms gives full support for Android emulators and physical devices and for iOS simulators.

iOS tests in CI therefore need a macOS machine with a simulator. The alternative is Maestro's cloud, where you upload the app build and the test files.

To start, it is enough to run a few key flows on every change to the main branch and the full set before a store release. Save results, screenshots and recordings from failed tests as CI artefacts, so the team can assess an error without running it again.