Organising a Maestro Suite
On this page
Five flows in one folder need no structure. Fifty flows across two platforms, three environments and a CI pipeline do. This chapter turns the course's flows into a workspace: a folder layout, a config.yaml, tags for selecting what runs, and test data that does not collide.
A workspace layout#
A common convention is a .maestro/ folder at the root of the app repository:
.maestro/
config.yaml
auth/
login.yaml
signup.yaml
calculator/
add_numbers.yaml
table.yaml
subflows/
enter_numbers.yaml
login_as.yaml
scripts/
expected.js
create_user.js
Group runnable flows by feature or by user journey, keep reusable pieces in subflows/, and JavaScript in scripts/. The folder name .maestro is not required, but it is what many tools default to (the TestingBot GitHub Action's workspace input defaults to .maestro, for example), so using it saves configuration later.
config.yaml and flow discovery#
When you run maestro test .maestro/, Maestro looks for config.yaml at the root of that folder. Without one, it runs only the flow files at the top level, which with the layout above would be nothing. The flows key tells it where to look, using globs: * is the contents of a folder, ** includes all subfolders, and a leading ! excludes.
# .maestro/config.yaml
flows:
- "auth/*"
- "calculator/*"
- "!calculator/wip_*.yaml"
excludeTags:
- flaky
Note that subflows/ and scripts/ are simply not listed, so they never run as standalone tests; they are only executed when a flow calls them. A flows list must contain at least one positive pattern.
You can keep several configs, for example a fast one for pull requests and a full one for nightly runs, and choose with --config:
maestro test --config .maestro/nightly-config.yaml .maestro/
config.yaml lists flows: ["auth/*", "calculator/*"]. Does subflows/login_as.yaml run as a test of its own?
Only the folders matched by the flows globs are collected. Subflows and scripts stay out of the list and run when something calls them.
Tags#
Tags describe what a flow is, independent of where it lives. Add them in the flow header:
appId: org.reactjs.native.example.SampleApp
name: Add two numbers
tags:
- smoke
- calculator
---
- launchApp
Then select at run time:
maestro test .maestro/ --include-tags=smoke
maestro test .maestro/ --exclude-tags=wip,flaky
maestro test .maestro/ --include-tags=smoke --exclude-tags=flaky
The rules are worth memorising because they decide what actually runs:
- Several tags in one flag are OR:
--include-tags=auth,checkoutruns flows tagged with either. - There is no AND within a flag. You cannot ask for "tagged smoke and auth" directly.
- Include and exclude together are applied in order: first collect flows with an included tag, then drop any with an excluded tag. A flow tagged
smokeandflakyis excluded by--include-tags=smoke --exclude-tags=flaky. - With an include filter, untagged flows do not run. With only an exclude filter, untagged flows are kept.
- CLI flags take precedence over
includeTags/excludeTagsinconfig.yaml.
A small, stable tag vocabulary works better than many ad-hoc tags. A typical set: smoke (minutes, every pull request), regression (everything stable, nightly), a tag per feature area, and a flaky or quarantine tag that CI always excludes.
Naming flows for reports#
The flow's name is what appears in reports, and properties add metadata to the JUnit output, such as a link to a test case management ID:
appId: com.example.app
name: Login with valid credentials
properties:
testCaseId: "TC-101"
---
- launchApp
Readable names pay off the first time someone who did not write the flow reads a failed CI run.
Order, and why to avoid depending on it#
Maestro runs the flows in a folder in no guaranteed order, deliberately: flows that only pass in a certain sequence are fragile. If you truly need an order, config.yaml supports it:
executionOrder:
continueOnFailure: false
flowsOrder:
- signup_flow
- verify_email_flow
The better default is that each flow can run on a freshly reset device. Put the prerequisite steps in a subflow or an onFlowStart hook instead of relying on the previous flow. This becomes non-negotiable once flows run in parallel on several devices, where "the previous flow" may be running on a different phone.
verify_email_flow only passes if signup_flow ran before it. What is the better default than executionOrder?
A flow that can run on a freshly reset device survives parallel runs, where the previous flow may be on a different phone.
Test data#
Hard-coded test data is the most common reason a suite that passes alone fails in parallel. Some patterns that scale:
-
Generate unique values.
${faker.internet().emailAddress()}or${'user_' + Date.now()}for sign-up flows. -
Create data through the API, not the UI. A
runScriptin anonFlowStarthook can call your backend withhttp.postto create a user and put its credentials inoutput, and anonFlowCompletehook can delete it again. -
Keep secrets out of the repository. Pass them as parameters (
-e PASSWORD=...locally, CI secrets in a pipeline), never as constants in a flow file. - One account per flow when flows may run at the same time.
appId: com.example.app
onFlowStart:
- runScript:
file: ../scripts/create_user.js
env:
API_URL: ${API_URL}
---
- launchApp
- runFlow:
file: ../subflows/login_as.yaml
env:
EMAIL: ${output.email}
PASSWORD: ${output.password}
Your sign-up flow types qa@example.com. It passes on the first run and fails on every later one with email already registered. What fixes it?
The account lives on the server, so resetting the app does not help. Unique or API-managed data does.
How this carries over to the cloud#
The workspace you just built is also the unit you upload to a cloud runner. TestingBot reads a config.yaml at the top level of the uploaded flows, supports flows, includeTags, excludeTags, env and platform there, and has matching --include-tags and --exclude-tags CLI flags with the same untagged-flow rules. The Maestro options page lists the supported keys, including includedPaths for screenshot baselines. If you are moving an existing suite from Maestro Cloud, the migration guide confirms tags and flow files carry over unchanged. The next chapter runs the suite there.