Skip to main content
BugRadar has two types of variables that work together to make your flows flexible and data-driven:
  1. Environment Variables — Static configuration (credentials, URLs, feature flags) set before runs
  2. Runtime Variables — Dynamic values that accumulate during execution from hooks, flow/suite overrides, and the agent itself

Environment Variables

Environment variables are key-value pairs managed in Settings > Environments. They store static configuration like API keys, test credentials, and URLs.
  • Reference them in flow instructions and cURL hooks using ${env:VARIABLE_NAME}
  • Scripts access them via standard language methods (os.environ.get(), process.env, $VAR)
  • Can be stored as secrets (encrypted, never displayed in plain text)
  • The agent never sees the raw variable — only the resolved value substituted into instructions
See Environments for full details on creating and managing environment variables.

Runtime Variables

Runtime variables are dynamic values that build up during a run. They come from these sources, and all feed into the same pool:

Build Variables

Attached to a specific app build, either from your CI pipeline or the dashboard. These override environment variables for all flows that run against that build. When to use: You need to pass context from your CI pipeline into flow instructions — PR numbers, branch names, feature flags, deployment URLs, or any other build-specific data. How to set them from CI (GitHub Action):
How to set them from the API: Include a variables field in the request body of /api/ci/confirm-upload, /api/ci/upload-web-build, or /api/v1/flows/run. The value can be a string ("KEY1=VALUE1,KEY2=VALUE2") or a JSON object ({"KEY1": "VALUE1"}). How to set them from the dashboard:
  1. Go to Apps
  2. Open an app’s builds list with its N builds button
  3. Open a build’s ⋯ menu and choose Build variables
  4. Add key-value pairs and click Save variables
You can also set variables when uploading a new build via the Advanced section in the upload dialog. How to use them in instructions:
The agent sees the resolved value (e.g., pr-42) and types it into the UI.

Suite Variables

For code-managed suites, define variables in _suite.yaml. See Variables in YAML. Suite variables override environment variables for all flows in the suite. When to use: You want a different TEST_EMAIL or API_URL for a specific suite without changing the environment. For dashboard-managed suites:
  1. Edit your suite
  2. Expand the Advanced dropdown
  3. Add key-value pairs

Flow Variables

For code-managed flows, define variables in *.flow.yaml. See Variables in YAML. Flow variables override both suite variables and environment variables for that specific flow. When to use: One flow in a suite needs a different value than the rest — for example, a flow that tests a different API endpoint. For dashboard-managed flows:
  1. Edit your flow
  2. Expand the Advanced dropdown
  3. Add key-value pairs

Hook Exports

Hooks can export values by writing KEY=VALUE pairs to /tmp/BugRadar.env. These values become available to all subsequent hooks and flows in the suite.
See Sharing Data Between Hooks for full details and examples in all supported languages.

Run Metadata

Set by BugRadar for every run: BugRadar_FLOW_RUN_ID, BugRadar_FLOW_ID, BugRadar_RUN_GROUP_ID, BugRadar_RUN_URL, BugRadar_RUN_GROUP_URL, BugRadar_BATCH_ID, and BugRadar_BATCH_URL. They can’t be overwritten. When to use: Linking your own logs or error reports to an BugRadar run from a hook. Don’t use them in flow instructions, except BugRadar_FLOW_ID. The others change every run, so the flow can’t be cached. See Run Metadata.

Agent Variables

The agent can dynamically save and retrieve values during flow execution. This is useful when the data you need doesn’t exist until the agent interacts with the app. Set Variable — Tell the agent to save a value it sees on screen:
Get Variable — Tell the agent to retrieve a previously saved value:
The agent automatically knows which variables are currently set, so you can reference them by name in your instructions without having to list what exists. Use cases:
  • Saving a generated order ID, username, or confirmation number from the screen
  • Capturing dynamic data in one step and verifying it in a later step
  • Storing values that subsequent hooks or flows need
Very large values are stored and available to hooks and subsequent flows (via ${env:KEY}), but are not displayed to the agent when using Get Variable. Keep stored values concise — save specific data points (IDs, names, tokens) rather than large payloads.

Using Variables in Instructions

Use the ${env:VARIABLE_NAME} syntax to reference variables in flow instructions:
This syntax resolves all variable types — environment variables, suite variables, flow variables, run metadata, and any runtime values (hook exports, agent-set values) that were set before the current flow started.
${env:KEY} is resolved once, before the agent starts running. This means it cannot reference values that the agent sets or that hooks export during the current flow. For a value the agent saves or a hook exports in this flow, use ${var:KEY} (below) or Get Variable.For subsequent flows in a suite, ${env:KEY} works — runtime variables from earlier flows are available to later flows.

Using Saved Values

To use a value the agent saved with Set Variable, write ${var:KEY}. BugRadar fills in the saved value at the moment the step runs, so it works for a value saved earlier in the same flow, or in an earlier flow in the suite:
  • ${var:KEY} reads the value saved with Set Variable, or the code the agent last read from a leased inbox or phone number (BugRadar_OTP_CODE, see OTP Testing). If nothing saved KEY, it reads a hook export, or a secret that the instructions also use as ${env:KEY}.
  • For any other variable, write ${env:KEY}. For a suite, flow or build variable or run metadata, ${var:KEY} refuses the step and tells the agent to use Get Variable. For anything else, including an environment variable, the text ${var:KEY} is typed as written.
  • ${var:KEY} is filled in only where the agent types text, opens a URL or deep link, or sets the clipboard. To check a saved value on screen, such as Verify the receipt shows ${var:order_id}, use Get Variable instead.
  • Steps that use ${var:KEY} can still be cached. On a later run, the cached step usually uses that run’s newly saved value. Flows That Save Variables lists when it runs live instead.
You don’t need to write ${var:KEY} yourself. When the agent types or opens a value it saved, it is told to use ${var:KEY}.

Variable Precedence

When multiple sources define the same variable name, later sources override earlier ones: For example, if your environment defines TEST_EMAIL=default@example.com and your suite defines TEST_EMAIL=suite@example.com, the suite value wins for all flows in that suite.
If both a hook and the agent set the same variable name, whichever runs last wins — there’s no fixed priority between them.

Cross-Flow Propagation in Suites

When flows run together in a suite, runtime variables from one flow automatically carry forward to the next. This lets you chain data across flows: Flow 1 — Agent captures data:
Flow 2 — Uses the data from Flow 1 (via ${env:KEY}):
Hook on Flow 2 — Also has access:
All runtime variable types carry forward — suite variables, flow variables, hook exports, and values set by the agent.

Examples

Example 1: Dynamic Data Capture Within a Single Flow

Capture a value from the app and verify it later in the same flow:

Example 2: Passing Data Between Flows in a Suite

Flow 1 — Create an order:
Flow 2 — Verify the order (uses ${env:KEY}):

Example 3: Agent Sets a Variable, Hook Uses It

Flow instructions:
Teardown hook (Python) — reads the saved variable:

Next Steps