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
- A flow file: A YAML file with an
appIdand a list of commands such aslaunchApp,tapOn,inputTextandassertVisible. — Maestro docs - Stable selectors: Tap by visible text or accessibility id. Add
accessibilityLabelortestIDto elements that lack stable text. — Maestro docs - Test accounts and data: Use a dedicated test user and seeded data in a development backend, never production. — Supabase docs
- 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.
- Maestro tutorial — YouTube search: Maestro mobile testing tutorial
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
flow.yaml -> Maestro -> real build -> taps/inputs -> assertionsSmallest Possible Example
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
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
- Testing & QA rules: testing rules
- Expo + Jest + Detox rule: E2E alternative
