AGENTIC UI TESTING
Maestro is mobile UI testing at agentic velocity. Open source, human-readable code, easy CI integrations, and powerful CLI and desktop apps.
Maestro in action
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 for 1 pattern, read 4 files, listed 1 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
- settings_sections_visible - scroll through the full screen and assert every section header is present
Content Correctness
-
settings_about_shows_version - About section shows Version and Build rows
-
settings_voice_section_no_api_key - voice section shows no voices loaded
Pickers
-
settings_sample_rate_picker - verify sample rate options
-
settings_effects_profile_picker - verify effects profile options
Persistence
-
settings_toggles_persist - toggle every switch, restart app, verify saved state
-
settings_voice_rate_persists - adjust speaking rate and verify value after relaunch
-
settings_audio_encoding_persists - choose MP3 and confirm selection survives restart
Reset
-
settings_reset_to_defaults - reset all TTS settings and verify confirmation
-
settings_reset_cancel - cancel reset flow and verify settings remain unchanged
Navigation
-
settings_history_button_navigates - tap History and verify empty state or recent sessions
-
settings_back_returns_home - navigate back and assert the home screen is visible
Accessibility
-
settings_controls_accessible_labels - verify controls expose stable accessible labels
-
settings_dynamic_type_layout - increase text size and verify rows remain tappable
-
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.
Build on open-source integrity
Extensible and with no vendor lock-in, Maestro is the foundation for thousands of teams’ mobile testing.
t@macbookpro Code % 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 (delta 1101), reused 743 (delta 723), pack-reused 31314
Receiving objects: 100% (32693/32693), 925.09 MiB | 13.99 MiB/s, done.
Resolving deltas: 100% (14496/14496), done.
---
t@macbookpro Code %
Surfaces
Build like the wind
Write and manage tests wherever you like, however fast you like.
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.
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.
1appId: com.apple.Maps
2---
3- launchApp:
4 clearState: true
5- runFlow: 6 when:
7 visible: "Allow “Maps” to use your location?"
8 commands:
9 - tapOn: "Allow While Using App" 10 label: Handle location permission if prompted
11
12- runFlow: 13 when:
14 visible: "What’s New in Maps"
15 commands:
16 - tapOn: "Continue" 17 label: Dismiss onboarding splash screen
18
19- tapOn: 20 id: "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: 29 when:
30 visible:
31 id: "More"
32 commands:
33 - tapOn: 34 id: "More"
35 label: Open more options if action bar is collapsed
36
37- tapOn: "Add to Favorites" 38
39- runFlow: 40 when:
41 visible: "Done"
42 commands:
43 - tapOn: "Done" 44 label: Close the detail card to return to map
45
46- tapOn: 47 id: "Search"
48- scrollUntilVisible: 49 element: "Favorites"
50 direction: DOWN
51- tapOn: "See All" 52
53- assertVisible: "Space Needle"
54- assertVisible: "400 Broad St"
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.
t@macbookpro ~ % maestro
Usage: maestro [-hv] [--[no-]ansi] [--verbose] [-p=<platform>] [--udid=<deviceId>] [COMMAND]
-h, --help Display help message
--[no-]color Enable / disable colors and ansi output
--p=<platform> (Optional) Select a platform to run on
--d=<deviceId> (Optional) Device ID to run on explicitly, can be a comma separated list of IDs
-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
Total flow runs
3069+1% m/m
Average run time
3min
Failed flow runs
23
Passing rate
99.25%+1% m/m
Run history
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.