DEV Community

Cover image for E2E Testing React Native with Maestro: A Practical Guide
PEAKIQ
PEAKIQ

Posted on • Originally published at peakiq.in

E2E Testing React Native with Maestro: A Practical Guide

#reactnative #maestro #e2etesting #uitests

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
Enter fullscreen mode Exit fullscreen mode

Maestro is compatible with macOS, Windows, and Linux. Verify the install:

maestro --version
Enter fullscreen mode Exit fullscreen mode

Step 2 — Start your simulator/emulator

iOS (macOS only):

open -a Simulator
Enter fullscreen mode Exit fullscreen mode

Android:

emulator -avd Pixel_6_API_33
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Run it:

maestro test .maestro/sign-in-flow.yaml
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

Then in your flow:

- tapOn:
    id: "submit-button"
Enter fullscreen mode Exit fullscreen mode

Tip: Prefer testID over 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"
/>
Enter fullscreen mode Exit fullscreen mode

Your Maestro flow:

- tapOn:
    id: "email-input"
- inputText: "hello@maestro.dev"
- hideKeyboard
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

Your flow stays clean:

- tapOn:
    id: "tap-target"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Run with parameters:

maestro test .maestro/sign-in-flow.yaml \
  -e EMAIL=test@example.com \
  -e PASSWORD=mypassword
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

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 },
});
Enter fullscreen mode Exit fullscreen mode

.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!"
Enter fullscreen mode Exit fullscreen mode

Tips for Reliable Tests

  1. Always use testID for anything interactive. Text changes. testID doesn't (unless you change it deliberately).
  2. 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.
  3. Keep flows small and composable. One flow = one user journey. A sign-in flow shouldn't also test the profile page.
  4. Reset app state between runs. Use clearState: true in launchApp to ensure a clean slate: 
- launchApp:
    clearState: true
Enter fullscreen mode Exit fullscreen mode
  1. Use runFlow for shared setup: 
# .maestro/helpers/login.yaml
---
- tapOn: "Email"
- inputText: ${EMAIL}
- tapOn: "Sign In"
Enter fullscreen mode Exit fullscreen mode 
# Your main flow
---
- launchApp
- runFlow: helpers/login.yaml
- assertVisible: "Dashboard"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Happy testing.

Resources

Top comments (0)