断言与等待元素

A Maestro flow without assertions only tells you the app did not crash. Assertions verify that the app shows the correct content after each action. They are the part of the test that actually checks correctness.

Maestro provides a rich set of assertion commands: checking that elements are visible, not visible, contain specific text, or are enabled/disabled. Learning to write precise, targeted assertions is what distinguishes a useful E2E test from one that only provides false confidence.

assertVisible checks that an element with the given text or id is currently displayed on screen. It retries for up to 5 seconds by default, making it resilient to brief loading delays.

assertNotVisible is the opposite — it verifies that an element is NOT on screen. Use this to confirm that an error message disappears after the user fixes their input, or that a loading spinner is gone after data loads.

The default assertion timeout in Maestro is 5 seconds. If your app makes a network call before showing content, 5 seconds may not be enough on a slow CI machine or with a real network. Override the timeout per assertion with the timeout option (in milliseconds).

A good practice is to set longer timeouts on the first assertion after a network call and shorter ones for assertions on content that should appear immediately after a tap (like a navigation transition).

Animations can cause assertion failures even when the content is technically visible. If an element is animating in (fading, sliding, scaling), Maestro might tap or assert on it before the animation completes, leading to flaky tests.

Add waitForAnimationToEnd after a tap that triggers a screen transition or an animated list update. Maestro pauses until the UI is fully still before continuing. This eliminates the most common source of flakiness in mobile E2E tests.

Content below the fold is not visible to Maestro assertions even if it is rendered. Use the scroll command to bring off-screen content into view before asserting on it.

The scroll command supports directions (UP, DOWN, LEFT, RIGHT) and a speed option. You can also scroll within a specific container by adding an element filter, which is useful for scrollable content inside a modal or a tab panel.

Sometimes you want to assert on content that contains a dynamic value — like a username, count, or timestamp — that you cannot hard-code. Maestro supports regex patterns in text assertions to match partial or dynamic content.

Add regexp: true and use a regular expression in the text field. For example, match any string that starts with 'Hello,' followed by any name, or match a timestamp pattern like \d{2}:\d{2}.

Mobile apps sometimes show optional dialogs (permission requests, update prompts, onboarding) that may or may not appear depending on device state. Use optional: true on tapOn to dismiss these dialogs only if they appear.

Combine optional taps with conditional flows using Maestro's JavaScript-based condition syntax. If a particular element is visible, take one path; otherwise take another. This makes your flows resilient to non-deterministic UI states.

assertVisible checks for an element in the current view. For more complex conditions — like verifying an element's count or checking that the screen title matches a pattern — use assertCondition with a JavaScript expression.

The JavaScript expression has access to the current screen's elements. Return true from the expression if the condition passes. This gives you the full power of JavaScript for complex assertions that go beyond simple element visibility.

Maestro can take screenshots at any point in a flow with the takeScreenshot command. These screenshots are saved to disk and included in the test report. Use them to capture UI state at critical checkpoints for visual documentation or debugging.

Provide an absolute path for the screenshot file. Maestro also automatically takes a screenshot when an assertion fails, so you get a visual of exactly what was on screen when the test broke.

Use the swipe command to simulate swipe gestures. You can swipe from a percentage-based start point to an end point, which is useful for dismissing modals, navigating carousels, or triggering swipe-to-delete on list items.

Specify start and end points as percentages of the screen dimensions. For example, to swipe left on a card to reveal a delete button: start at 80% from the left, end at 20% from the left, at 50% height.

The best assertions test the user-visible outcome, not implementation details. Instead of asserting that a specific component ID is present, assert on the text the user would see. Instead of asserting on a loading state, assert on the final content that appears after loading.

Keep assertions specific enough to catch real bugs but flexible enough to survive minor UI changes. An assertion that checks the exact spacing or color of a button is fragile — an assertion that checks the button's label and that it is tappable is much more durable.

In this lesson you learned: how to use assertVisible, assertNotVisible, and timeout to write precise Maestro assertions, how waitForAnimationToEnd prevents flaky tests caused by UI animations, and how to use optional: true for non-deterministic dialogs and swipe commands for gesture-driven UI. Next up we write multi-screen user journey flows that test complete app features end to end.