Maestro

Maestro is a declarative UI testing framework for mobile apps. Instead of writing test code in a general-purpose language, you describe user journeys as YAML flows: launch the app, tap visible controls, enter text, assert that expected content appears, and repeat the flow in CI.

This tutorial covers Maestro as a general framework and then explains how to relate that workflow to webmate’s app testing features without assuming direct Maestro execution support.

Goal

By the end of this tutorial you will be able to create a Maestro flow, run it against an app, organize repeated journeys, pass variables, and decide where Maestro fits next to webmate workflows such as app upload, manual inspection, and Appium-based automation.

Before You Start

You need a mobile app that can run on an Android emulator, iOS simulator, or supported device, and you need the Maestro CLI installed in the environment where flows will run. You should also know the app ID. On Android, this is the package name. On iOS, this is the bundle identifier.

Maestro works best for user journeys that can be described in visible steps. It is a good fit for smoke tests, onboarding checks, login flows, and regression checks that should remain readable by both developers and QA engineers.

Project Setup

A common layout keeps flows in a dedicated folder:

1
2
3
4

maestro/
  login.yaml
  checkout.yaml
  smoke.yaml

A simple flow starts with the app ID and then a list of commands:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

appId: com.example.app
---
- launchApp:
    clearState: true
- tapOn: "Email"
- inputText: "tester@example.com"
- tapOn: "Password"
- inputText: "correct-horse-battery-staple"
- tapOn: "Sign in"
- assertVisible: "Dashboard"

The flow is intentionally readable. Each command describes an action or assertion in the same order a user would perform it.

Step 1: Launch the App Cleanly

Use launchApp at the start of a flow. The clearState option is useful for smoke tests that need a fresh app state.

1
2

- launchApp:
    clearState: true

Do not clear state for every flow by default. Some suites intentionally reuse a logged-in session or preloaded data. Choose the state strategy per suite so failures are understandable.

Step 2: Tap and Type Through the Journey

Maestro commands can target visible text, identifiers, and patterns. Prefer stable labels and accessibility identifiers where the app exposes them.

1
2
3
4
5
6
7
8

- tapOn: "Create account"
- tapOn:
    id: "email_input"
- inputText: ${USERNAME}
- tapOn:
    id: "password_input"
- inputText: ${PASSWORD}
- tapOn: "Continue"

Variables use the ${VARIABLE_NAME} syntax. Pass secrets through the execution environment or CI secret store rather than committing them in flow files.

Step 3: Assert Results

Assertions should describe user-visible outcomes. If a login flow succeeds, assert the dashboard, profile name, or another stable result rather than a transient spinner disappearing.

1
2

- assertVisible: "Welcome back"
- assertNotVisible: "Invalid password"

For flows that depend on asynchronous work, Maestro’s command model is designed to tolerate common UI delays. Still, the app should expose stable completion signals; hidden timers and indefinite loading states make any UI automation harder.

Step 4: Organize Suites

Small flow files are easier to review than one large file. Use a workspace config when you need inclusion rules, tags, execution order, or output directories.

1
2
3
4
5
6
7
8

flows:
  - "maestro/smoke/*"
  - "maestro/regression/*"
includeTags:
  - smoke
executionOrder:
  continueOnFailure: false
testOutputDir: maestro-results

Use tags to split fast smoke checks from slower regression flows. A pull request should run the flows that catch obvious breakage quickly. Nightly jobs can run more devices, accounts, and longer journeys.

Step 5: Run Locally and in CI

Run a single flow while developing:

1

maestro test maestro/login.yaml

Run a folder or workspace in CI:

1

maestro test maestro/

A CI job usually builds the app, starts or selects a device, installs the app, and runs Maestro. Keep app build and test execution logs as artifacts so failures can be diagnosed later.

How This Maps to webmate

The existing repository documents webmate app upload, mobile device access, Appium execution, manual testing, and Workbench inspection. It does not document direct Maestro execution as a webmate automation capability. Treat Maestro as a local or CI-side mobile automation framework unless your team has a separate, verified integration.

webmate can still support the surrounding workflow. Use webmate to manage app packages, inspect behavior manually, compare device behavior, or run Appium suites where direct webmate automation is required. If a Maestro flow reveals a defect, the same app version and scenario can be reproduced in webmate Workbench for investigation and reporting.

Debugging

When a tap fails, check whether the target text or identifier is present on the screen. Permission dialogs, first-run onboarding, and network errors often change the visible state before the flow reaches the expected command.

When input fails, confirm the focused field accepts text and that the keyboard is not covering the next control. When assertions fail intermittently, look for missing completion signals in the app rather than adding arbitrary waits.

Verify the Result

A good Maestro setup has readable flows, stable selectors, externalized secrets, and a CI command that can reproduce local runs. The suite should produce enough output to identify the failed command and the visible app state.

Next Steps

Use Upload App and Manual App Testing when you need to inspect the same app in webmate. Use Appium when the requirement is WebDriver-based mobile automation through webmate.