Testing Multi-Screen User Journeys

A user journey is a sequence of interactions that spans multiple screens to accomplish a meaningful goal. Examples include the registration journey (onboarding → email signup → profile setup → home), the purchase journey (browse → add to cart → checkout → confirmation), and the content creation journey (home → compose → preview → post).

E2E tests that cover complete journeys provide the most value because they verify that all the pieces of your app work together correctly. A unit test can confirm that a form validates correctly, but only a journey test confirms that a validated form actually navigates to the next screen.

Before writing the YAML, sketch the journey on paper: which screens appear, what the user taps or types on each screen, and what the expected final state is. Identify the happy path first — the normal flow without errors — then add edge case flows for error states.

Break the journey into logical phases and comment your YAML accordingly. Comments in YAML start with #. Clear comments make the flow readable to teammates who did not write it and help you debug which phase failed when the test reports an error.

The registration journey walks through the sign-up form, validates the confirmation screen, and verifies that the user lands on the home screen. Use the env section to parameterize test data so you can run the same flow with different users by changing just the environment variables.

Each phase ends with an assertVisible to confirm the transition was successful before starting the next phase. This gives you precise failure location in the test report — you know exactly which screen transition failed.

A common journey is: log in, browse a list, open an item, interact with it, and go back. This tests navigation forward and backward, data loading on each screen, and the interaction on the detail screen.

Use the back command to simulate pressing the device back button on Android. On iOS, swipe back or tap the back button with tapOn: text: 'Back'. Test both directions of navigation to catch bugs where going back leaves the app in a broken state.

Apps with bottom tab navigators require testing that each tab opens the correct screen. Test the initial tab, switch to each other tab, verify the content loads, and switch back. This catches wiring bugs where tabs navigate to the wrong screen.

Use tapOn with the tab label text or the id of the tab bar button. After switching tabs, always assert on unique content that confirms the correct tab is active.

Journey tests should cover both the happy path and the error path. A separate flow for the error path verifies that validation errors appear correctly, the user can fix them, and the form successfully submits after correction.

This catches bugs like: error messages not appearing, form not re-enabling after a failed submission, or validation not re-running after the user fixes an input. These bugs are hard to find without an E2E test because they require multiple interactive steps to reproduce.

Modals and bottom sheets block interaction with the underlying screen. Test that modals appear correctly, contain the expected content, and dismiss properly. After dismissing a modal, assert that the underlying screen is still in the correct state.

For confirmation dialogs (like delete confirmation), test both paths: tapping Confirm to complete the action and tapping Cancel to abort it. The Cancel path is often untested and frequently has bugs.

Hard-coding test data in flows makes them fragile when the test account changes or the app requires unique data per run. Use Maestro's env section at the top of the flow file to define variables, and pass them on the command line to override them at runtime.

You can also pass env variables from CI systems using command-line arguments. This lets you use different test accounts or API endpoints for different environments without changing the YAML files.

Deep links open your app directly at a specific screen. Test them in Maestro by using the openLink command to trigger the deep link URL and then asserting that the app opened to the correct screen.

Deep link tests verify that your app handles incoming URLs correctly and navigates to the right place. They also confirm that the screen renders correctly when navigated to directly (without passing through the normal navigation flow).

As your test suite grows, organize flows in directories by feature rather than by screen. This makes it easy to run all tests for a specific feature and to find the relevant test when a feature breaks.

A recommended directory structure: maestro/flows/auth/ for authentication flows, maestro/flows/feed/ for feed features, maestro/flows/profile/ for profile features, and maestro/flows/subflows/ for shared steps. Run a specific feature with maestro test maestro/flows/auth/.

E2E tests are the most expensive tests to maintain because UI changes break them even when the logic is correct. Minimize maintenance by: querying by semantic content (user-visible text) instead of implementation details (component IDs), keeping flows focused on critical paths, and extracting reusable steps into subflows.

When a flow breaks after a UI redesign, update the query in the tapOn or assertVisible to match the new text or ID. The test logic itself often does not change — only the selector. This is a feature, not a bug: the test caught that the UI changed in a user-facing way.

Test your understanding of React Native Mobile Development concepts from this lesson.

In this lesson you learned: how to plan and write multi-screen journey flows that test complete features end to end, how to test both happy paths and error paths including form validation and confirmation dialogs, and how to organize flows by feature for a maintainable E2E test suite. Next up we integrate Maestro tests into a GitHub Actions CI pipeline to catch regressions automatically on every pull request.