aleksandr-chaika 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
- ADD semantic labels —
Key()/Semanticson all interactive widgets - WRITE flows in YAML — simple, readable, no code
- RUN on emulator first, then real devices
- CAPTURE screenshots at key assertion points
- 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
└──────────────────────────────────────────┘