testform suite

testform suite [subcomando] [opciones]

El comando testform suite gestiona y automatiza el ciclo de vida de los archivos de suite de pruebas (testrun y testplan). Permite estructurar, poblar, vincular y registrar resultados de ejecución de manera rápida y programática, eliminando la necesidad de redactar sintaxis Gherkin a mano.

---

Estructura de Comandos y Opciones

testform suite define init como su subcomando de creación, mientras que las operaciones sobre suites existentes se invocan mediante opciones:

testform suite init [opciones]
testform suite -fill -target=<resource>
testform suite -link="<id>[=status]" -target=<resource>
testform suite -mark="<id>=status" -target=<resource>
testform suite -tags="<address>"

[!NOTE] Por conveniencia y compatibilidad con scripts de terminal, también puedes invocarlos como argumentos posicionales (ej. testform suite fill ..., testform suite link ..., testform suite mark ...).

---

Subcomando: init

Crea un nuevo archivo de suite de ejecución (.run.feature) o de planificación (.plan.feature) siguiendo las convenciones de nomenclatura configuradas (timestamp, hash o slug):

testform suite init -scope=testrun -title="Regresión Sprint 42"
testform suite init -scope=testplan -title="Plan de Lanzamiento Q3"

Opciones de init:

• -scope=<testrun|testplan>: Ámbito de la suite (requerido).
• -title="<texto>": Título descriptivo para el encabezado del Feature.
• -rule="<archivo>": Archivo fuente a incluir como bloque Rule: inicial (puede repetirse).

---

Opciones Principales

1. -fill (Autocompletar Reglas en Testruns)

Lee los bloques Rule: vacíos o implícitos de un archivo .run.feature, busca los archivos .case.feature correspondientes y vuelca todos sus escenarios en estado inicial pending:

testform suite -fill -target="@tr-42"
testform suite -fill -target="sprint42.run.feature"

Cada escenario generado incluye el paso estándar de ejecución:

* mark status = pending

---

2. -link="<identificador>[=estado]" (Enlazar Casos o Suites)

Inyecta la estructura Gherkin adecuada directamente en el archivo de la suite sin editar el texto manualmente.

En Ámbito testrun:

• Enlace Implícito (archivo completo): Vincula un feature de casos agregando la regla:

  testform suite -link="checkout.case.feature" -target="@tr-42"

  Produce:

  Rule: checkout.case.feature

• Enlace Explícito (caso específico): Vincula un escenario individual bajo su regla:

  testform suite -link="@tc-1=passed" -target="@tr-42"
  testform suite -link="checkout.case.feature.@tc-1=passed" -target="@tr-42"

  Produce:

  Rule: checkout.case.feature
    Scenario: @tc-1
      * mark status = passed

En Ámbito testplan:

Vincula suites de ejecución completas (.run.feature):

testform suite -link="sprint42.run.feature" -target="@tp-1"
testform suite -link="@tr-42" -target="@tp-1"

[!IMPORTANT] Los planes de prueba (testplan) solo enlazan suites de ejecución (testrun) completas. No deben contener escenarios individuales directamente.

---

3. -mark="<identificador>=<estado>" (Registrar Estado de Ejecución)

Actualiza el resultado de ejecución (passed, failed, pending, skipped) de un caso en un .run.feature, sincronizando el archivo local y recalculando automáticamente el veredicto consolidado (Rollup Verdict) en el ledger de estado testform.state:

testform suite -mark="@tc-1=passed" -target="@tr-42"
testform suite -mark="checkout.case.feature.@tc-1=failed" -target="@tr-42"
testform suite -mark="Pago con tarjeta exitoso=passed" -target="@tr-42"

[!WARNING] Si la regla donde reside el caso aún es implícita (Rule: checkout.case.feature), debes ejecutar primero -fill antes de registrar estados con -mark.

---

4. -tags="<expresión>" (Generación por Tags)

Genera automáticamente un archivo de suite .run.feature filtrando escenarios de prueba mediante expresiones de tags entre corchetes:

# Todos los casos etiquetados con @smoke en el proyecto
testform suite -tags="[@smoke]"

# Casos etiquetados con @smoke dentro de un feature específico
testform suite -tags="cuenta.case.feature.[@smoke]"

---

Resolución de Objetivos (-target)

Las opciones -fill, -link y -mark requieren identificar la suite de destino mediante -target. Testform soporta tres modalidades de resolución:

                           ┌──────────────────────────────┐
                           │    Resolución de -target     │
                           └──────────────┬───────────────┘
                                          │
         ┌────────────────────────────────┼────────────────────────────────┐
         ▼                                ▼                                ▼
  Identity Tag                    Canonical Address                Canonical File
 (@tr-N / @tp-N)           (Dirección Inmutable Completa)        (Scoped File Path)

 Exclusivo para Suites     Ruta canónica completa con tag.      Ruta relativa al directorio
 (testrun y testplan son   Ej: tests/runs/sprint42.run.feature  de pruebas (-test-directory).
 únicos en el workspace).  .@tr-1                               Ej: sprint42.run.feature

1. Identity Tag (@tr-N / @tp-N)

• Identificador global único: Se resuelve directamente contra el archivo de estado (testform.state).
• Solo para testrun y testplan: Los tags de corrida (@tr-1, @tr-2) y de plan (@tp-1) son únicos en todo el proyecto.
• ¿Por qué NO para @tc-N como target? Los tags de casos (@tc-1, @tc-2) son locales y pueden repetirse en múltiples archivos .case.feature diferentes. Usar un @tc-N sin especificar el archivo rompería la unicidad. Por ello, @tc-N se utiliza en el argumento de enlace o marca, mientras que -target apunta al contenedor único (@tr-N).

2. Canonical Address vs Canonical File (Scoped File Path)

La diferencia fundamental entre Canonical Address y Canonical File radica en el alcance configurado por -test-directory:

Concepto	Definición	Ejemplo
Canonical Address	La dirección inmutable y completa del recurso, que incluye su ruta absoluta/raíz y su tag de identidad.	tests/runs/20261024.run.feature.@tr-1
Canonical File (Scoped)	La ruta recortada relativa al directorio de pruebas actual configurado con -test-directory.	20261024.run.feature

• Si -test-directory no se especifica (o es la raíz del workspace), ambas rutas pueden coincidir.
• Si -test-directory="tests/runs" está definido, el usuario puede referenciar el archivo de forma recortada y limpia (20261024.run.feature), y Testform resuelve automáticamente la dirección canónica completa en el grafo de dependencias.

---

Auto-ayuda Interactiva

Si omites -target o parámetros obligatorios al invocar testform suite, la herramienta inicia un asistente interactivo:

• Lista las suites disponibles en el estado para que selecciones una con el teclado.
• Guía la creación de suites paso a paso si omites -scope o -title.
• Permite seleccionar si deseas realizar un enlace implícito (archivo completo) o explícito (escenario específico).