Especificación de main.yml

El archivo main.yml es el manifiesto de configuración central de tu espacio de trabajo. En él se declaran la versión requerida de Testform, el backend de almacenamiento de estado, los proveedores externos, los alcances (scopes) y el esquema de campos personalizados.

Estructura General

main.yml

testform:
  required_version: ">= 1.0.0"
  backend:
    local:
      path: "testform.state"

# 1. Configuración del Proveedor (GitHub, Jira, GitLab, Local)
provider:
  github:
    owner: "mi-organizacion"
    repository: "mi-aplicacion"
    project_number: 12
    token_env: "GITHUB_TOKEN"

# 2. Variables y Valores Locales Base
variable:
  app_url:
    type: string
    description: "URL base de la aplicacion"
    default: "https://www.saucedemo.com"
  environment:
    type: string
    default: "dev"

locals:
  base_url: "${var.app_url}"
  api_health: "${local.base_url}/health"

# 3. Declaración de Recursos de Prueba (resource)
# Permite estrictamente: testcase, testrun, testplan (y global)
resource:
  global:
    scaffold:
      directory: "tests"
    fields:
      - name: priority
        source: "tag"
        enum: ["@low", "@medium", "@high", "@critical"]
        default: "@medium"
  testcase:
    match: "*.case.feature"
    scaffold:
      directory: "tests/features"
      filename: "{slug}.case.feature"
    fields:
      - name: module
        source: "step"
        required: true
  testrun:
    match: "*.run.feature"
    scaffold:
      directory: "tests/runs"
      filename: "{slug}.run.feature"
    fields:
      - name: environment
        source: "step"
        default: "qa"
  testplan:
    match: "*.plan.feature"
    scaffold:
      directory: "tests/plans"
      filename: "{slug}.plan.feature"

Pipeline de Compilación y Procesamiento de Configuración

Testform procesa las diferentes capas de configuración mediante un motor secuencial en memoria:

 ┌────────────────┐   ┌────────────────┐   ┌────────────────┐
 │    main.yml    │   │ variables.yml  │   │  resource.yml  │
 └───────┬────────┘   └───────┬────────┘   └───────┬────────┘
         │                    │                    │
         ▼                    ▼                    ▼
   [FASE 1: DESCUBRIMIENTO Y FUSIÓN DE ESQUEMA EN MEMORIA]
         │
         ▼
   [FASE 2: INGESTA DE VALORES Y PRECEDENCIA (*.vars.yml, CLI)]
         │
         ▼
   [FASE 3: VALIDACIÓN ESTÁTICA Y MOTOR AST (enum, condition)]
         │
         ▼
   [FASE 4: EVALUACIÓN DE LOCALS Y FUNCIONES HCL]
         │
         ▼
   [FASE 5: INYECCIÓN EN RECURSOS GHERKIN (*.case.feature) + DAG]
         │
         ▼
   [FASE 6: CONCILIACIÓN DIFF CONTRA testform.state (plan / apply)]

---

1. Bloque backend

Determina donde se almacena el ledger de estado (testform.state) y como se gestiona el bloqueo concurrente:

Tipo (type)	Descripcion	Parametros Requeridos
local	Almacenamiento en archivo local (ideal para desarrollo individual).	path
oci	Oracle Cloud Infrastructure Object Storage con bloqueo condicional de ETag.	namespace, bucket, object_name, tenancy_id
s3	Amazon S3 con bloqueo distribuido mediante Amazon DynamoDB.	bucket, key, dynamodb_table, region
azure	Azure Blob Storage con arrendamiento exclusivo de blobs (leases).	storage_account, container, blob_name
gcs	Google Cloud Storage con generacion condicional de objetos.	bucket, prefix

---

2. Bloque resource: Gobierno de Recursos Gherkin

En Testform, los componentes que se gestionan (testcase, testrun, testplan) son Recursos, siguiendo el mismo principio de Terraform. Para evitar que alguien configure tipos no permitidos, Testform valida estrictamente que solo se declaren los recursos oficiales: testcase, testrun, testplan (y global para reglas compartidas).

Para evitar que main.yml sea excesivamente largo, Testform soporta definir el bloque resource: directamente en main.yml o en un archivo modular independiente resource.yml (o resource.yaml).

Flujo de Datos: De Gherkin a resource.ts y al Provider

Los fields no son campos directos de la API remota, sino el contrato de calidad para el autor de Gherkin. El componente resource.ts es el adaptador que extrae esos datos y los entrega al Provider:

  Gherkin (.feature)            resource.yml                   resource.ts                   Provider (GitHub/Jira)
 ┌──────────────────────┐      ┌────────────────────────┐     ┌───────────────────────┐     ┌──────────────────────┐
 │ @high @tc-login-001  │      │ resource:              │     │ resource.registry({   │     │ GitHub Project V2    │
 │ Scenario: Login      │      │   global:              │     │   fields: [           │     │   Status: "Done"     │
 │   * field module =   │ ──►  │     fields: [module,   │ ──► │     custom_fields:    │ ──► │   Project: "HT 360"  │
 │     "auth"           │      │       priority,        │     │       s.custom.fields │     │   Module: "auth"     │
 │                      │      │       Status]          │     │   ]                   │     │   Priority: "high"   │
 └──────────────────────┘      └────────────────────────┘     └───────────────────────┘     └──────────────────────┘

Estructura en resource.yml

resource.yml

resource:
  # 1. Reglas comunes heredadas por TODOS los recursos
  global:
    scaffold:
      filename: "{YYYYMMDD}_{HHmmss}"
    fields:
      - name: project
        source: step
        required: true
        default: "Hirent Talent 360"
      - name: assignees
        source: step
        required: true
        default: "fromeroc9"
      - name: priority
        source: tag
        enum: ["@low", "@medium", "@high"]
        default: "@medium"
      - name: Status
        source: step
        required: true
        default: "Done"

  # 2. Recurso testcase (*.case.feature)
  testcase:
    match: "*.case.feature"
    identity: "tc-*"
    fields:
      - name: module
        source: step
        required: true
      - name: functional
        source: step
        required: true

  # 3. Recurso testrun (*.run.feature)
  testrun:
    match: "*.run.feature"
    identity: "tr-*"
    fields:
      - name: startDate
        source: step
      - name: endDate
        source: step

  # 4. Recurso testplan (*.plan.feature)
  testplan:
    match: "*.plan.feature"
    identity: "tp-*"
    fields: []

3. Declaración de fields: source y enum

En Testform, los campos personalizados se declaran dentro de scopes.<scope>.fields o scopes.global.fields. Se configuran utilizando las siguientes propiedades esenciales:

• source (Origen de Extracción): Especifica de dónde extrae Testform el valor del campo:
  • tag: El valor se extrae de las etiquetas del escenario o feature (ejemplo: @high -> campo priority con valor "@high").
  • step: El valor se define mediante un paso Gherkin con la directiva * field <nombre> = <valor> (ejemplo: * field module = auth).
• enum (Valores Permitidos): Lista cerrada de valores permitidos para el campo (ejemplo: ["@low", "@medium", "@high"]).
• required (Obligatoriedad): Booleano que exige que el escenario declare el campo (o tenga un valor por defecto). Si falta, testform validate reporta una infracción.
• default (Valor Predeterminado): Valor que se asigna automáticamente cuando el escenario no lo declara explícitamente.

4. Configuracion de Proveedores (provider)

Testform soporta proveedores remotos (como GitHub y GitLab) asi como un proveedor completamente local y desconectado (local).

Proveedor Local (provider: local)

El proveedor local permite gestionar casos, ejecuciones y planes sin depender de ningun servicio en la nube ni requerir credenciales de red. Todas las incidencias, comentarios y campos simulados se registran en el archivo local .testform/cache/data.json.

Es ideal para desarrollo individual, pipelines aislados sin acceso a internet o pruebas conceptuales:

# Modo escalar directo
provider: local

O utilizando la sintaxis de diccionario:

provider:
  local: {}

Al utilizar provider: local, los comandos testform plan y testform apply crean identificadores locales con el prefijo local:<numero> (por ejemplo, local:1, local:2), garantizando total reproducibilidad offline.

Proveedor GitHub (provider.github)

Permite sincronizar recursos como incidencias y proyectos en GitHub Projects V2. Testform soporta tanto el numero simple visible en la URL del proyecto (projectId: 12) como el identificador GraphQL de nodo (projectId: "PVT_kwDOB12345").

provider:
  github:
    owner: "mi-organizacion"
    repository: "mi-aplicacion"
    projectId: 12
    token_env: "GITHUB_TOKEN"

Parametro	Descripcion	Requerido
owner	Organizacion o usuario propietario del repositorio en GitHub.	Si
repository	Nombre del repositorio de GitHub.	Si
projectId	Identificador numerico o GraphQL del proyecto en GitHub Projects V2.	No
token_env	Nombre de la variable de entorno con el token de acceso (por defecto GITHUB_TOKEN).	No

El token puede suministrarse de forma segura mediante la variable de entorno GITHUB_TOKEN o la variable personalizada indicada en token_env.

Proveedor GitLab (provider.gitlab)

Permite sincronizar recursos con incidencias en proyectos de GitLab:

provider:
  gitlab:
    projectId: 12345678
    token_env: "GITLAB_TOKEN"

5. Variables (variable:) y Valores Locales (locals:)

Testform permite parametrizar tanto el texto de los pasos Gherkin como las etiquetas mediante variables de entrada e interpolación local:

• variable:: Declaración de variables con tipo (string, number, boolean), descripción, lista permitida enum: [...], reglas validation: y valor por defecto.
• locals:: Expresiones computadas y derivadas, resueltas dinámicamente mediante el motor AST sandboxed (${var.nombre}, ${local.nombre}, ${lower()}, ${format()}).

Para más detalles sobre la precedencia y el sistema de tipos, consulta la Guía de Variables y Tipos.