---
title: Organising a Maestro Suite | Maestro Mobile Testing
description: 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&#39;s…
source_url:
  html: https://testingbot.com/resources/courses/maestro/organising-a-suite
  md: https://testingbot.com/resources/courses/maestro/organising-a-suite.md
---

Course

[Maestro Mobile Testing](https://testingbot.com/resources/courses/maestro)

Chapter 7 of 10

1. [1 Maestro Tutorial: Mobile UI Tests in YAML](https://testingbot.com/resources/courses/maestro)
2. [2 Install Maestro and Run Your First Flow](https://testingbot.com/resources/courses/maestro/install-and-first-flow)
3. [3 Maestro Selectors and Core Commands](https://testingbot.com/resources/courses/maestro/selectors-and-commands)
4. [4 Subflows, Conditions, Loops and JavaScript](https://testingbot.com/resources/courses/maestro/flow-control-and-javascript)
5. [5 iOS vs Android: Permissions, State, Links](https://testingbot.com/resources/courses/maestro/ios-and-android-specifics)
6. [6 Debugging Flaky Maestro Flows](https://testingbot.com/resources/courses/maestro/debugging-and-flakiness)
7. [7 Organising a Maestro Suite](https://testingbot.com/resources/courses/maestro/organising-a-suite)
8. [8 Run Maestro Flows on TestingBot](https://testingbot.com/resources/courses/maestro/run-on-testingbot)
9. [9 Running Maestro in CI Pipelines](https://testingbot.com/resources/courses/maestro/ci-pipelines)
10. [10 Knowledge check](https://testingbot.com/resources/courses/maestro/knowledge-check)

[Exit course](https://testingbot.com/resources/courses)

 Chapter 7 of 10 Beginner 6 min read 3 quick checks Updated Nov 2026 

# Organising a Maestro Suite
On this page
1. [A workspace layout](https://testingbot.com#a-workspace-layout)
2. [config.yaml and flow discovery](https://testingbot.com#config-yaml-and-flow-discovery)
3. [Tags](https://testingbot.com#tags)
4. [Naming flows for reports](https://testingbot.com#naming-flows-for-reports)
5. [Order, and why to avoid depending on it](https://testingbot.com#order-and-why-to-avoid-depending-on-it)
6. [Test data](https://testingbot.com#test-data)
7. [How this carries over to the cloud](https://testingbot.com#how-this-carries-over-to-the-cloud)

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[#](https://testingbot.com#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[#](https://testingbot.com#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.

```yaml
# .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`:

```bash
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?

 Yes, every YAML file in the workspace runs Only if it has a `tags` block No, it only runs when a listed flow calls it

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[#](https://testingbot.com#tags)

Tags describe what a flow _is_, independent of where it lives. Add them in the flow header:

```yaml
appId: org.reactjs.native.example.SampleApp
name: Add two numbers
tags:
  - smoke
  - calculator
---
- launchApp
```

Then select at run time:

```bash
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,checkout` runs 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 `smoke` and `flaky` is 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` / `excludeTags` in `config.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[#](https://testingbot.com#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:

```yaml
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[#](https://testingbot.com#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:

```yaml
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`?

 Rename the files so they sort in the right order Put the sign-up steps in a subflow or `onFlowStart` hook so the verify flow sets up its own precondition Run the suite with `--shard-split 1` Merge all flows into one file

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[#](https://testingbot.com#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 `runScript` in an `onFlowStart` hook can call your backend with `http.post` to create a user and put its credentials in `output`, and an `onFlowComplete` hook 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.

```yaml
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?

 Generate a unique value, for example `${'user_' + Date.now()}` or faker, or create and delete the user through the API Add `clearState: true` Retry the flow once

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[#](https://testingbot.com#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](https://testingbot.com/support/app-automate/maestro/options#config) lists the supported keys, including `includedPaths` for screenshot baselines. If you are moving an existing suite from Maestro Cloud, the [migration guide](https://testingbot.com/support/app-automate/maestro/migrate-from-maestro-cloud) confirms tags and flow files carry over unchanged. The next chapter runs the suite there.

[Previous · Chapter 6 Debugging Flaky Maestro Flows](https://testingbot.com/resources/courses/maestro/debugging-and-flakiness) [Next · Chapter 8 Run Maestro Flows on TestingBot](https://testingbot.com/resources/courses/maestro/run-on-testingbot)

On this page

1. [A workspace layout](https://testingbot.com#a-workspace-layout)
2. [config.yaml and flow discovery](https://testingbot.com#config-yaml-and-flow-discovery)
3. [Tags](https://testingbot.com#tags)
4. [Naming flows for reports](https://testingbot.com#naming-flows-for-reports)
5. [Order, and why to avoid depending on it](https://testingbot.com#order-and-why-to-avoid-depending-on-it)
6. [Test data](https://testingbot.com#test-data)
7. [How this carries over to the cloud](https://testingbot.com#how-this-carries-over-to-the-cloud)

Certification

Earn the free, resume-worthy TestingBot Maestro Certification for this course.

[How it works](https://testingbot.com/resources/courses/maestro/certification)
