Maestro Flutter

Maestro Flutter E2E Testing Guide

Reference Guide

| Topic | Reference | Use When | |-------|-----------|----------| | Flow Patterns | references/flow-patterns.md | Writing YAML flows, Flutter-specific tips | | CI & Visual Regression | references/ci-visual-regression.md | CI/CD setup, visual comparison, troubleshooting |

Core Principles

1. ADD semantic labels — Key() / Semantics on all interactive widgets
2. WRITE flows in YAML — simple, readable, no code
3. RUN on emulator first, then real devices
4. CAPTURE screenshots at key assertion points
5. USE visual regression for Pixel Perfect validation

TestKeys Pattern (MANDATORY)

// lib/core/constants/test_keys.dart
abstract class TestKeys {
  static const emailField = Key('email_field');
  static const passwordField = Key('password_field');
  static const loginButton = Key('login_button');
  static const registerButton = Key('register_button');
  static const homeTab = Key('home_tab');
  static const profileTab = Key('profile_tab');
  static const loadingIndicator = Key('loading_indicator');
  static const errorMessage = Key('error_message');
}

Project Structure

.maestro/
├── config.yaml
└── flows/
    ├── auth/
    │   ├── login.yaml
    │   └── register.yaml
    ├── {feature}/
    │   └── {action}.yaml
    └── smoke_test.yaml

Flow YAML Syntax

appId: com.example.myapp
name: User Login
---
- launchApp:
    clearState: true
- extendedWaitUntil:
    visible: "Welcome"
    timeout: 10000
- tapOn:
    id: "email_field"
- inputText: ${TEST_EMAIL}
- tapOn:
    id: "password_field"
- inputText: ${TEST_PASSWORD}
- tapOn:
    id: "login_button"
- waitForAnimationToEnd
- assertVisible:
    id: "home_tab"
- takeScreenshot: "login_success"

Key Commands

| Command | Description | |---------|-------------| | tapOn: { id: "key" } | Tap by widget Key | | inputText: "value" | Type text | | assertVisible: "text" | Assert visible | | assertNotVisible: "text" | Assert gone | | extendedWaitUntil | Wait for element | | waitForAnimationToEnd | Wait animations | | takeScreenshot: "name" | Screenshot | | runFlow: path.yaml | Reuse flow | | launchApp: { clearState: true } | Fresh start |

Running Tests

flutter build apk --debug
maestro test .maestro/flows/

Testing Pyramid

              ┌─────────────────┐
              │    Maestro      │  10% — Full user journeys
              └────────┬────────┘
            ┌──────────┴──────────┐
            │   Widget Tests      │  20% — UI components
            └──────────┬──────────┘
  ┌────────────────────┴────────────────────┐
  │              Unit Tests                  │  70% — Business logic
  │  (BLoC, UseCases, Repositories)          │  mocktail, bloc_test
  └──────────────────────────────────────────┘

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aleksandr-chaika
• Source: aleksandr-chaika/flutter-clean-arch-skills
• License: MIT

Install and usage instructions live in the source repository linked above.