Exit course
Chapter 6 of 10 Beginner 8 min read 3 quick checks Updated

Debugging Flaky Maestro Flows

On this page
  1. Step 1: read what the CLI already told you
  2. Step 2: see what Maestro sees
  3. Step 3: classify the flake
  4. Step 4: decide about retries
  5. Recording runs
  6. Reports for CI
  7. Debugging cloud runs

Maestro's automatic waiting removes a whole class of timing bugs, but flows still fail, and some fail only sometimes. This chapter is a working method: where to look first, which tools show you what Maestro sees, and which fix matches which kind of flakiness.

Step 1: read what the CLI already told you#

A failing maestro test prints the failed command, the reason, and the path of a debug folder:

Assert that "15" is visible... FAILED

Assertion is false: "15" is visible

==== Debug output (logs & screenshots) ====
/Users/you/.maestro/tests/2026-11-10_103042

That folder is the first place to look. By default Maestro writes artifacts under ~/.maestro/tests (%userprofile%\.maestro\tests on Windows), one timestamped folder per session. Point it somewhere predictable with --test-output-dir, or testOutputDir in config.yaml, especially on CI where you want to upload it:

maestro test --test-output-dir build/maestro-results flows/

What you will find inside depends on your Maestro version. Current releases create a sub-folder per flow containing a commands.json (every executed step with its status, duration and error), a logs/ folder with maestro.log and the device log (logcat on Android, the simulator log on iOS), a screenshot of the failing step and the view hierarchy at that moment as JSON. Older releases put the same kinds of files directly in the session folder. Either way, the screenshot of the failing step is usually enough to explain the failure.

In chapter 2, that screenshot showed 100 + 50 = 150 and explained the bug in seconds: the cursor was in the wrong place. Look before you change anything.

Step 2: see what Maestro sees#

When a selector does not match, the question is always "what does the accessibility tree actually contain?". Three tools answer it:

  • maestro hierarchy prints the tree for whatever is on screen right now. Search it for the text you expected. You might find the label is Log in and not Login, that the id is set on a container rather than the input, or that the element you want has no text at all.
  • Maestro Studio, the desktop app, shows the same tree visually: hover an element on the mirrored device to see its attributes, right-click it to insert a command into your flow, and run a flow step by step with a recording of each run.
  • maestro test -c (continuous mode) re-runs the flow every time you save, which turns "tweak selector, re-run" into a tight loop.

Add --verbose (a global option, so before the subcommand: maestro --verbose test flow.yaml) for more detail on what each command did, and console.log from JavaScript lands in maestro.log.

tapOn: "Login" fails with element not found, but you can see the button on screen. What is the fastest next step?

The label may be Log in, or the text may sit on a different element. The hierarchy shows what Maestro actually sees; retries and timeouts will not fix a selector that never matches.

Step 3: classify the flake#

A flaky flow is one that sometimes passes. Before reaching for a retry, decide which kind of problem it is. Each has a different fix.

Symptom Likely cause Fix
Fails on slow runs with "not visible" The screen genuinely takes longer than the assertion's built-in wait (about 7 seconds) extendedWaitUntil with a realistic timeout
Tap "succeeds" but nothing happens Tapped before the view was ready to respond retryTapIfNoChange: true on that tapOn, or wait for an element that only exists once the screen is ready
Tap lands on the wrong item Element still moving after a transition waitForAnimationToEnd, or disable animations on the device
Fails only after another flow ran State leaking between flows (logged in, cached data) clearState in launchApp, or an onFlowComplete cleanup hook
Fails only in parallel runs Two flows share an account or test record Give each flow its own data, created through your API
Different element tapped on another device Ambiguous selector or coordinates Use an id, or narrow with index / relational selectors

Two of these in YAML:

- tapOn: "Pay now"
- extendedWaitUntil:
    visible: "Payment confirmed"
    timeout: 30000

- tapOn:
    id: "refresh_button"
    retryTapIfNoChange: true

Keep timeouts honest. If a screen should load in two seconds, a 60-second timeout hides a performance regression.

A real one: the keyboard that would not go away#

Chapter 3's flow originally called hideKeyboard on both platforms. On the iOS simulator it failed with:

Couldn't hide the keyboard. This can happen if the app uses a custom input
or doesn't expose a standard dismiss action.

hideKeyboard has no native API to call: on Android it sends a back event, on iOS it performs small swipes and hopes the keyboard auto-hides. A number pad with no return key gives it nothing to work with. The options are to tap a neutral, non-interactive element (a title or label) to move focus away, to skip the step where the keyboard does not cover anything you need, or to restrict it to the platform where it works, as chapter 3 does with when: { platform: Android }.

A flow passes when run alone but fails whenever the onboarding flow ran before it on the same device. Which fix matches?

Failing only after another flow is state leaking between flows. Timing fixes do not touch the cause.

Step 4: decide about retries#

retry and runner-level retries are legitimate for things outside your control, like a third-party login page. They are not a fix for your own app being unreliable. A sensible policy:

  1. Fix the flow if the cause is a selector or timing problem in the test.
  2. File a bug if the app really does fail sometimes. That is a finding, not noise.
  3. While the bug is open, tag the flow (for example flaky) and exclude the tag in CI so the pipeline stays trustworthy. Chapter 6 shows how.

Recording runs#

For bugs you need to show someone, record the screen. Inside a flow:

- startRecording: checkout
- tapOn: "Checkout"
- assertVisible: "Order placed"
- stopRecording

The video is saved in the flow's artifact folder. maestro record flow.yaml renders a shareable video of a whole flow; add --local to render it on your machine (marked beta in the docs).

Reports for CI#

maestro test can write a report alongside the artifacts:

maestro test --format junit --output build/report.xml flows/
maestro test --format html --output build/report.html flows/

JUnit is what most CI systems display as test results. The report is written to the --output path, not into the artifacts folder, so upload both.

CI uploads the --test-output-dir folder, but the JUnit file from --format junit is never in it. Why?

Reports and artifacts go to separate places. Upload both, or the CI test tab stays empty.

Debugging cloud runs#

When the same flow fails on a remote device, you cannot run maestro hierarchy against it, so artifacts matter even more. On TestingBot each result includes a video, test logs and the steps of every flow, visible in the dashboard; the CLI's --download-artifacts failed option downloads the logs, screenshots and video of failed flows, as described in the Maestro results section of the docs. The Maestro REST API exposes the same data for scripts. Next, organising flows into a suite you can filter and scale.