4.3 Variables Scoping & Built-in Dynamic Macros
How variable resolution flows across scopes (Step → Case → Suite → Global) and how to use dynamic test data macros.
Variable Scope Hierarchy
Section titled “Variable Scope Hierarchy”When {{ myVar }} is referenced, CertiQA resolves from highest to lowest precedence: Step Output Variables → Case/DDT Variables → Suite Variables → Project Global Variables → Encrypted Vault. That ordering is what lets a suite-level default (say, a shared BASE_URL) be overridden safely by a single case’s DDT row or a step’s own captured output, without editing the suite-level value everyone else still relies on – the narrower scope always wins over the broader one, never the other way around.
| Dynamic Macro | Generated Example | Use Case |
|---|---|---|
| {{ $randomEmail }} | [email protected] | Unique user registration without collisions. |
| {{ $timestamp }} | 1756492800000 | Unique order IDs and timestamps. |
| {{ $uuid }} | a3f9104c-8e2b-4019-b68a-241f92a93411 | Idempotency keys and tokens. |
| {{ $randomPhone }} | +15550198421 | Formatted valid phone numbers. |
Expression Macros: ${…} Syntax
Section titled “Expression Macros: ${…} Syntax”A second macro family uses ${PREFIX:arg} syntax inside a TEXT-sourced step value, and covers more ground than the {{ $shorthand }} macros above – environment variables, synthetic data by type, relative dates, ranged random numbers, and deterministic 2FA/email/SMS values. Both families resolve in the same value pipeline and can be mixed in one value string; unlike the {{ $shorthand }} macros, the ${…} family is not currently surfaced in the step value editor’s autocomplete, so these are typed by hand.
| Macro | Example | Resolves To |
|---|---|---|
| ${ENV:VAR_NAME} | ${ENV:STAGING_URL} | A process environment variable on the runner (masked in logs once resolved). |
| ${SECRET:KEY_NAME} | ${SECRET:ADMIN_PASSWORD} | A Vault-encrypted secret, fetched asynchronously (also available as {{secret:KEY_NAME}}). |
| ${FAKER:type} | ${FAKER:email} | Synthetic data by type – email, firstname, lastname, name, ssn, iban, phone, uuid, alphanumeric, and similar generators. |
| ${DATETIME:expr} | ${DATETIME:+7d} | A relative or absolute date/time expression. |
| ${RANDOM:number:min..max} | ${RANDOM:number:100..999} | A random integer in the given range. |
| ${TOTP:secret_or_key} | ${TOTP:JBSWY3DPEHPK3PXP} | A live 6-digit TOTP code generated from a base32 secret – see 2.8 Virtual Auth. |
| ${EMAIL:inbox_name} | ${EMAIL:signup_test} | A fresh ephemeral virtual inbox address – see 2.8 Virtual Auth. |
| ${SMS:phone_label} | ${SMS:signup_test} | A fresh ephemeral virtual phone number – see 2.8 Virtual Auth. |