Parameters and constants

Pass dynamic values to flows using parameters and inline constants.

Instead of writing values like usernames, passwords, or product IDs directly into a flow, you use variables and fill in the values at run time. One flow can then be reused with different data.

There are two main ways to define these variables:

• Parameters: values that come from outside the flow, for example from an Astra Scout environment.
• Constants: values defined inside the flow, with 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

Use parameters for sensitive data (like credentials) or environment-specific settings (like URLs) that you do not want to commit to your repository.

Passing parameters from an environment

In Astra Scout, choose Run → Manage Environments… and create an environment. An environment has a name, optional include and exclude tags, and a list of Environment variables. Select the environment before you run a flow and each variable is available as ${NAME}.

Type safety

Parameters are always strings. If you need a number or boolean, convert it in JavaScript (e.g., parseInt(${COUNT})).

For example, the environment has two variables, USERNAME and PASSWORD. The following flow uses them to log in.

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

Use macOS environment variables

Flows can also read the environment variables Astra Scout was started with. Start your own variable names with MAESTRO_ (for example MAESTRO_API_KEY) so they do not mix with system variables such as HOME.

WARNING

An app opened from the Dock or Finder does not get the variables you export in a terminal. Open Astra Scout from that same terminal, or use an Astra Scout environment instead.

For example, if Astra Scout was started with MAESTRO_API_KEY=12345, a flow reads the value like this:

- evalScript: ${output.apiKey = MAESTRO_API_KEY}

Constants

Constants are variables defined right in the flow file. Use them for test data, configuration flags, or reusable values that do not change between runs.

Defining inline constants

Define constants at the top of the flow file with the env key. In this example, DEFAULT_TIMEOUT and IS_DEBUG are available in the whole flow file.

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

Passing arguments to subflows

When you call a subflow with runFlow, you can pass arguments to use one subflow with different data. Variables defined in env apply only to that run of the subflow.

In the following example, the login.yaml subflow runs with USER_ROLE set to admin.

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

Priority

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

A constant in a flow's env header also overrides a variable with the same name from the selected environment. To make the header value only a default that the environment can replace, write NAME: ${NAME || "default"}, as in the next section.

Setting default values

Use JavaScript syntax to set default values for parameters, so a missing value does not cause an error. In this example, ${USERNAME} uses the provided value if there is one, otherwise "guest".

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

This fits subflows well: a subflow can run on its own (using the defaults) or inside a larger suite (using the values passed in).

# 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

Every flow has these built-in parameters.

Parameter	Description
MAESTRO_FILENAME	The current flow's file name without the file extension (e.g., login).
MAESTRO_SHARD_ID	Always 1 (Astra Scout does not split a run across devices).
MAESTRO_SHARD_INDEX	Always 0 (Astra Scout does not split a run across devices).

WARNING

The MAESTRO_DEVICE_UDID variable is not available in Astra Scout. Do not use it in flows.

Next steps

Continue with:

• Nested flows: use runFlow to pass variables to a subflow.
• JavaScript overview: work with parameters in JavaScript.