Gestión de Suites de Pruebas

El comando testform suite es el conjunto de herramientas de Testform para la creación, estructuración, filtrado y marcado declarativo de archivos de ejecución (.run.feature) y planes de prueba (.plan.feature).

Filosofía: Separación entre Estado y Ejecución

Testform no es un ejecutor de pruebas ni compite con runners como Playwright, Cypress o Vitest:

• Los Runners (Playwright, Cypress, Vitest): Se encargan de levantar navegadores, simular acciones de usuario y verificar aserciones en código.
• Testform: Gestiona la infraestructura de pruebas como código (Test-as-Code), el catálogo de cobertura, el ledger de estado autorizado (testform.state) y la conciliación remota en Jira o GitHub Projects.

 ┌────────────────────────────────────────────────────────┐
 │  1. GENERACIÓN DECLARATIVA DE LA SUITE                 │
 │     testform suite -tags="[@smoke]"                    │
 └──────────────────────────┬─────────────────────────────┘
                            │ (Crea runs/20261024_smoke.run.feature con status=pending)
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │  2. EJECUCIÓN EXTERNA (Runner de Pruebas)              │
 │     npx playwright test tests/e2e/                     │
 └──────────────────────────┬─────────────────────────────┘
                            │ (Obtiene resultados: passed / failed)
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │  3. MARCADO DE RESULTADOS EN GHERKIN                   │
 │     testform suite mark "@tc-login=passed" -target=... │
 └──────────────────────────┬─────────────────────────────┘
                            │ (Actualiza línea "* mark status = passed")
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │  4. CONCILIACIÓN REMOTA CONTRA GITHUB / JIRA           │
 │     testform apply -auto-approve                       │
 └────────────────────────────────────────────────────────┘

---

Generación de Suites por Tags (suite tags / -tags)

Permite generar instantáneamente un archivo de corrida de pruebas (.run.feature) a partir de expresiones de etiquetas con corchetes ([...]):

1. Dirección a Nivel de Workspace ([@tag])

Busca en todos los archivos .case.feature del workspace y agrupa bajo un bloque Rule: cada archivo que contenga escenarios con esa etiqueta:

npx testform suite -tags="[@smoke]" -title="Smoke Suite Regresión"

Genera automáticamente el archivo .run.feature:

@testrun @tr-1
Feature: Smoke Suite Regresión

  Rule: auth.case.feature
    Scenario: Inicio de sesión exitoso
      * mark status = pending

  Rule: checkout.case.feature
    Scenario: Pago con tarjeta de crédito
      * mark status = pending

2. Dirección Específica de Archivo (archivo.[@tag])

Filtra únicamente los escenarios que posean la etiqueta indicada dentro de un archivo .case.feature específico:

npx testform suite -tags="checkout.case.feature.[@smoke]"

3. Etiquetas Múltiples

Admite combinar etiquetas separadas por comas. Se incluirá cualquier escenario que cumpla con al menos una de ellas:

npx testform suite -tags="[@smoke,@critical]"

---

Subcomandos de testform suite

El comando dispone de 5 operaciones estandarizadas:

Subcomando	Descripción	Sintaxis Principal
tags	Genera una suite .run.feature a partir de direcciones de tags entre corchetes.	testform suite tags "<address>" o testform suite -tags="<address>"
init	Crea el esqueleto base de una suite .run.feature o .plan.feature.	testform suite init -scope=<testrun|testplan> [-title=<title>]
fill	Autocompleta bloques Rule vacíos en un testrun con los casos de su .case.feature.	testform suite fill -target=<target>
link	Vincula un caso o corrida de prueba dentro de una suite destino.	testform suite link "<identifier>=<status>" -target=<target>
mark	Registra el estado de ejecución de un caso dentro de la corrida Gherkin.	testform suite mark "<identifier>=<status>" -target=<target>

---

Estrategias Unificadas de Identificación

Para evitar inconsistencias, todos los subcomandos de testform suite implementan exactamente las mismas estrategias:

Estrategia de Target (-target=<target>)

Determina la suite destino en fill, link y mark:

1. Canonical Address: tests/runs/smoke.run.feature.@tr-1 o smoke.run.feature.@tr-1
2. File Path: tests/runs/smoke.run.feature (o relativo)
3. Identity Tag: @tr-1

Estrategia de Identificador (<identifier>=<status>)

Determina qué caso de prueba se está marcando o enlazando:

1. Identity Tag: "@tc-1=passed"
2. Canonical / File: "checkout.case.feature.@tc-1=passed"
3. Scenario Name: "Pago con tarjeta=passed"

Estados de ejecución admitidos: pending, passed, failed, blocked, skipped, undefined.

---

Integración con Pipelines CI/CD

En un pipeline de CI/CD (GitHub Actions, GitLab CI), puedes conectar tu runner automatizado con Testform de manera declarativa:

- name: Generar Suite Smoke
  run: npx testform suite -tags="[@smoke]" -title="CI PR #${{ github.event.number }}"

- name: Ejecutar Pruebas Automatizadas
  id: runner
  run: npx playwright test --reporter=json > test-results.json

- name: Marcar Resultados en la Suite
  run: |
    # Script que lee test-results.json y actualiza Testform
    npx testform suite mark "@tc-auth-001=passed" -target="@tr-1"
    npx testform suite mark "@tc-checkout-001=failed" -target="@tr-1"

- name: Conciliar Estado en GitHub Projects
  run: npx testform apply -auto-approve