Flutter
Test Flutter apps via the Semantics Tree. Use semanticLabel, Semantics widget, or identifier (Flutter 3.19+) instead of Keys for stable automation.
Maestro treats Flutter as a first-class citizen, supporting both pure and hybrid (add-to-app) mobile applications. Unlike internal tools that inject Dart code, Maestro interacts with the device elements that Flutter exposes through its Semantics Tree, ensuring your tests reflect the actual experience of an end-user.
Black-box approach
Maestro operates externally, orchestrating input events and validating outcomes based on the actual pixels and accessibility labels rendered on the device.
Zero Framework Dependencies: No
pubspec.yamlintegration is required. Maestro tests the compiled APK or IPA directly.Stability Across Upgrades: Your tests remain stable across Flutter version updates because Maestro does not depend on the internal widget tree.
System-Level Automation: Since Maestro lives at the OS level, it can handle system-level flows, like push notifications or permission dialogs, that in-app Dart frameworks cannot reach.
Element interaction strategies
To interact with a widget, Maestro needs it to have semantic information. By default, widgets that display text (like Text or TextField) provide this implicitly.
Interacting by semantics label (text)
Maestro can target any widget that displays text content. For widgets without implicit text, such as an Icon, you can manually provide a semanticLabel.
To target Icon, for example, in this Dart code, you need to add a label to an Icon so Maestro can "see" it. For more details, see the official Flutter Icon documentation. In the following example, semanticLabel is being used to add a label.
This way, you can easily identify the element when creating a flow:
The semantics widget
You can wrap any layout component, such as a Container or SizedBox, with a Semantics widget to make it inspectable by Maestro.
When you add semantics to a layout, it allows you to perform actions such as tapping on a visual area that does not inherently contain text. The following example adds a label using semantics, allowing Maestro to target the element during testing.
This way, you can easily interact with the element by referring to the label:
Semantics identifiers
As your app adds multi-language support or A/B tests, text-based labels can become brittle. The best practice is to use Semantic Identifiers.
This feature was contributed by the Maestro team to Flutter and is available in Flutter 3.19+.
This pattern creates a permanent link between your Dart code and your YAML Flow that never changes, even if you translate your app into 20 languages.
To use the pattern, the developer needs to assign a unique identifier that is invisible to the user but exposed to Maestro.
This way, the test can target that identifier using the id selector.
Why not use Flutter Keys?
Flutter Keys are designed for the Flutter engine to manage widget identity during state changes (like reordering a list). They are not exposed to the system's accessibility layer. Because Maestro lives outside the Flutter runtime, it cannot "see" Keys. Always use Semantics for automation.
Known limitations
Flutter Desktop: Maestro does not yet support Flutter for Desktop.
Flutter Web: It is fully supported by Maestro. It works identically to standard Web Testing. Simply use Semantics to make your web elements addressable.
Next steps
If you don't know how to create tests with Maestro, access the Quickstart guide to get up and running in minutes.
To learn how to create tests, refer to the Flows documentation. If you want to explore Maestro solutions, consult the appropriate documentation:
Last updated