Originally published on PEAKIQ
Source: https://www.peakiq.in/blog/e2e-testing-your-react-native-app-with-maestro
E2E Testing Your React Native App with Maestro
Writing end-to-end tests for mobile apps has always been painful. Appium needs drivers. Detox needs native build hooks. Everything breaks when your UI shifts by 4 pixels. Maestro changes that. It talks to your app the same way a user does — through the accessibility layer — and writes tests in plain YAML.
This guide covers everything: installation, writing your first flow, handling iOS quirks, and plugging Maestro into your CI pipeline.
Why Maestro?
Before we dive in, here's why Maestro stands out against the traditional tools.
| Feature | Maestro | Detox | Appium |
|---|---|---|---|
| Setup complexity | Minimal | High | Very High |
| Language | YAML | JS/TS | JS/Python/Java |
| Platform support | iOS + Android | iOS + Android | iOS + Android |
| Zero app changes | ✅ | ❌ | ❌ |
| Flakiness handling | Built-in auto-wait | Manual sleeps | Manual sleeps |
| Expo support | ✅ First-class | Limited | Limited |
Info: Maestro operates entirely at the accessibility layer. It doesn't touch your JavaScript source, doesn't need npm packages inside your app, and tests the final compiled binary — just like a real user would use it.
Prerequisites
- Node.js ≥ 18
- React Native CLI or Expo project
- For iOS: Xcode + Simulator running
- For Android: Android Studio + AVD Manager with an emulator running
Installation
Step 1 — Install Maestro CLI
curl -Ls "https://get.maestro.mobile.dev" | bash
Maestro is compatible with macOS, Windows, and Linux. Verify the install:
maestro --version
Step 2 — Start your simulator/emulator
iOS (macOS only):
open -a Simulator
Android:
emulator -avd Pixel_6_API_33
Step 3 — Install and launch your app
# React Native CLI
npx react-native run-ios
npx react-native run-android
# Expo
npx expo start --ios
npx expo start --android
Your First Flow
Create a .maestro/ folder at the root of your project. This is where all your test flows live.
your-app/
├── .maestro/
│ ├── sign-in-flow.yaml
│ └── onboarding-flow.yaml
├── src/
└── package.json
Here's a minimal flow that launches your app and taps a button:
# .maestro/sign-in-flow.yaml
appId: com.yourapp.bundle
---
- launchApp
- tapOn: "Sign In"
- inputText:
text: "hello@example.com"
label: "Email"
- inputText:
text: "supersecret"
label: "Password"
- tapOn: "Continue"
- assertVisible: "Welcome back"
Run it:
maestro test .maestro/sign-in-flow.yaml
That's it. No compilation step, no linking, no driver setup.
Targeting Components
Maestro gives you two clean ways to target elements in your React Native app.
By visible text
If your component renders visible text, Maestro can find it directly:
- tapOn: "Add to Cart"
- assertVisible: "Item added"
By testID
For components without unique visible text (icons, image buttons), add a testID:
<TouchableOpacity testID="submit-button" onPress={handleSubmit}>
<Icon name="arrow-right" />
</TouchableOpacity>
Then in your flow:
- tapOn:
id: "submit-button"
Tip: Prefer
testIDover text matching for interactive elements. It decouples your tests from copy changes and internationalization.
Handling Text Input
Text input requires two steps: focus the field, then type.
Your React Native component:
<TextInput
testID="email-input"
placeholder="Enter your email"
onChangeText={setEmail}
keyboardType="email-address"
/>
Your Maestro flow:
- tapOn:
id: "email-input"
- inputText: "hello@maestro.dev"
- hideKeyboard
Assertions
Maestro ships with a concise set of assertions out of the box.
# Assert an element is visible
- assertVisible: "Dashboard"
# Assert by testID
- assertVisible:
id: "user-avatar"
# Assert something is NOT on screen
- assertNotVisible: "Loading..."
# Assert text content
- assertVisible:
text: "You have 3 notifications"
Handling iOS Nested Accessibility (Common Gotcha)
On iOS, React Native sometimes "swallows" touch events when components are deeply nested. You'll hit this when trying to tap something inside a Pressable or TouchableOpacity that's inside another tappable container.
The fix — in your React Native component:
// ❌ Before — inner Text is unreachable
<TouchableOpacity onPress={handlePress}>
<View>
<Text>Tap me</Text>
</View>
</TouchableOpacity>
// ✅ After — disable accessibility on outer, enable on inner
<TouchableOpacity accessible={false} onPress={handlePress}>
<View>
<Text accessible={true} testID="tap-target">Tap me</Text>
</View>
</TouchableOpacity>
Your flow stays clean:
- tapOn:
id: "tap-target"
Advanced: Parameterized Flows
Avoid duplicating flows for different test scenarios. Use Maestro's parameter support:
# .maestro/sign-in-flow.yaml
appId: com.yourapp.bundle
---
- launchApp
- tapOn: "Email"
- inputText: ${EMAIL}
- tapOn: "Password"
- inputText: ${PASSWORD}
- tapOn: "Sign In"
- assertVisible: "Dashboard"
Run with parameters:
maestro test .maestro/sign-in-flow.yaml \
-e EMAIL=test@example.com \
-e PASSWORD=mypassword
This is especially powerful for testing multiple user roles or locales without duplicating flow files.
Running a Full Test Suite
Run every flow in your .maestro/ directory with a single command:
maestro test .maestro/
Maestro will execute all .yaml files sequentially and report results for each one.
Integrating with CI/CD
GitHub Actions
# .github/workflows/e2e.yml
name: E2E Tests
on:
push:
branches: [main]
pull_request:
jobs:
e2e-android:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up JDK
uses: actions/setup-java@v4
with:
distribution: "temurin"
java-version: "17"
- name: Install Maestro
run: curl -Ls "https://get.maestro.mobile.dev" | bash
- name: Build APK
run: cd android && ./gradlew assembleDebug
- name: Start emulator
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: 33
script: |
adb install android/app/build/outputs/apk/debug/app-debug.apk
maestro test .maestro/
Maestro Cloud (Optional)
For parallel execution across real devices, push to Maestro Cloud:
maestro cloud \
--apiKey $MAESTRO_API_KEY \
android/app/build/outputs/apk/debug/app-debug.apk \
.maestro/
This gives you a visual dashboard of historical runs, device logs, and screenshots on failure.
Sample App: Complete Example
Here's a minimal React Native screen and its corresponding Maestro flow.
App.tsx:
import React, { useState } from "react";
import { SafeAreaView, Button, Text, TextInput, StyleSheet } from "react-native";
export default function App() {
const [taps, setTaps] = useState(0);
const [text, setText] = useState("");
return (
<SafeAreaView style={styles.container}>
<Button title="Add one" onPress={() => setTaps(taps + 1)} />
<Button
title="Add ten"
testID="add_ten"
onPress={() => setTaps(taps + 10)}
/>
<Text>Number of taps: {taps}</Text>
<TextInput
testID="text_input"
placeholder="Change me!"
onChangeText={setText}
style={styles.input}
/>
<Text>You typed: {text}</Text>
</SafeAreaView>
);
}
const styles = StyleSheet.create({
container: { flex: 1, alignItems: "center", justifyContent: "center" },
input: { borderWidth: 1, width: 200, padding: 8, marginTop: 12 },
});
.maestro/counter-flow.yaml:
appId: com.myapp
---
- launchApp
- tapOn: "Add one"
- tapOn:
id: "add_ten"
- assertVisible: "Number of taps: 11"
- tapOn: "Change me!"
- inputText: "Hello, Maestro!"
- assertVisible: "You typed: Hello, Maestro!"
Tips for Reliable Tests
-
Always use
testIDfor anything interactive. Text changes.testIDdoesn't (unless you change it deliberately). -
Don't use
sleep. Maestro automatically waits for elements to appear. Explicit sleeps are a code smell — if you think you need one, something else is wrong. - Keep flows small and composable. One flow = one user journey. A sign-in flow shouldn't also test the profile page.
-
Reset app state between runs. Use
clearState: trueinlaunchAppto ensure a clean slate:
- launchApp:
clearState: true
-
Use
runFlowfor shared setup:
# .maestro/helpers/login.yaml
---
- tapOn: "Email"
- inputText: ${EMAIL}
- tapOn: "Sign In"
# Your main flow
---
- launchApp
- runFlow: helpers/login.yaml
- assertVisible: "Dashboard"
Conclusion
Maestro removes the friction from mobile E2E testing. No native bridges, no custom drivers, no flaky sleeps — just YAML that reads like a QA script and runs like a charm.
With full support for both Expo and React Native CLI, built-in handling of timing and async UI, and a one-line CI setup, there's very little reason not to add Maestro to your project today.
Get started:
curl -Ls "https://get.maestro.mobile.dev" | bash
maestro test .maestro/your-first-flow.yaml
Happy testing.