Recursos Declarativos y Personalización

Resources (Recursos Declarativos y Personalización)

En Testform, los Recursos son el bloque de construcción fundamental del testing. Mientras que en Terraform un recurso modela un componente de infraestructura (una instancia EC2, un bucket S3), en Testform un recurso modela una especificación BDD de prueba o una ejecución con ciclo de vida gestionado.

Nota

BDD as Code: En Testform las pruebas viven en archivos Gherkin (.feature), no en bloques YAML. El motor interno de resource.ts traduce automáticamente los escenarios a los objetos de las APIs remotas de los proveedores.

---

Tipos Canónicos de Recursos

Testform define internamente plantillas declarativas para los recursos de gestión de calidad:

Recurso	Propósito	Formato / Ubicación
github_testcase	Especificación unitaria de prueba individual	Scenario: en archivos *.case.feature
github_testrun	Ejecución inmutable de pruebas contra un build	*.run.feature
github_testplan	Plan de orquestación y alcance de pruebas	*.plan.feature
Custom Resources	Recursos personalizados para Jira, TestRail, etc.	Definidos mediante registerResource()

---

1. Extensión de Campos en YAML (Configuración Declarativa)

Cuando deseas agregar campos calculados o metadatos adicionales a los recursos canónicos (testcase, testrun, testplan), puedes extenderlos directamente en el bloque resource de tu archivo de configuración YAML, sin necesidad de redefinir generadores de pasos ni código TypeScript:

main.yml

resource:
  testcase:
    fields:
      severity: "${custom.fields.severity || 'Normal'}"
      jira_component: "${custom.fields.component || 'Core'}"
      team_owner: "QA-Core"

Los campos declarados se fusionan automáticamente con los campos nativos del recurso en tiempo de ejecución.

---

2. Modificación de Recursos ya Declarados por el Usuario (registerResource)

Los recursos predefinidos en resource.ts (github_testcase, github_testrun, etc.) no son cajas negras cerradas. Cualquier equipo puede modificar o sobreescribir los campos, el formato del body o las etiquetas generadas utilizando registerResource().

Las definiciones del usuario toman precedencia automática sobre las plantillas del sistema, preservando los campos no modificados:

TypeScript

import { registerResource } from 'testform';

// Sobreescribir el recurso ya declarado github_testcase
registerResource({
    type: 'github_testcase',
    fields: [
        // Personalizamos el título con un prefijo corporativo
        { name: 'title', value: (s) => `[QA-CORE] ${s.name}` },

        // Formato Markdown personalizado para el cuerpo del Issue
        {
            name: 'body',
            value: (s) => `## Caso de Prueba: ${s.name}\n\n### Pasos a Ejecutar:\n` +
                          s.steps.map(step => `- **${step.keyword}** ${step.text}`).join('\n')
        },

        // Etiquetas automáticas personalizadas
        {
            name: 'labels',
            value: (s) => [...new Set(['automated', ...(s.tags || []).map(t => t.replace('@', ''))])]
        }
    ]
});

JavaScript

const { registerResource } = require('testform');

registerResource({
    type: 'github_testcase',
    fields: [
        { name: 'title', value: (s) => `[QA-CORE] ${s.name}` },
        {
            name: 'body',
            value: (s) => `## Caso: ${s.name}\n\n` + s.steps.map(st => `${st.keyword}${st.text}`).join('\n')
        }
    ]
});

---

3. Registro de Nuevos Proveedores (Custom Providers)

Para conectar Testform con plataformas externas (Jira, TestRail, Zephyr o herramientas propietarias), se registran recursos adicionales mediante la misma API pública:

import { registerResource } from 'testform';

registerResource({
    type: 'jira_testcase',
    fields: [
        { name: 'summary', value: (s) => s.name },
        {
            name: 'description',
            value: (s) => s.steps.map(st => `${st.keyword} ${st.text}`).join('\n')
        },
        {
            name: 'priority',
            value: (s) => s.custom?.fields?.priority || 'Medium'
        }
    ]
});

---

4. Direcciones Canónicas de Recursos (Resource Addresses)

Al igual que en Terraform cada recurso posee un identificador universal único (ej. aws_instance.web), en Testform cada recurso se direcciona mediante notación por puntos pura:

<ruta_archivo_relativa>.<tag_identificador>

Ejemplos:

• features/auth/login.case.feature.@tc-001
• features/checkout/payment.case.feature.@tc-stripe

Estas direcciones son utilizadas por:

• El motor de dependencias @depends_on("features/auth/login.case.feature.@tc-001")
• El ledger inmutable de estado testform.state
• Comandos CLI como testform state show <address> y testform taint <address>

---

5. Estado y Conciliación

Durante testform plan, el motor compara los recursos declarados en el código BDD con el estado actual registrado en testform.state:

• + create: Se ha creado un nuevo escenario de prueba.
• ~ update: Se han modificado pasos, tags o variables de un escenario existente.
• - destroy: Se ha eliminado un escenario del código.