// E2E testing and mobile automation for Flutter apps. Use when creating/running tests with Maestro, Mobile MCP, and Dart MCP.
| name | flutter-mobile-automation |
| description | E2E testing and mobile automation for Flutter apps. Use when creating/running tests with Maestro, Mobile MCP, and Dart MCP. |
Covers both E2E test automation and development workflow automation.
Maestro MCP + Dart MCP combination is optimal for Flutter app E2E testing and development automation.
Principle: Use MCP for operations requiring DTD connection, CLI for everything else
| 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 |
| 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 |
# 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
maestro test .maestro/test.yaml)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__*"
]
}
}
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 |
# 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
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(...),
)
# Recognize by tooltip text (FloatingActionButton etc.)
- tapOn: "Increment"
# Recognize by text
- tapOn: "Submit"
# Regex
- tapOn:
text: ".*Login.*"
# Using identifier (recommended)
- tapOn:
id: "login-button"
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
| 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 |
Maestro MCP (UI operation & verification)
Dart MCP (Development & debugging)
1. Dart MCP: Launch app -> DTD connection
2. Dart MCP: Check UI structure with widget tree
3. Maestro MCP: Visual verification with screenshot
4. Maestro MCP: Interactive tap operations
5. Maestro CLI: Create/run E2E test scenarios
6. Dart MCP: Check runtime errors on failure
Recommended: Prioritize Accessibility Info
Verify screen state in this order:
inspect_view_hierarchy (First Priority)
take_screenshot (Only When Needed)
NG: screenshot -> verify -> operate -> screenshot -> ...
OK: hierarchy -> operate -> hierarchy -> ... -> screenshot (final verification)
1. Planning (Plan Mode)
- Start design with EnterPlanMode
- Clarify questions with AskUserQuestion
- Write implementation details in plan file
- Get approval with ExitPlanMode
2. Implementation
- Break down tasks with TodoWrite
- Update to completed after each task
- Minimize code changes
3. 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)
4. Commit & Push
- Conventional Commits format
- Commit per feature
- Push at appropriate timing
UI theming skill for applying brand designs to Flutter apps. Use when user asks to 'apply X style', 'change theme to Y', 'make it look like Z', or provides reference images for UI design.
Modern UI design guidelines for Flutter apps. Achieve refined visuals based on Material Design 3.
Systematic requirements gathering through AskUserQuestion. Use when starting development to clarify app specifications.
Self-review before completing tasks. Multi-perspective verification using Gemini CLI + Claude subagent.