Flutter Mobile Automation

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)

CLI Recommended (More Efficient Than MCP)

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.

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

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

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

Efficient State Verification Pattern

Recommended: Prioritize Accessibility Info

Verify screen state in this order:

1. inspect_view_hierarchy (First Priority)

   • Lightweight and fast
   • Get resource-id, accessibilityText, bounds info
   • Sufficient for identifying operation targets

2. 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

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

References

• Maestro Flutter Testing
• Mobile MCP
• Dart MCP Server