E2E Testing React Native with Maestro: A Practical Guide

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 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"
/>

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 testID for anything interactive. Text changes. testID doesn'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: true in launchApp to ensure a clean slate:

- launchApp:
    clearState: true

Use runFlow for 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.

推荐订阅源

DEV Community

E2E Testing Your React Native App with Maestro

Why Maestro?

Prerequisites

Installation

Step 1 — Install Maestro CLI

Step 2 — Start your simulator/emulator

Step 3 — Install and launch your app

Your First Flow

Targeting Components

By visible text

By `testID`

Handling Text Input

Assertions

Handling iOS Nested Accessibility (Common Gotcha)

Advanced: Parameterized Flows

Running a Full Test Suite

Integrating with CI/CD

GitHub Actions

Maestro Cloud (Optional)

Sample App: Complete Example

Tips for Reliable Tests

Conclusion

Resources

推荐订阅源

DEV Community

E2E Testing Your React Native App with Maestro

Why Maestro?

Prerequisites

Installation

Step 1 — Install Maestro CLI

Step 2 — Start your simulator/emulator

Step 3 — Install and launch your app

Your First Flow

Targeting Components

By visible text

By testID

Handling Text Input

Assertions

Handling iOS Nested Accessibility (Common Gotcha)

Advanced: Parameterized Flows

Running a Full Test Suite

Integrating with CI/CD

GitHub Actions

Maestro Cloud (Optional)

Sample App: Complete Example

Tips for Reliable Tests

Conclusion

Resources

By `testID`