---
title: Subflows, Conditions, Loops and JavaScript | TestingBot
description: A suite of twenty flows that each copy the same login steps is twenty
  places to fix when the login screen changes. This chapter covers the tools Maestro…
source_url:
  html: https://testingbot.com/resources/courses/maestro/flow-control-and-javascript
  md: https://testingbot.com/resources/courses/maestro/flow-control-and-javascript.md
---

Course

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

Chapter 4 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 4 of 10 Beginner 7 min read 3 quick checks Updated Nov 2026 

# Subflows, Conditions, Loops and JavaScript
On this page
1. [Subflows with runFlow](https://testingbot.com#subflows-with-runflow)
2. [Variables: env, -e and defaults](https://testingbot.com#variables-env-e-and-defaults)
3. [Conditions with when](https://testingbot.com#conditions-with-when)
4. [Loops and retries](https://testingbot.com#loops-and-retries)
5. [JavaScript](https://testingbot.com#javascript)
6. [Putting it together](https://testingbot.com#putting-it-together)
7. [Hooks for setup and teardown](https://testingbot.com#hooks-for-setup-and-teardown)

A suite of twenty flows that each copy the same login steps is twenty places to fix when the login screen changes. This chapter covers the tools Maestro gives you to avoid that: subflows, variables, conditions, loops, retries and JavaScript. Every snippet in the worked example below was run against the sample app on an iOS simulator.

## Subflows with runFlow[#](https://testingbot.com#subflows-with-runflow)

Move repeated steps into their own file and call it with `runFlow`. Paths are relative to the calling flow. Keep subflows in a subfolder: when you run `maestro test .`, Maestro only picks up flow files at the top level of the folder, so files in `subflows/` are not executed on their own.

```
flows/
  add_numbers.yaml
  table.yaml
  subflows/
    enter_numbers.yaml
  scripts/
    expected.js
```

`subflows/enter_numbers.yaml` types two values into the calculator. It reads them from variables, so the caller decides the data:

```yaml
appId: org.reactjs.native.example.SampleApp
---
- tapOn:
    id: inputA
    point: "90%,50%"
- eraseText
- inputText: ${A}
- tapOn:
    id: inputB
    point: "90%,50%"
- eraseText
- inputText: ${B}
```

## Variables: env, -e and defaults[#](https://testingbot.com#variables-env-e-and-defaults)

Variables use `${NAME}` syntax and are case-sensitive. There are three common sources:

- **The flow header.** An `env:` block above `---` defines constants for that flow and the subflows it calls.
- **The command line.** `maestro test -e A=7 -e B=8 table.yaml`. CLI values are always strings; parse them in JavaScript if you need numbers.
- **The runFlow call.** Pass values to one subflow invocation:

```yaml
- runFlow:
    file: subflows/login.yaml
    env:
      USERNAME: "admin@example.com"
```

Constants defined in a subflow, in its header or in the `runFlow` call, override parameters with the same name from the parent. To make a subflow usable on its own, give it a default with a JavaScript expression: `${USERNAME || "guest"}`.

The Maestro CLI also exposes shell environment variables that start with `MAESTRO_` (for example `MAESTRO_API_KEY`) to your flows, which is convenient in CI. Built-in variables include `MAESTRO_FILENAME` and, when sharding, `MAESTRO_SHARD_INDEX`.

In CI you export `API_KEY=...` in the shell, but `${API_KEY}` is empty inside the flow. Why?

 Maestro only exposes shell variables whose names start with `MAESTRO_`; rename it or pass it with `-e` Variables are lowercase in flows Shell variables are only visible in subflows

The CLI passes through `MAESTRO_`-prefixed environment variables only. Anything else has to be passed explicitly with `-e KEY=VALUE`.

## Conditions with when[#](https://testingbot.com#conditions-with-when)

`runFlow` accepts a `when` block. If the condition is true, the file or inline `commands` run; otherwise they are skipped and the flow continues. The conditions are:

| Condition | Runs when |
| --- | --- |
| `visible:` | an element matching the selector is on screen |
| `notVisible:` | no matching element is on screen |
| `platform:` | the platform is `Android`, `iOS` or `Web` |
| `true:` | a JavaScript expression is true |

Several conditions in one `when` must all hold. The classic use is a dialog that sometimes appears:

```yaml
- runFlow:
    when:
      visible: "Rate this app"
    commands:
      - tapOn: "Not now"
```

For a single optional step there is a shorter form: add `optional: true` to the command, ideally with a `label` explaining why. Use conditions sparingly. A flow full of branches is hard to read, and a `visible:` check on an element that appears late can make the branch itself flaky. If two scenarios differ a lot, write two flows.

## Loops and retries[#](https://testingbot.com#loops-and-retries)

`repeat` runs commands a fixed number of `times`, `while` a condition holds, or both (whichever limit is hit first):

```yaml
- repeat:
    times: 10
    while:
      notVisible: "End of list"
    commands:
      - scroll
```

`retry` re-runs a block if it fails, up to `maxRetries` (0 to 3, default 1):

```yaml
- retry:
    maxRetries: 2
    commands:
      - tapOn: "Refresh"
      - assertVisible: "Updated just now"
```

Treat `retry` as a scalpel. Wrapping a whole flow in it hides real defects, such as a button that only works half the time.

A `repeat` block has `times: 10` and `while: { notVisible: "End of list" }`. When does it stop?

 After exactly 10 iterations Only when End of list becomes visible When either limit is reached: End of list appears or 10 iterations have run It fails, because the two options cannot be combined

With both set, whichever limit is hit first ends the loop, so `times` works as a safety cap on the condition.

## JavaScript[#](https://testingbot.com#javascript)

Maestro embeds a JavaScript engine for logic YAML cannot express. There are three ways in:

- **Inline expressions** , anywhere a value is accepted: `- inputText: ${'user_' + Date.now()}`.
- **`evalScript`** for a one-line statement with no UI action: `- evalScript: ${output.counter = 0}`.
- **`runScript`** for a `.js` file. Pass it values with `env:` just like a subflow.

Scripts share data through the global `output` object; anything you assign to it is readable later in the flow as `${output.name}`. `console.log` writes to `maestro.log` (only the first argument is printed, so concatenate). The built-in `http` client (`http.get`, `http.post`, ...) and `json()` parser let a script create test data through your API instead of through the UI, and `faker` generates random names, emails and numbers.

`scripts/expected.js` computes the sum the app should show:

```javascript
output.expected = String(parseInt(A) + parseInt(B))
```

## Putting it together[#](https://testingbot.com#putting-it-together)

`table.yaml` uses all of the above against the sample app:

```yaml
appId: org.reactjs.native.example.SampleApp
tags:
  - regression
env:
  A: ${A || "7"}
  B: ${B || "8"}
---
- launchApp
- runFlow:
    file: subflows/enter_numbers.yaml
- runScript: scripts/expected.js
- assertVisible: ${output.expected}
- runFlow:
    when:
      platform: Android
    commands:
      - hideKeyboard
- retry:
    maxRetries: 2
    commands:
      - assertVisible:
          id: sum
- copyTextFrom:
    id: sum
- assertTrue: ${maestro.copiedText == output.expected}
```

What happens when it runs:

1. The `env` block sets `A` and `B` to 7 and 8 unless they were passed in, and the subflow sees them and types them.
2. The script computes `"15"` into `output.expected`, and the assertion waits for that text.
3. On iOS the Android-only block is reported as `SKIPPED`. (Why Android-only? See chapter 5: `hideKeyboard` could not dismiss the iOS number pad.)
4. `copyTextFrom` reads the Total field into `maestro.copiedText`, and `assertTrue` compares it with the computed value.

Run it with different data without touching the file:

```bash
maestro test -e A=20 -e B=22 table.yaml # types 20 and 22, expects 42
```

The `${A || "7"}` form is deliberate. In our test run, a plain constant in the header (`A: "7"`) won over `-e A=20`: the flow still typed 7. If a value should be overridable from the command line, give it a default with `||` instead of a fixed constant.

## Hooks for setup and teardown[#](https://testingbot.com#hooks-for-setup-and-teardown)

Instead of starting every flow with the same `runFlow`, declare it once per flow as a hook in the header:

```yaml
appId: com.example.app
onFlowStart:
  - runFlow: subflows/login.yaml
onFlowComplete:
  - runFlow: subflows/logout.yaml
---
- tapOn: "Profile"
```

`onFlowComplete` runs whether the flow passed or failed, which makes it the right place for cleanup such as deleting test data through your API. Keep hooks fast; they run for every flow.

When you later run these flows on [TestingBot's Maestro grid](https://testingbot.com/support/app-automate/maestro), variables are passed with the same `-e KEY=VALUE` form, and secrets get a dedicated flag. The [Maestro options reference](https://testingbot.com/support/app-automate/maestro/options) lists both. Next: the differences between iOS and Android that your flows need to handle.

Your flow creates a user through the API and must delete it again, even when an assertion fails halfway. Where does the delete go?

 As the last command of the flow In an `onFlowComplete` hook In a `retry` block In an `onFlowStart` hook of the next flow

`onFlowComplete` runs whether the flow passed or failed. The last command never runs after a failure, and relying on the next flow creates an order dependency.

[Previous · Chapter 3 Maestro Selectors and Core Commands](https://testingbot.com/resources/courses/maestro/selectors-and-commands) [Next · Chapter 5 iOS vs Android: Permissions, State, Links](https://testingbot.com/resources/courses/maestro/ios-and-android-specifics)

On this page

1. [Subflows with runFlow](https://testingbot.com#subflows-with-runflow)
2. [Variables: env, -e and defaults](https://testingbot.com#variables-env-e-and-defaults)
3. [Conditions with when](https://testingbot.com#conditions-with-when)
4. [Loops and retries](https://testingbot.com#loops-and-retries)
5. [JavaScript](https://testingbot.com#javascript)
6. [Putting it together](https://testingbot.com#putting-it-together)
7. [Hooks for setup and teardown](https://testingbot.com#hooks-for-setup-and-teardown)

Certification

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

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