Parameters and constants

Pass dynamic values to flows using CLI parameters and inline constants.

Maestro allows you to inject data into your Flows to make them dynamic and reusable. Instead of hardcoding values like usernames, passwords, or product IDs, you can use variables that are populated at runtime.

There are two main ways to define these variables:

• Parameters: Values passed externally (e.g., from the CLI or CI/CD pipeline).
• Constants: Values defined internally within the Flow (e.g., using the env key).

Both are accessed using the same ${VARIABLE_NAME} syntax.

Case sensitivity

Variable names are case-sensitive. ${APP_ID} is different from ${App_ID}.

Parameters

Parameters are useful for passing sensitive data (like credentials) or environment-specific configurations (like URLs) that you don't want to commit to your repository.

Passing parameters via CLI

You can pass parameters to Maestro using the -e flag when running the test or cloud commands.

maestro test -e USERNAME=[e-mail] -e PASSWORD=secret flow.yaml

Type safety

Remember that CLI parameters are passed as strings. If you need a number or boolean, you may need to parse it in JavaScript (e.g., parseInt(${COUNT})).

In your Flow, you can access these values using the ${VARIABLE_NAME} syntax. The following Flow uses the provided username and password to log in.

appId: com.example.app
---
- launchApp
- tapOn: "Username"
- inputText: ${USERNAME}
- tapOn: "Password"
- inputText: ${PASSWORD}

Accessing shell variables

Maestro automatically reads shell environment variables prefixed with MAESTRO_ and makes them available in your flows. This is convenient for CI/CD environments where secrets are often exposed as environment variables.

This feature works only with the Maestro CLI, not Maestro Studio.

export MAESTRO_API_KEY="12345"
maestro test flow.yaml

In this example, the API key exported in the shell is captured by an inline evaluation within the Flow.

- evalScript: ${output.apiKey = MAESTRO_API_KEY}

Constants

Constants are variables defined directly within your Flow files. They are useful for defining test data, configuration flags, or reusable values that don't need to change between runs.

Defining inline constants

You can define constants at the top of your Flow file using the env key.

In this example, DEFAULT_TIMEOUT and IS_DEBUG are set as constants for the entire Flow file.

appId: com.example.app
env:
    DEFAULT_TIMEOUT: 5000
    IS_DEBUG: true
---
- launchApp

Passing arguments to subflows

When using nested Flows, you can pass arguments to reuse the same subflow with different data. Variables defined in env are available only to that specific subflow execution.

In the following example, the login.yaml subflow is executed with the USER_ROLE constant set to admin.

- runFlow:
    file: subflows/login.yaml
    env:
        USER_ROLE: "admin"

Priority

Constants defined in a subflow (either in the env header or the runFlow command) override parameters with the same name from the parent flow.

Setting default values

You can use JavaScript syntax to provide default values for parameters. This is used for preventing crashes if a parameter is not provided.

In this example, ${USERNAME} will use the provided value if it exists, otherwise, it defaults to "guest".

- inputText: ${USERNAME || "guest"}

This technique is particularly powerful in subflows, allowing them to be run standalone (using defaults) or as part of a larger suite (using passed parameters).

# subflows/login.yaml
appId: com.example.app
env:
    # Use the passed value, or default to a test account
    USER_ID: ${USER_ID || "test_user_1"}
---
- tapOn: "User ID"
- inputText: ${USER_ID}

Built-in parameters

Maestro provides a set of built-in parameters that are available in all flows.

Parameter	Description
MAESTRO_FILENAME	The filename of the current flow (e.g., login.yaml).
MAESTRO_DEVICE_UDID	The identifier for the device under test
MAESTRO_SHARD_ID	Identifies the shard this test is running on. Starts counting at 1, and defaults to 1 when not using sharding.
MAESTRO_SHARD_INDEX	Identifies the shard this test is running on. Starts counting at 0, and defaults to 0 when not using sharding.

Next steps

To continue learning how to create Flows, check the following pages:

• Nested flows: Learn more about using runFlow to pass environment variables.
• Maestro CLI overview : Explore more options for the -e flag.
• JavaScript overview: Learn how to manipulate parameters using JavaScript logic.