Template Variables Reference

Template variables allow QA plans to be parameterized so that the same plan can run against different environments and configurations without modification. The AI agent uses template variables when building QA plan steps via MCP tools, and the aqua CLI resolves them at execution time.

Syntax

Variables use double-brace syntax and are replaced with their resolved values before a step executes:

{{variable_name}}

Variables are expanded in all step configuration fields, including URLs, headers, request bodies, CSS selectors, and assertion values.

TOTP Variables

For time-based one-time password (TOTP) authentication, use the totp: prefix:

{{totp:mfa_secret}}

The variable value must be either a Base32-encoded TOTP secret (e.g., JBSWY3DPEBLW64TMMQQQ) or an otpauth:// URI. For raw Base32 secrets, aqua uses the defaults: SHA1 algorithm, 6 digits, 30-second period. For otpauth:// URIs, parameters are extracted from the URI. At execution time, aqua computes the current OTP code and substitutes it in place of the template.

Resolution Priority

Variables are resolved using a layered merge strategy. When the same variable name appears in multiple sources, the higher-priority source wins:

1. Plan defaults (lowest priority) — Variables defined in the QA plan version’s variables field.
2. Environment file — Variables and resolved secrets from the .aqua/environments/<name>.json file.
3. Execution overrides (highest priority) — Variables passed via --var key=value on the CLI or as overrides in MCP tool calls.

Extracting Variables

Steps can extract values from their results and make them available as variables for subsequent steps. Define extractions in the step’s extract field:

{
  "extract": {
    "user_id": "$.data.id",
    "auth_token": "$.headers.authorization"
  }
}

Each key becomes a variable name and each value is a JSONPath expression evaluated against the step’s response. Extracted variables are global — they are available to all subsequent steps across all scenarios.

Variable Scoping

• Variables defined in plan defaults are available to all steps.
• Variables from an environment file are available to all steps.
• Extracted variables become available after the extracting step completes and persist for the remainder of the execution.
• Execution overrides apply to all steps.

Secret Resolution

Only secrets that are actually referenced by template variables in the plan are resolved at execution time. The collectVariableReferences function scans the plan to identify which {{variable_name}} templates appear, and only the corresponding secrets are fetched. This minimizes unnecessary secret access and reduces the risk of exposing unused credentials.

Examples

URL with variables

{{base_url}}/api/v1/users/{{user_id}}

Header with secret

{
  "Authorization": "Bearer {{api_token}}"
}

TOTP in a browser step

{ "type": "type", "selector": "#mfa-code", "text": "{{totp:mfa_secret}}" }