maestro-flutter-instructions

Instruction Command

When this command is used, acknowledge that you understand these instructions and will follow them throughout the conversation. Then await the user's request.

---

🎯 Maestro Flutter Testing Instructions

💡 Comprehensive guide for testing Flutter applications with Maestro's first-class Flutter support.

Flutter Widget Interaction

Semantics-Based Testing

Maestro interacts with Flutter widgets through their semantics information. By default, this includes all widgets that display text (Text widget data, TextField hintText, etc.).

Basic Text Interaction

# Tap on a Text widget
- tapOn: Open Browser

# Enter text in a TextField
- tapOn: Enter your username
- inputText: charlie_root

# Assert text visibility
- assertVisible: Welcome back, dear Test User!

Adding Semantics to Widgets

For widgets without implicit semantics (like Icon), add semantics explicitly:

// Using semanticLabel on Icon
FloatingActionButton(
  onPressed: _incrementCounter,
  child: Icon(Icons.add, semanticLabel: 'fabAddIcon'),
)

- tapOn: fabAddIcon

Wrapping with Semantics Widget

Semantics(
  label: 'funky yellow box',
  child: Container(
    color: Colors.yellow,
    width: 100,
    height: 100,
  ),
)

- tapOn: funky yellow box

Semantic Identifiers (Flutter 3.19+)

For better test maintainability, use semantic identifiers instead of labels:

Semantics(
  identifier: 'signin_button',
  child: ElevatedButton(
    onPressed: _signIn,
    child: Text('Sign in'),
  ),
)

- tapOn:
    id: signin_button

Best Practices

Enforcing Accessibility Identifiers

Create custom widgets that require identifiers:

class FancyButton extends StatelessWidget {
  FancyButton({
    super.key,
    required this.identifier,
    required this.onPressed,
  });

  final String identifier;
  final VoidCallback onPressed;

  @override
  Widget build(BuildContext context) {
    return Semantics(
      identifier: identifier,
      child: RawMaterialButton(
        onPressed: onPressed,
        // ...
      ),
    );
  }
}