テンプレート変数リファレンス

テンプレート変数を使用すると、QA プランをパラメータ化し、同じプランを変更なしで異なる環境や設定に対して実行できます。AI エージェントが MCP ツールを通じて QA プランのステップを構築する際にテンプレート変数を使用し、aqua CLI が実行時にそれらを解決します。

構文

変数は二重中括弧構文を使用し、ステップの実行前に解決された値に置換されます：

{{variable_name}}

変数は、URL、ヘッダー、リクエストボディ、CSS セレクタ、アサーション値など、すべてのステップ設定フィールドで展開されます。

TOTP 変数

時間ベースのワンタイムパスワード（TOTP）認証には、totp: プレフィックスを使用します：

{{totp:mfa_secret}}

変数の値は、Base32 エンコードされた TOTP シークレット（例: JBSWY3DPEBLW64TMMQQQ）または otpauth:// URI のいずれかである必要があります。Raw の Base32 シークレットの場合、SHA1 アルゴリズム、6 桁、30 秒周期がデフォルトで使用されます。otpauth:// URI の場合、パラメーターは URI から抽出されます。実行時に aqua が現在の OTP コードを計算し、テンプレートに代入します。

解決の優先順位

変数はレイヤードマージ戦略を使用して解決されます。同じ変数名が複数のソースに存在する場合、優先度の高いソースが優先されます：

プランのデフォルト（最低優先度）— QA プランバージョンの variables フィールドで定義された変数です。
環境ファイル — .aqua/environments/<name>.json ファイルからの変数と解決されたシークレットです。
実行時オーバーライド（最高優先度）— CLI の --var key=value または MCP ツールコールのオーバーライドとして渡された変数です。

変数の抽出

ステップは結果から値を抽出し、後続のステップの変数として利用できるようにすることができます。ステップの extract フィールドで抽出を定義します：

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

各キーは変数名となり、各値はステップのレスポンスに対して評価される JSONPath 式です。抽出された変数はグローバルであり、すべてのシナリオにわたる後続のすべてのステップで利用可能です。

変数のスコープ

プランのデフォルトで定義された変数は、すべてのステップで利用可能です。
環境ファイルからの変数は、すべてのステップで利用可能です。
抽出された変数は、抽出ステップの完了後に利用可能になり、実行の残りの期間を通じて保持されます。
実行時オーバーライドは、すべてのステップに適用されます。

環境ファイルでの環境変数の埋め込み

テンプレート変数の展開とは別に、環境ファイルの値では {$ENV_VAR} 構文を使用して、ファイル読み込み時に OS 環境変数を埋め込むことができます：

構文	動作
`{$VAR}`	環境変数 `VAR` の値に置換されます。未定義の場合はエラー。
`{$VAR:-default}`	環境変数 `VAR` の値に置換されます。未定義の場合は `default` が使用されます。

これはテンプレート変数の解決より前に行われます。たとえば、環境ファイルに "api_base_url": "http://{$SUBDOMAIN:-staging}.example.com" がある場合、ファイル読み込み時に {$SUBDOMAIN} が解決され、その結果の値がプランテンプレートで {{api_base_url}} として利用可能になります。

詳細は環境設定ガイドを参照してください。

シークレットの解決

プラン内のテンプレート変数で実際に参照されているシークレットのみが、実行時に解決されます。collectVariableReferences 関数がプランをスキャンし、どの {{variable_name}} テンプレートが出現するかを特定し、対応するシークレットのみが取得されます。これにより、不要なシークレットアクセスが最小化され、未使用の認証情報が露出するリスクが軽減されます。

使用例

URL での変数使用

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

シークレットを使用したヘッダー

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

ブラウザステップでの TOTP

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