Wait commands

Control timing with wait commands for animations, network calls, and UI updates.

In a perfect world, apps respond instantly. In reality, network latency, slow animations, and background processing can cause tests to fail because Maestro tries to interact with an element that isn't ready yet.

Maestro provides several ways to handle these timing issues. This guide helps you choose the right strategy to make your Flows resilient and fast.

Automatic waiting

Before using a dedicated wait command, remember the golden rule of Maestro timing:

If you expect an element to appear or disappear within a short period, use an assertion.

Maestro’s assertions are smart. They don't just check once and fail, they poll the UI continuously until the element appears or the timer expires. This makes them the most efficient way to wait because the test continues immediately after the condition is met.

• assertVisible: Best for waiting for a screen to load, a success message to appear, or a button to become active.

• assertNotVisible: Best for waiting for a loading spinner to disappear or a modal to close.

# assertVisible example
- tapOn: "Submit"
- assertVisible: "Success!" # Maestro will wait for this to appear

Wait strategies

When assertions aren't enough, such as for long-running processes or stabilizing complex animations, you can use one of the specific wait commands.

Waiting for long processes (extendedWaitUntil)

Use extendedWaitUntil for slow network responses (like processing a payment or generating a large report) that are guaranteed to take longer than a few seconds.

This command optimizes your test because Maestro moves on immediately if the element appears faster than the timeout.

- extendedWaitUntil:
    visible: "Payment Confirmed"
    timeout: 30000            # Wait up to 30 seconds

Set realistic timeouts

Avoid setting every timeout to 60 seconds. If a screen should load in 5 seconds, let the default assertion handle it. This helps catch performance regressions early.

Waiting for UI stability (waitForAnimationToEnd)

Sometimes elements are visible but still moving (e.g., a list sliding into place or a side menu opening). Interacting too early can cause missed taps.

Use the waitForAnimationToEnd command to ensure the test continues only after the animation finishes.

- waitForAnimationToEnd:
    timeout: 5000 # Wait up to 5s for movement to stop

Ghost taps

If you experience "ghost taps" (tapping a button that exists but isn't yet clickable), combine your wait logic with retryTapIfNoChange: true in your tapOn command.

Next steps

For full technical details and parameter lists, visit the individual command pages:

• assertVisible: Your primary tool for standard waits.

• assertNotVisible: For waiting for elements to disappear.

• extendedWaitUntil: For smart, long-duration waiting.

• waitForAnimationToEnd: For stabilization after UI transitions.

Or continue learning about flow control by exploring the Loops or Conditions guides.