Mastering Maestro: A Guide to Crafting Robust Test Flows

Best practices to follow when writing Mobile app test cases in the Maestro framework

So, you’ve decided to use Maestro for your mobile UI testing. Great choice! Maestro’s simplicity, using YAML for writing tests, is one of its biggest strengths. You can get up and running with meaningful tests in no time.
But as your test suite grows, how do you keep your flows clean, maintainable, and powerful? In this post, we’ll explore some best practices for structuring your Maestro flows to handle different testing scenarios gracefully.

The Core: Your First Simple Flow

At its heart, a Maestro flow is a sequence of commands. You tell Maestro what to do, step by step. Here’s a classic login flow:

This is straightforward and gets the job done. But we can do better.

Best Practice 1: Embrace Modularity with runFlow

Imagine you have ten test cases that require the user to be logged in. Are you going to copy-paste the login steps every time? Please don’t.

Maestro lets you run flows from other flows. This is perfect for creating reusable “sub-flows” for common actions like logging in, logging out, or navigating to a specific part of your app.

Let’s make our login.yaml a reusable module. We can use parameters to make it more flexible.

Now, any other flow can just call this one:

Clean, right? If your login UI changes, you only have to update one file.

Best Practice 2: Keep Your Data Out of Your Logic

Hardcoding values like usernames and passwords in your test flows is a maintenance nightmare. We already saw how to use environment variables with runFlow. You can also use external data files to separate your test data from your test logic.

Maestro can use environment variables set from the command line. This makes it easy to run the same flow with different data sets.

For example, you could run your test from the command line like this:

$ maestro test --env-file .env.user1 flows/test_user_profile.yaml

Best Practice 3: Handle the Unexpected with Conditional Logic

Apps can be unpredictable. A promotional pop-up, a “rate our app” dialog, or a slow network connection can all throw a wrench in your tests. Maestro’s when condition is your best friend here.

This flow will only try to dismiss the “What’s New” dialog if it appears. Your tests just became a lot more resilient.

Structuring for Success

Here’s a sample directory structure that puts these practices into action:

├── flows/
│   ├── login.yaml
│   ├── onboarding.yaml
│   └── main_app/
│       ├── test_feature_A.yaml
│       └── test_feature_B.yaml
├── config.yaml

• flows/: Contains all your test flows.
• Reusable flows: login.yaml and onboarding.yaml are great examples of reusable sub-flows.
• Feature-specific flows: Group tests for specific features in subdirectories like main_app/.

By adopting these simple best practices, you’ll be well on your way to building a Maestro test suite that is not just effective, but also a joy to work with. Happy testing!