A calmer route: how to use maestro flows for flaky mobile screens

The practical answer to how to use maestro is to start with one screen that misbehaves, then let the flow file explain what the app is actually showing. In the mobile UI automation sense, Maestro works best when a test reads like a short route through a real user moment. The common mistake is to draft a whole journey before checking the first tap. A calmer start is to open the Studio view, inspect the hierarchy, and note the text, id, or accessibility label that makes one control recognizable.

how to use maestro Studio to inspect a single screen

The first screen in how to use maestro Studio is the hierarchy view, because it turns a visual screen into named targets. Select the button, field, or card that caused the test to fail, then compare its visible label with the identifier the flow is using. If the label is split across containers, the inspector usually shows which node owns the tap. That small check prevents a long flow from failing on a target that was never stable.

Keep the inspected screen open while you edit the first steps. Change one target at a time, run that fragment, and look at the next screen before adding more. The Studio view is a reading tool, not a substitute for the flow file; it helps you decide what to name, then you return to the file and make the step explicit.

Reading the flow file before the first tap

A useful repair habit when learning how to use maestro is to read the flow file from top to bottom before pressing run. Each step should name one action and one expected state. If a tap step depends on a screen that has not loaded, move the wait earlier instead of adding a pause after the failure. If two steps assert the same label, one of them is probably noise.

Write the route in the order a user would experience it: launch, land, choose, confirm, and read the result. Short comments in the flow file can explain why a selector exists, especially when the visible label is translated or abbreviated. The goal is not a clever file; it is a file another person can repair after a screen changes.

Selectors that survive dynamic text in Maestro

A practical rule for how to use maestro with dynamic text is to prefer an id or accessibility label, then fall back to text only when the wording is stable. Prices, timestamps, counts, and user names make poor anchors because they change between runs. When a card contains repeated text, target the container first and then the control inside it, so the flow does not tap the first matching label on the screen.

Keep selector choices close to the step that uses them. A separate “selector notes” section at the bottom of the flow file is easy to forget. If a screen has two similar buttons, give the flow enough context to tell them apart, such as the surrounding heading or the order of visible labels. That context is what makes the next test run predictable.

Assertions and waits for a slow checkout panel

The safer pattern for how to use maestro on a slow checkout panel is to wait for a visible state, not for a fixed number of seconds. An assertion should prove that the screen reached the state the next step expects. If the panel shows a spinner, wait for the confirmation label or the enabled button; a blind pause hides the real problem and makes the flow slower than it needs to be.

Put the assertion immediately before the action it protects. That placement makes a failure readable: the report shows which expected state did not appear, not just which tap failed later. When a wait is needed, tie it to one clear element and keep the timeout modest. A flow that waits for the right label is easier to trust than one that waits for the clock.

When a Maestro flow should split into two

Split a flow when the app crosses a boundary that has its own setup, such as signing in, choosing a saved profile, or returning to a clean home screen. A single long flow is hard to diagnose because one early failure hides every later check. Two shorter flows can share the same starting state and still report separate results, which makes the failing screen obvious.

Name each flow by intent rather than by screen order. A name like “profile update confirmation” tells the next person what the flow protects; a name like “test 4” does not. After a split, rerun both flows from the same clean state to confirm that the shared setup still works.

The last check for how to use maestro is to rerun the flow after changing one selector, then read the report as if you were new to the file. If the step names a visible state, the target has a stable anchor, and the wait is tied to a real screen change, the flow will be easier to keep alive. That habit matters more than a long first draft.