Arquitectura Modular

Testform implementa un sistema modular completo con paridad funcional a los módulos de Terraform, permitiendo empaquetar, parametrizar y reutilizar flujos de prueba en Gherkin y YAML.

---

1. El Problema de la Duplicación en Testing

Flujos esenciales como autenticación, aprovisionamiento de carritos o navegación inicial se repiten en decenas de archivos de prueba. Duplicar estos pasos manualmente genera código frágil ante cambios de diseño y rompe el principio DRY.

Con los Módulos de Testform, puedes encapsular un flujo completo o un escenario específico y componerlo dinámicamente con parámetros de entrada (vars) y valores de retorno (outputs).

---

2. Declaración de un Módulo

A. Módulo en Archivo Feature (.case.feature)

Crea un archivo de módulo bajo modules/auth/login.case.feature:

@testcase
Feature: Módulo de Autenticación
  @tc-login
  Scenario: Login con credenciales
    Given el usuario navega a "<base_url>"
    When ingresa el usuario "<user>" y contraseña "<password>"
    Then la sesión queda activa con perfil "<role>"

Los pasos pueden utilizar comodines de ángulo <param> o sintaxis de variable ${var.param} que serán inyectados dinámicamente durante la invocación.

B. Declaración en main.yml

Puedes registrar módulos reutilizables centralmente con sus variables por defecto:

module:
  auth_standard:
    source: "./modules/auth/login.case.feature"
    vars:
      base_url: "${var.app_url}"
      user: "standard_user"
      password: "${var.default_password}"
      role: "viewer"
    output:
      session_id:
        value: "${testrun.modules/auth/login.case.feature.@tr-1.issueNumber}"

C. Módulos Remotos (Git Registry)

Testform soporta repositorios Git remotos para compartir módulos entre diferentes proyectos u organizaciones:

module:
  auth_shared:
    source: "git::https://github.com/mi-org/qa-modules.git//auth?ref=v1.2.0"
    vars:
      base_url: "https://staging.empresa.com"

Durante testform init, los módulos remotos se descargan automáticamente en .testform/modules/.

---

3. Invocación y Parámetros (vars)

A. Invocación Directa con vars

Invoca el módulo pasando parámetros de entrada específicos:

@tc-checkout-admin
@module(source="./modules/auth/login.case.feature", variable={user: "admin", role: "superuser"})
Scenario: Pago ejecutado con credenciales administrativas
  When el usuario pulsa "Confirmar Pago"
  Then la transacción es aprobada

Los parámetros declarados en variable={...} sustituyen los valores <user> y <role> en los pasos heredados antes de ejecutar el escenario.

B. Invocación por Nombre de Módulo

Si el módulo fue registrado en main.yml, puedes invocarlo directamente por su nombre o sobreescribir variables:

@tc-checkout-standard
@module("auth_standard")
Scenario: Pago con usuario estándar
  When el usuario pulsa "Confirmar Pago"
  Then la transacción es aprobada

O con variables específicas:

@tc-checkout-custom
@module(name="auth_standard", variable={user: "custom_qa_user"})
Scenario: Pago con usuario de control de calidad
  When el usuario pulsa "Confirmar Pago"
  Then la transacción es aprobada

C. Selección de Escenario Específico

Si un archivo de módulo contiene múltiples escenarios, puedes seleccionar únicamente el que necesitas mediante scenario o notación de puntos:

# Opción 1: Argumento scenario
@module(source="./modules/auth/login.case.feature", scenario="@tc-login", variable={user: "demo"})

# Opción 2: Notación canónica de punto
@module(source="./modules/auth/login.case.feature.tc-login", variable={user: "demo"})

---

4. Scoping Estricto de Outputs (${module.<name>.<output>})

Regla de Aislamiento: Si un output se define dentro de un módulo, el output pertenece exclusivamente al espacio de nombres del módulo y no contamina el ámbito global.

A. Declaración dentro del Módulo

Dentro de modules/auth/output.yml:

output:
  session_token:
    description: "Token generado por el flujo de autenticación"
    value: "tok_secure_active_session"
  user_id:
    value: "${testcase.modules/auth/login.case.feature.@tc-login.remoteId}"

B. Consumo desde el Proyecto Raíz

El proyecto principal o cualquier escenario que consuma el módulo accede al output utilizando el prefijo module.<nombre>.<output>:

main.yml

output:
  active_admin_token:
    description: "Token de sesión del módulo de autenticación"
    value: "${module.auth.session_token}"

Y en pasos de prueba Gherkin:

Scenario: Operación autenticada
  When ejecuta operación usando token "${module.auth.session_token}"

---

5. Inicialización (testform init)

Al ejecutar testform init, Testform detecta los módulos configurados y los prepara:

$ testform init
Initializing the backend...
Successfully configured the backend "local"!

Initializing modules...
- Using local module auth_standard from ./modules/auth/login.case.feature
- Downloading git::https://github.com/mi-org/qa-modules.git//auth?ref=v1.2.0 for auth_shared...
- Installed auth_shared to .testform/modules/auth_shared

Initializing provider plugins...
- Finding fromeroc9/github versions matching "1.0.0"...
- Installed fromeroc9/github v1.0.0

Testform has been successfully initialized!