End-to-End Tests with Maestro

Write simple YAML flows that drive a real build and run them locally and in CI.

Maestro flows read like a script of what a user does. They are quick to write and easy for an agent to generate and for you to review.

Core concepts

  1. A flow file: A YAML file with an appId and a list of commands such as launchApp, tapOn, inputText and assertVisible. — Maestro docs
  2. Stable selectors: Tap by visible text or accessibility id. Add accessibilityLabel or testID to elements that lack stable text. — Maestro docs
  3. Test accounts and data: Use a dedicated test user and seeded data in a development backend, never production. — Supabase docs
  4. Run on builds: Run flows against a development or preview build on a simulator or device, and in CI for key branches. — EAS Build

Concept videos

YouTube channels and searches for these topics. On a large screen they open in the reading panel next to the roadmap.

Explanation

Keep flows short

One flow per journey (sign-in, create item, delete account). Short flows fail clearly.

Avoid flakiness

Assert on visible results instead of sleeping; Maestro waits for elements by default.

What Is It?

Maestro is a mobile UI testing tool driven by YAML flows.

Why Should I Care?

It checks the whole stack the way a user does, catching integration bugs unit tests cannot.

Real World Analogy

A flow is a stage direction card: enter, say this line, expect that reaction.

Visual Mental Model

text
flow.yaml -> Maestro -> real build -> taps/inputs -> assertions

Smallest Possible Example

yaml
appId: com.example.myapp
---
- launchApp
- tapOn: "Sign in"
- inputText: "demo@example.com"
- tapOn: "Continue"
- assertVisible: "Welcome"

Common Mistakes

❌ Using production data in tests.

Tests may delete or change real users' data; use a test project.

❌ Long, sprawling flows.

Failures are hard to locate; split by journey.

Build This Mini Project

Write flows for sign-in and creating an item, run them on a simulator and add them to a CI job.

Prompts for Cursor, Claude Code & Codex

Paste these into Cursor, Claude Code, Codex, or any coding agent. Replace the bracketed parts with your app details, and keep the agent in plan mode first so you review the approach before it edits files.

Generate a Maestro flow

text
Write a Maestro flow for the journey: [steps]. Use visible text or accessibility labels, add assertions after each key step, and list any testID or accessibilityLabel I should add to components.

Rules, databases & blogs to use

Resources

Threads in the same domain as this chapter — go deeper on iHateReading without leaving the roadmap.

Making AI applications without AI slop cover

Making AI applications without AI slop

Quality and safety guardrails for AI-built software.

Cursor, Codex, Claude Code prompts collection cover

Cursor, Codex, Claude Code prompts collection

200+ copy-paste prompts for coding agents to build better products.