runFlow

Execute a subflow file with optional environment variables.

The runFlow command executes a sequence of commands from another Flow file or from an inline definition. This command helps you modularize tests and reuse common sequences, such as a login process. Inline subflows (using the commands parameter) are especially useful for conditional logic or for grouping a few steps under a clear label.

Parameters

The runFlow command accepts the following parameters.

Parameter	Type	Description
file	string	The relative path to the Flow file to execute.
label	string	A short description of what the subflow does. Shown in reports and helps with readability and maintenance.
env	map	A map of key-value pairs to pass as environment variables to the subflow.
commands	list	A list of commands to execute inline. Use this instead of the file parameter for self-contained Flows.

Usage examples

The following examples demonstrate how to use the runFlow command.

Run a separate Flow file

To reuse a common sequence of steps, define them in a separate file and call them with runFlow. For example, you can define a login sequence once and reuse it in multiple tests. The following Login Flow is defined in one file and reused in the other two Flows (Profile and Settings).

Login.yaml

appId: com.example.app
---
- launchApp
- tapOn: Username
- inputText: Test User
- tapOn: Password
- inputText: Test Password
- tapOn: Login

Profile.yaml

Settings.yaml

Flow files are a great way to abstract steps or create a reusable component. Be mindful during test Flow files help you reuse and abstract steps. Keep tests easy to follow so they stay maintainable.

Pass environment variables to a subflow

You can pass variables to the subflow using the env parameter. These variables are accessible within the subflow.

- runFlow: 
    file: anotherFlow.yaml
    env:
      MY_PARAMETER: "123"

When to use inline subflows

Inline subflows fit conditional logic or small groups of steps that don't need a separate file. Use a label so the step has a clear intent; otherwise, listing the commands directly is simpler.

Run an inline Flow

To define a subflow in place, use the commands parameter instead of file. A label gives the step a clear name so you can see at a glance what it does. For example:

- runFlow:
    label: Sort alphabetically
    commands:
      - tapOn:
          id: sort_icon
      - tapOn: algorithm
      - tapOn: A-Z
      - tapOn: Apply

You can also pass environment variables into an inline subflow:

- runFlow:
    env:
      INNER_ENV: Inner Parameter
    commands:
      - inputText: ${INNER_ENV}

Cloud execution

Pass a workspace folder (not a single Flow file) so Maestro can upload dependent flows and a root config.yaml if present. Passing only a file relies on best-effort dependency collection and can result in Failed to parse file. Use named parameters. For example, if your flows and app are under myTestsFolder:

maestro cloud --app-file myApp.apk --flows ./myTestsFolder

Related content

Learn how to define parameters and set environment variables in Maestro Flows by accessing the Parameters and constants and pages.