Flutter Mobile Automation
Covers both E2E test automation and development workflow automation.
Recommended Setup: Maestro MCP + Dart MCP
Maestro MCP + Dart MCP combination is optimal for Flutter app E2E testing and development automation.
Dart MCP vs CLI Usage
Principle: Use MCP for operations requiring DTD connection, CLI for everything else
MCP Recommended (No CLI Alternative)
Operation Tool Reason
Launch app launch_app
Requires DTD URI
DTD connection connect_dart_tooling_daemon
MCP only
Hot reload hot_reload
Executed via DTD
Hot restart hot_restart
Executed via DTD
Widget tree get_widget_tree
Only available via DTD
Runtime errors get_runtime_errors
Only available via DTD
App logs get_app_logs
Get logs from running app
CLI Recommended (More Efficient Than MCP)
Operation CLI Command Reason
Device list flutter devices
Simpler output
Run tests flutter test
Better output, more options
Static analysis dart analyze
Better output
Format dart format .
Fast, shows diff
Add dependency flutter pub add <pkg>
Interactive
Get dependencies flutter pub get
Fast
Create project flutter create
More options
Build flutter build ios/apk
Detailed output
Typical Workflow
1. CLI: Build & Install
flutter build ios --simulator xcrun simctl install booted build/ios/iphonesimulator/Runner.app
2. MCP: Launch app & DTD connection
-> launch_app -> connect_dart_tooling_daemon
3. MCP: Debug during development
-> get_widget_tree, get_runtime_errors, hot_reload
4. CLI: Test & Analyze
flutter test dart analyze
Tool Overview
Maestro / Maestro MCP
-
E2E testing framework with first-class Flutter support
-
CLI: Write tests in YAML (maestro test .maestro/test.yaml )
-
MCP: Interactive operation from Claude Code (no YAML needed)
-
Take screenshots
-
Tap operations (text/id specification, no coordinate calculation)
-
Get view hierarchy
Dart MCP Server
-
MCP server for Flutter development integration
-
Get widget tree (Flutter internal structure)
-
Hot reload/restart
-
Get runtime errors
Mobile MCP (Reference)
-
Usually not needed as Maestro MCP can substitute
-
Use only for special cases requiring coordinate-based operations
Claude Code Setup
Recommended Settings (.claude/settings.json)
Share common permission settings in repository:
{ "permissions": { "allow": [ "Bash(flutter:)", "Bash(dart:)", "Bash(adb:)", "Bash(xcrun simctl:)", "Bash(maestro:)", "Bash(MAESTRO_DRIVER_STARTUP_TIMEOUT= maestro:)", "Bash(git:)", "Bash(gh:)", "WebSearch", "WebFetch(domain:github.com)", "WebFetch(domain:docs.maestro.dev)", "mcp__dart-mcp__", "mcp__maestro__*" ] } }
Maestro CLI Platform Selection
Recommended: iOS Simulator
iOS Simulator recommended for Maestro CLI execution.
Platform launchApp Stability Notes
iOS 18.x OK High Recommended
Android API 30 Warning Low Only works first time, then unstable
Android API 34+ NG
TCP forwarding / timeout errors
iOS E2E Test Execution
Start iOS simulator
xcrun simctl boot "iPhone 16 Pro"
Build & install iOS app
flutter build ios --simulator xcrun simctl install booted build/ios/iphonesimulator/Runner.app
Run test (increased timeout recommended)
MAESTRO_DRIVER_STARTUP_TIMEOUT=120000
maestro --device "<DEVICE_ID>"
test -e APP_ID=com.example.app
.maestro/test.yaml
Flutter + Maestro Best Practices
Using Semantics Widget
Maestro recognizes elements by semantic information. In Flutter, provide accessibility info with Semantics widget:
// Make identifiable by label Semantics( label: 'submit-button', child: ElevatedButton( onPressed: _submit, child: Text('Submit'), ), )
// Use identifier attribute (Flutter 3.19+) Semantics( identifier: 'login-button', child: ElevatedButton(...), )
Element Specification in Maestro
Recognize by tooltip text (FloatingActionButton etc.)
- tapOn: "Increment"
Recognize by text
- tapOn: "Submit"
Regex
- tapOn: text: ".Login."
Using identifier (recommended)
- tapOn: id: "login-button"
Semantics Naming Convention (Verified)
Pattern: {feature}-{element-type}[-{dynamic-id}]
Static elements:
- todo-fab-add # FAB
- search-field # Search field
- save-button # Save button
- category-chip-work # Category chip
Dynamic elements:
- todo-tile-{uuid} # Todo tile
- todo-checkbox-{uuid} # Checkbox
Tool Selection Guide
Feature Comparison
Feature Dart MCP Maestro MCP
Widget tree Detailed (Flutter internal)
Accessibility info
accessibilityText
Screenshot
Available
Element list
CSV format
Tap operation Requires setup Text/id specification
Hot reload Available
Runtime errors Available
E2E scenario
YAML / Interactive
Recommended Usage
Maestro MCP (UI operation & verification)
-
Take screenshots
-
Tap operations (text specification, no coordinate calculation)
-
View hierarchy verification
-
Create/run E2E test scenarios
Dart MCP (Development & debugging)
-
Detailed widget tree verification
-
Get runtime errors
-
Hot reload/restart
-
App launch and DTD connection
Typical Workflow
- Dart MCP: Launch app -> DTD connection
- Dart MCP: Check UI structure with widget tree
- Maestro MCP: Visual verification with screenshot
- Maestro MCP: Interactive tap operations
- Maestro CLI: Create/run E2E test scenarios
- Dart MCP: Check runtime errors on failure
Efficient State Verification Pattern
Recommended: Prioritize Accessibility Info
Verify screen state in this order:
inspect_view_hierarchy (First Priority)
-
Lightweight and fast
-
Get resource-id, accessibilityText, bounds info
-
Sufficient for identifying operation targets
take_screenshot (Only When Needed)
-
Use only when visual verification is required
-
Layout issues, colors, images
-
Reporting results to user
NG: screenshot -> verify -> operate -> screenshot -> ... OK: hierarchy -> operate -> hierarchy -> ... -> screenshot (final verification)
Development Flow
Feature Implementation Flow
-
Planning (Plan Mode)
- Start design with EnterPlanMode
- Clarify questions with AskUserQuestion
- Write implementation details in plan file
- Get approval with ExitPlanMode
-
Implementation
- Break down tasks with TodoWrite
- Update to completed after each task
- Minimize code changes
-
E2E Testing
- Dart MCP: Launch app & DTD connection
- Maestro MCP: Verify state with inspect_view_hierarchy (lightweight)
- Maestro MCP: Operate with tap_on / input_text
- Maestro MCP: Visual verification with take_screenshot (only when needed)
-
Commit & Push
- Conventional Commits format
- Commit per feature
- Push at appropriate timing
References
-
Maestro Flutter Testing
-
Mobile MCP
-
Dart MCP Server