Android Native

Black-box testing for Android Views and Jetpack Compose via the Accessibility layer. Target elements by text, Resource ID, Content Description, or testTag.

Maestro provides a black-box testing approach for native Android applications. By interacting with the app through the Android Accessibility layer rather than internal code instrumentation, you can test production-ready binaries without modifying your source code.

Technical advantages

• Zero Instrumentation: No custom Gradle configurations, build.gradle dependencies, or test-specific APK builds are required. You test the exact binary your users receive.

• Refactoring Resilience: Migrating your UI implementation will not break your tests as long as the user-visible text or semantic IDs remain consistent.

• UI-Layer Interaction: Maestro interacts with rendered UI elements, ensuring that tests validate the actual user experience rather than internal component states.

Element interaction strategies

In Android development, Maestro leverages the accessibility layer of the device to identify and interact with elements via primary methods:

• Text Selection: Target any view with a text property (e.g., Button, TextView).

  - tapOn: "Login"

• Resource ID: Access views by their android:id. This is ideal for disambiguating identical text elements.

  - tapOn:
      id: "login_button"

• Content Description: The android:contentDescription attribute is surfaced as a text property, making it the "gold standard" for automating icons and image-based buttons.

  - tapOn: "Settings Icon"

• Hints: For input fields that have not yet been filled, the android:hint attribute is also exposed to the text selector.

Handling lists and dynamic content

Native Android often uses RecyclerView or LazyColumn for long lists. Maestro abstracts the complexity of view recycling through intelligent scrolling.

Instead of calculating scroll offsets, use the built-in intelligence of Maestro to find elements that are currently off-screen:

- scrollUntilVisible:
    element:
        text: "Item #50"
    direction: DOWN

Maestro will automatically swipe down, wait for the next items to load, and stop only when the target element is detected in the view hierarchy.

Known limitations

While Maestro can detect and tap on views containing Unicode characters, direct inputting (typing) of Unicode text via the inputText command is currently not possible.

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:

• Maestro Studio

• Maestro CLI

• Maestro Cloud