Variables

Input Variables in Testform allow you to parameterize test suites and modules without hardcoding URLs, credentials, or environment details inside test specification files.

Just like the variable block in Terraform, variables in Testform are declared cleanly in YAML using the official variable: key and referenced inside Gherkin steps via ${var.<name>}.

---

1. Variable Declaration (variables.yml)

Variables are declared in variables.yml (or main.yml). You can define data types, descriptions, default values, allowed value sets (enum), and validation rules evaluated by the AST engine:

variables.yml

variable:
  environment:
    type: string
    default: "staging"
    description: "Target environment for test execution"
    enum:
      - "dev"
      - "staging"
      - "prod"
    validation:
      condition: "${contains(['dev', 'staging', 'prod'], var.environment)}"
      error_message: "The environment variable must be 'dev', 'staging', or 'prod'."

  base_url:
    type: string
    default: "https://staging.app.com"
    description: "Base URL of the application under test"

  timeout_ms:
    type: number
    default: 5000
    description: "Execution timeout in milliseconds"
    validation:
      condition: "${var.timeout_ms > 0 && var.timeout_ms <= 60000}"
      error_message: "Timeout must be greater than 0 and not exceed 60000 ms."

---

2. Type System and Current Limitations

Like Terraform, Testform classifies data types into primitive and complex types. Below is the active capability matrix:

Type	Category	Testform Support	Active Validation
string	Primitive	100% Supported	Direct string interpolation and injection.
number	Primitive	100% Supported	Strict numeric check; fails if non-numeric.
boolean	Primitive	100% Supported	Strict check to true or false.
enum	Restriction	100% Supported	Fails with structured diagnostic if value is not allowed.
validation	AST Logic	100% Supported	Evaluated via sandboxed AST expression engine with custom message.
list(...)	Collection	Partial / Limitation	Stored flattened as string ("a,b"). Does not validate element types.
map(...)	Collection	Partial / Limitation	Does not validate homogeneous value types.
object	Structural	Partial / Limitation	Does not validate nested property schemas or required fields.

Practical Examples of Primitive Types

variable:
  # 1. Simple String
  app_url:
    type: string
    default: "https://demo.playwright.dev/todomvc"

  # 2. Number with range validation
  retries:
    type: number
    default: 3
    validation:
      condition: "${var.retries >= 1 && var.retries <= 10}"
      error_message: "Retries must be between 1 and 10."

  # 3. Strict Boolean
  headless_mode:
    type: boolean
    default: true

  # 4. Enum with allowed value catalog
  target_env:
    type: string
    default: "staging"
    enum: ["dev", "staging", "prod"]

Current Limitations in Complex Types & Recommended Usage

Caution

Current Technical Limitations:

1. No direct bracket or dot indexing: Syntax like ${var.browsers[0]} or ${var.database.host} is not yet supported directly in the parser syntax tree.
2. Access via HCL Functions: To work with lists or maps in the current version, use the built-in AST functions:
   • contains(list, val): Checks if an item exists in a list or string.
   • element(list, index): Gets the element by zero-based index.
   • length(list): Returns collection length.
   • lookup(map, key, default): Safely looks up a key in a map.

# Recommended approach in the current version for collections:
variable:
  allowed_browsers:
    default: ["chromium", "firefox", "webkit"]

locals:
  # Access first element using element()
  default_browser: "${element(var.allowed_browsers, 0)}"

  # Count elements with length()
  total_browsers: "${length(var.allowed_browsers)}"

---

3. Assigning Values: *.vars.yml Files

Concrete variable values are placed in files with the *.vars.yml (or *.vars.yaml) extension:

Automatic Auto-Loading

Any file matching the *.vars.yml pattern inside the workspace root (e.g., testform.vars.yml, default.vars.yml) is automatically loaded in alphabetical order when running testform plan and testform apply:

# testform.vars.yml (Auto-loaded by default)
environment: "staging"
base_url: "https://staging-api.company.com"
timeout_ms: 10000

Environment-Specific Injection (-var-file)

For specific environments like production or CI/CD pipelines, create dedicated files and inject them explicitly:

prod.vars.yml

environment: "prod"
base_url: "https://api.company.com"
timeout_ms: 30000

testform plan -var-file=prod.vars.yml
testform apply -var-file=prod.vars.yml

---

4. Usage in Gherkin Scenarios

Variables can be interpolated inside any Gherkin step using ${var.<name>}:

Scenario: Dynamic authentication
  Given browser navigates to "${var.base_url}/login"
  When user inputs credentials for "qa-tester"
  Then session starts in under ${var.timeout_ms} milliseconds

---

5. Precedence Hierarchy

Testform resolves variable values according to strict precedence:

▲ HIGHEST PRECEDENCE
│  [Level 5] CLI Flags:            -var "key=value"
│  [Level 4] CLI Var Files:        -var-file="staging.yml"
│  [Level 2] Domain Folders:       auth/auth.yml, inventory/inventory.yml, etc.
│  [Level 1] Terraform Standard:   variables.yml, locals.yml
│  [Level 0] Base Manifest:        main.yml (global defaults)
▼ LOWEST PRECEDENCE