Variables

Las Variables de Entrada en Testform permiten parametrizar suites de prueba y módulos sin necesidad de hardcodear URLs, credenciales o datos de entorno dentro de los archivos de prueba.

Al igual que el bloque variable en Terraform, en Testform se declaran de manera limpia en YAML mediante la clave oficial variable: y se resuelven en expresiones Gherkin mediante ${var.<nombre>}.

---

1. Declaración de Variables (variables.yml)

Las variables se declaran en variables.yml (o en main.yml). Puedes definir tipos, descripciones, valores por defecto, listas de valores permitidos (enum) y reglas de validación evaluadas por el motor AST:

variables.yml

variable:
  environment:
    type: string
    default: "staging"
    description: "Entorno destino para la ejecución de pruebas"
    enum:
      - "dev"
      - "staging"
      - "prod"
    validation:
      condition: "${contains(['dev', 'staging', 'prod'], var.environment)}"
      error_message: "La variable environment debe ser 'dev', 'staging' o 'prod'."

  base_url:
    type: string
    default: "https://staging.app.com"
    description: "URL base de la aplicación bajo prueba"

  timeout_ms:
    type: number
    default: 5000
    description: "Tiempo límite de espera en milisegundos"
    validation:
      condition: "${var.timeout_ms > 0 && var.timeout_ms <= 60000}"
      error_message: "El timeout debe ser mayor a 0 y no superar los 60000 ms."

---

2. Sistema de Tipos y Limitaciones Actuales

Al igual que Terraform, Testform clasifica los tipos de datos en primitivos y complejos. Esta es la matriz técnica del estado de soporte actual:

Tipo	Categoría	Estado en Testform	Validación Activa
string	Primitivo	100% Soportado	Inyección e interpolación directa en texto.
number	Primitivo	100% Soportado	Verificación estricta con error si no es numérico.
boolean	Primitivo	100% Soportado	Restricción estricta a true o false.
enum	Restricción	100% Soportado	Bloqueo si el valor no está en la lista permitida.
validation	Lógica AST	100% Soportado	Evaluación de expresiones booleanas y mensaje de error.
list(...)	Colección	Parcial / Limitación	Se almacena aplanado a string ("a,b"). No valida tipo de hijos.
map(...)	Colección	Parcial / Limitación	No valida esquemas homogéneos de valores.
object	Estructural	Parcial / Limitación	No valida esquemas recursivos ni atributos requeridos.

Ejemplos Prácticos de Tipos Primitivos

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

  # 2. Number con validación de rango
  retries:
    type: number
    default: 3
    validation:
      condition: "${var.retries >= 1 && var.retries <= 10}"
      error_message: "Los reintentos deben estar entre 1 y 10."

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

  # 4. Enum con catálogo cerrado de valores
  target_env:
    type: string
    default: "staging"
    enum: ["dev", "staging", "prod"]

Limitaciones Actuales en Tipos Complejos y Cómo Operar Hoy

Precaución

Limitación Técnica Actual:

1. Sin indexación por corchetes: Sintaxis como ${var.browsers[0]} o ${var.database.host} no están soportadas directamente en el parser sintáctico.
2. Acceso mediante Funciones HCL: Para trabajar con colecciones o listas en la versión actual, utiliza las funciones del motor AST:
   • contains(list, val): Verifica si un elemento existe en una lista.
   • element(list, index): Obtiene el elemento por índice numérico.
   • length(list): Cuenta la cantidad de elementos.
   • lookup(map, key, default): Busca una clave en un mapa.

# Forma recomendada en la versión actual para colecciones:
variable:
  allowed_browsers:
    default: ["chromium", "firefox", "webkit"]

locals:
  # Acceder al primer elemento usando la función element()
  default_browser: "${element(var.allowed_browsers, 0)}"

  # Contar elementos con length()
  total_browsers: "${length(var.allowed_browsers)}"

---

3. Asignación de Valores: Archivos *.vars.yml

Los valores concretos para las variables se definen en archivos con extensión *.vars.yml (o *.vars.yaml):

Auto-Cargado Automático

Cualquier archivo que coincida con el patrón *.vars.yml dentro del workspace (por ejemplo, testform.vars.yml, default.vars.yml) se carga automáticamente en orden alfabético al ejecutar testform plan y testform apply:

# testform.vars.yml (Auto-cargado por defecto)
environment: "staging"
base_url: "https://staging-api.empresa.com"
timeout_ms: 10000

Inyección por Entorno (-var-file)

Para entornos específicos como producción o CI/CD, puedes crear archivos dedicados e inyectarlos explícitamente:

prod.vars.yml

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

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

---

4. Uso en Escenarios Gherkin

Dentro de cualquier paso de prueba puedes interpolar variables usando ${var.<nombre>}:

Scenario: Autenticación con credenciales dinámicas
  Given el navegador se dirige a "${var.base_url}/login"
  When ingresa el usuario "qa-tester"
  Then la sesión se inicia en menos de ${var.timeout_ms} milisegundos

---

5. Jerarquía de Precedencia

Testform resuelve el valor final de cada variable evaluando las fuentes de menor a mayor prioridad:

▲ MÁXIMA PRIORIDAD
│  [Nivel 5] Flags CLI:            -var "clave=valor"
│  [Nivel 4] Archivos CLI:         -var-file="staging.yml"
│  [Nivel 2] Dominio / Carpetas:   auth/auth.yml, inventory/inventory.yml, etc.
│  [Nivel 1] Estándar Terraform:   variables.yml, locals.yml
│  [Nivel 0] Manifiesto Base:       main.yml (defaults globales)
▼ BASE / MENOR PRIORIDAD

Consejo

Control total en CI/CD: Puedes fijar defaults comunes en testform.vars.yml para los desarrolladores locales y sobreescribir variables en el runner de GitHub Actions con -var-file=ci.vars.yml o -var="environment=prod".