Maestro, End-to-End UI Testing for Mobile and Web
AGENTIC UI TESTING
Go ahead.Code at 150mph.
Maestro is mobile UI testing at agentic velocity. Open source, human-readable code, easy CI integrations, and powerful CLI and desktop apps.
appId: com.example.app --- - launchApp - tapOn: Login - inputText: test@example.com - tapOn: Continue - assertVisible: Welcome back
Trusted by thousandsTrusted by the world's best teams
'%20fill='%23362d59'%3e%3c/path%3e%3c/svg%3e)
'%20fill='%23362d59'%3e%3c/path%3e%3c/svg%3e)
Maestro in action
Add Tasks.yaml Running
1appId: com.todoist
2---
3- launchApp
4- tapOn: Quick add
5- tapOn: id: message
6- inputText: "go to the gym"
7- tapOn: Date
8- tapOn: Today
9- tapOn: Add
10- inputText: "breakfast with John"
11- tapOn: Date
12- tapOn: Add time
13- tapOn: 9 o'clock
14- tapOn: OK
15- tapOn: Save
16- tapOn: Add
17- inputText: "grocery shopping"
18- tapOn: Add
19- inputText: "pick up the laundry"
20- tapOn: Add
21- inputText: "Finalize editing of v3"
22- tapOn: Priority
23- tapOn: Priority 1
24- tapOn: Add
25- inputText: "dinner at Emma's house"
26- tapOn: Date
27- tapOn: Add time
28- tapOn: 7 o'clock
29- tapOn: 30 minutes
30- tapOn: PM
31- tapOn: OK
32- tapOn: Save
33- tapOn: Add
34- tapOn: id: toolbar
35- tapOn: Upcoming
Features
Battle-tested, AI-native
Robust, open-source, time-tested - and now fully primed for human+AI development.
Close the agentic loop
Unlock high-velocity mobile development by powering up your agents with Maestro's AI toolkit.
> write Maestro tests for the new settings screen, including setting/testing each setting within
with full test plan, pls
● Let me look at the live screen and existing Maestro tests to understand what needs testing.
Read emulator screen hierarchy, searched for1 pattern, read4 files, listed1 directory
● Now I have a clear picture of the settings screen. Let me write a suite of focused Maestro tests.
---
Here are the tests I propose:
Structure / Smoke
1. settings_sections_visible- scroll through the full screen and assert every section header is present
Content Correctness
2. settings_about_shows_version- About section shows Version and Build rows
3. settings_voice_section_no_api_key- voice section shows no voices loaded
Pickers
4. settings_sample_rate_picker- verify sample rate options
5. settings_effects_profile_picker- verify effects profile options
Persistence
6. settings_toggles_persist- toggle every switch, restart app, verify saved state
7. settings_voice_rate_persists- adjust speaking rate and verify value after relaunch
8. settings_audio_encoding_persists- choose MP3 and confirm selection survives restart
Reset
9. settings_reset_to_defaults- reset all TTS settings and verify confirmation
10. settings_reset_cancel- cancel reset flow and verify settings remain unchanged
Navigation
11. settings_history_button_navigates- tap History and verify empty state or recent sessions
12. settings_back_returns_home- navigate back and assert the home screen is visible
Accessibility
13. settings_controls_accessible_labels- verify controls expose stable accessible labels
14. settings_dynamic_type_layout- increase text size and verify rows remain tappable
15. settings_voiceover_order- assert VoiceOver traversal follows visual order
Generate deterministic E2E tests
Maestro tests are human-readable YAML files, not black boxes. Repeatable, auditable, trustworthy.
1# .maestro/ios-settings.yaml
2appId: org.wikipedia.wikipedia
3---
4✓- launchApp
5✓- assertVisible: "Welcome to Wikipedia"
6✓- runFlow: subflows/onboarding.yaml
7✓- tapOn: "Year In Review"
8✓- assertNotVisible: "Sign in to edit"
9✓- inputText: "qwerty"
10✓- assertVisible: "qwerty"
11✓- eraseText
12✓- inputText: "london"
13✓- assertVisible: "London"
14✓- tapOn: "London"
15✓- assertVisible: "United Kingdom"
16✓- tapOn: "Save"
17✓- scrollUntilVisible: "History"
18✓- assertVisible: "History"
19✓- back
20✓- assertVisible: "Search"
21✓- tapOn: "Settings"
22✓- assertVisible: "Language"
23✓- tapOn: "Language"
24✓- inputText: "English"
25✓- assertVisible: "English"
26✓- tapOn: "Done"
27✓- back
28✓- assertVisible: "Home"
29✓- tapOn: "Explore"
30✓- assertVisible: "Featured article"
Build on open-source integrity
Extensible and with no vendor lock-in, Maestro is the foundation for thousands of teams’ mobile testing.
t@macbookproCode % git clone https://github.com/mobile-dev-inc/Maestro.git
---
Cloning into 'Maestro'...
remote: Enumerating objects:32693, done.
remote: Counting objects:100% (1379/1379), done.
remote: Compressing objects:100% (652/652), done.
remote: Total 32693 (delta1101), reused743 (delta723), pack-reused31314
Receiving objects: 100% (32693/32693),925.09 MiB |13.99 MiB/s, done.
Resolving deltas: 100% (14496/14496), done.
---
t@macbookproCode %
Surfaces
Build like the wind
Write and manage tests wherever you like, however fast you like.
Claude Codex
I’m turning that exact proof into an iOS Maestro test now, with the one-time education popups handled so it can run from clean state.
Explored 2 files, 2 searches, 1 list
I’m adding a dedicated ios-saved-flow.yaml rather than burying this inside the general smoke flow.
Created 1 file, edited 1 file
The new flow is in place and wired into ios-advanced-flow.yaml. I’m going to syntax-check it, then run the dedicated Saved flow.
Used Maestro MCP to inspect emulator hierarchy
I can see the onboarding card and the logged-out modal. I’m adding guarded runFlow steps so the test handles either clean or warm app state.
Tapped through emulator prompts, ran 1 flow
The Saved tab is reachable now. I’m asserting the article appears after restart so the test proves persistence, not just a successful tap.
Ask for follow-up changes
SummaryReview+72-0
ios-advanced-flow.yaml +1-0
39 unmodified lines
40-eraseText
41-inputText: qwerty
42-assertVisible: ${output.result}
43-runFlow: ios-saved-flow.yaml
ios-saved-flow.yaml +71-0
1-appId: org.wikimedia.wikipedia
2-tags:
3-- ios
4----
5-
6-- launchApp:
7-clearState: true
8-- runFlow: subflows/onboarding-ios.yaml
9-- runFlow:
10-when:
11-visible:
12-text: Explore your Wikipedia Year in Review
13-commands:
14-- tapOn: Done
15-label: Dismiss Year In Review popup, if visible
16-- runFlow:
17-when:
18-visible:"You have been logged out"
19-commands:
20-- tapOn:
21-text:"Continue without logging in"
22-label: Dismiss the auth modal if visible
Maestro MCP
Power up your favorite agent with our official MCP server. Give agents the "eyes and hands" to build and verify E2E coverage locally, fast and efficient, ensuring every change is fully tested before you ever open a PR.
Maestro Studio
iPhone 17 Pro●
simple-navigation-flow.yaml×
1appId: com.apple.Maps
2---
3- launchApp:
4clearState: true
5- runFlow:
6when:
7visible:"Allow “Maps” to use your location?"
8commands:
9- tapOn:"Allow While Using App"
10label: Handle location permission if prompted
11
12- runFlow:
13when:
14visible:"What’s New in Maps"
15commands:
16- tapOn:"Continue"
17label: Dismiss onboarding splash screen
18
19- tapOn:
20id:"Search"
21- inputText:"Space Needle"
22- waitForAnimationToEnd
23- tapOn:"Space Needle, Broad St, Seattle, WA"
24
25- assertVisible:"Space Needle"
26- assertVisible:"Observation deck"
27
28- runFlow:
29when:
30visible:
31id:"More"
32commands:
33- tapOn:
34id:"More"
35label: Open more options if action bar is collapsed
36
37- tapOn:"Add to Favorites"
38
39- runFlow:
40when:
41visible:"Done"
42commands:
43- tapOn:"Done"
44label: Close the detail card to return to map
45
46- tapOn:
47id:"Search"
48- scrollUntilVisible:
49element:"Favorites"
50direction: DOWN
51- tapOn:"See All"
52
53- assertVisible:"Space Needle"
54- assertVisible:"400 Broad St"
LocalCloud▷ Run Test
maestro
.maestro
scripts
subflows
ios-flow.yaml
ios-saved-flow.yaml
simple-navigation-flow.yaml
New file
Maestro Studio
Build tests in a visual IDE for Mac and Windows that makes manual test creation feel like magic. Contextual autocomplete, "tap-tap-tap" YAML generation, deep selector inspection, and an embedded emulator.
Terminal
t@macbookpro~ % maestro
Usage: maestro [-hv][--[no-]ansi][--verbose][-p=
-h, --help Display help message
--[no-]color Enable / disable colors and ansi output
--p=
--d=
-v, --version Display CLI version
--verbose Enable verbose logging
Commands:
test Test a Flow or set of Flows on a local iOS Simulator or Android Emulator
cloud Upload your flows on Cloud by using `maestro cloud sample/app.apk flows_folder/
record Render a beautiful video of your Flow - Great for demos and bug reports
download-samples Download sample apps and flows for trying out maestro without setting up your own app
login Log into Maestro Cloud
logout Log out of Maestro Cloud
bugreport Report a bug - Help us improve your experience!
start-device Starts or creates an iOS Simulator or Android Emulator similar to the ones on the cloud
chat Use Maestro GPT to help you with Maestro documentation and code questions
mcp Starts the Maestro MCP server, exposing the device/commands as Model Context Protocol
t@macbookpro~ %
Maestro CLI
The lightweight, open-source engine for developers who prefer to bring their own IDE. Run human-readable YAML tests with the fastest, best runner in mobile - whether iterating locally or executing at scale in CI.
Maestro Cloud
Scale in our cloud
Maestro Cloud provides high-speed, test-tuned infrastructure.
app.maestro.dev/test-runs
DashboardTest runs
Total flow runs
3069+1% m/m
Average run time
3min
Failed flow runs
23
Passing rate
99.25%+1% m/m
Run history
Run startWorkspaceOSDevice configDurationResults
Today, 10:42 AMwikipedia-iosiOSiPhone 17 Pro / iOS 26.23m 18s24 success / 0 failure
Today, 10:31 AMcheckout-androidAndroidPixel 9 / API 365m 04s18 success / 0 failure
Today, 10:18 AMmaps-regressioniOSiPad Air / iOS 26.24m 46s21 success / 2 failure
Today, 10:02 AMsettings-smokeAndroidGalaxy S25 / API 352m 12s16 success / 0 failure
Today, 9:49 AMrelease-candidateMixed24-device matrix6m 38s29 success / 0 failure
Today, 9:34 AMonboarding-flowiOSiPhone SE / iOS 25.61m 54s12 success / 0 failure
Today, 9:17 AMprofile-testsAndroidPixel Fold / API 363m 52s20 success / 0 failure
Today, 8:59 AMsearch-suiteiOSiPhone 16 / iOS 26.02m 43s15 success / 0 failure
Today, 8:41 AMpayments-smokeAndroidGalaxy Tab S10 / API 356m 11s27 success / 0 failure
Today, 8:22 AMsaved-itemsiOSiPad Pro / iOS 26.24m 09s19 success / 0 failure
Today, 8:05 AMauth-regressionAndroidPixel 8 / API 355m 31s23 success / 0 failure
Yesterday, 5:48 PMnotificationsiOSiPhone 15 / iOS 25.72m 27s14 success / 0 failure
Yesterday, 5:21 PMarticle-readerAndroidOnePlus 13 / API 363m 06s22 success / 0 failure
Yesterday, 4:56 PMdeep-linksiOSiPhone 17 Pro / iOS 26.21m 38s11 success / 0 failure
Yesterday, 4:30 PMnightly-matrixMixed18-device matrix6m 55s30 success / 0 failure
Parallel execution
Run your entire test suite across simulators and emulators simultaneously to cut CI wait times down to minutes. Enterprise-grade.
Test with context
Every run includes step-by-step video playback, detailed logs, and flake detection so you can diagnose and fix bugs efficiently.
Seamless CI integration
Plug Maestro into your existing pipeline with a single command to get instant reporting and deep diagnostic context.