testform report

testform [opciones globales] report <tipo> [opciones]

El comando testform report compila informes analíticos multidimensionales a partir del estado de ejecución (testform.state). Integra un motor desacoplado que separa la recolección de métricas del renderizado de formatos, soportando exportación nativa a Markdown, JSON, CSV, Word (.docx) y Excel (.xlsx), con capacidades de plantillas dinámicas y autocarga por convención.

Paridad con Terraform: Cero Polución

A diferencia de herramientas que requieren ensuciar main.yml con bloques de configuración de reportes, Testform utiliza autocarga automática desde .testform/reports/ para reportes, formatos y plantillas personalizadas.

---

Opciones del Comando

Opción	Por Defecto	Descripción
<tipo>	(Requerido)	Nombre del reporte a generar (ver catálogo de reportes).
-format=<formato>	md	Formato de salida: md, json, csv, xlsx, docx o formato personalizado.
-out=path	stdout	Ruta del archivo de destino donde guardar el reporte.
-filter=<query>	—	Filtro unificado por clave-valor (campo=valor) o texto libre. Puede repetirse.
-target=<recurso>	—	Acota el reporte a un recurso específico (@tr-N, @tp-N, ruta). En un testplan expande automáticamente todas sus corridas vinculadas.
-groupBy=<campo>	—	Agrupa los resultados dinámicamente por un campo (status, label, assignee, etc.).
-template=path	—	Ruta a plantilla personalizada (Word .docx, Excel .xlsx o texto).
-var='k=v'	—	Inyecta o sobrescribe variables para interpolación en plantillas.
-var-file=path	—	Carga variables de interpolación desde un archivo YAML (vars.yml).

---

Catálogo de reportes del core

Testform incluye 9 tipos de reportes predefinidos organizados por alcance (scope), más un extractor de datos puros (raw):

1. Alcance: Casos de Prueba (testcase)

• testcase-summary: Inventario de casos de prueba registrados con su estado actual, etiquetas, responsable y prioridad.
• test-case-activity: Registro cronológico de actividad, ejecuciones recientes y tendencias de casos de prueba.

2. Alcance: Ejecuciones de Prueba (testrun)

• testrun-summary: Resumen analítico de ejecuciones con métricas globales (Total Test Runs, Passed, Failed, Blocked, Skipped, Unexecuted) y tasa de aprobación (passRate).
• testrun-detailed: Vista granular y detallada paso a paso de ejecuciones individuales y sus escenarios.

3. Alcance: Planes de Prueba (testplan)

• testplan-summary: Progreso global de planes de prueba y estado consolidado de los test runs vinculados.

4. Multidimensional y Calidad Cruzada

• defects: Listado de pruebas con fallo (failed) o bloqueo (blocked), vinculando tags de defectos e incidencias.
• traceability: Matriz de trazabilidad entre requerimientos de negocio/etiquetas y ejecuciones reales.
• coverage: Porcentaje de cobertura y casos ejecutados agrupados por módulos o componentes.
• two-dimensional: Matriz de contingencia bidimensional (ej. Estado vs. Prioridad o Componente).
• raw: Volcado directo de la colección filtrada en formato de datos estructurados para integraciones externas.

---

Filtrado y agrupación unificados (StateQuery)

El comando report comparte el mismo motor de consulta que testform query:

1. Filtrado por Atributos Nativos (clave=valor)

# Filtrar solo ejecuciones fallidas
testform report testcase-summary -filter "status=failed"

# Filtrar por etiqueta y responsable simultáneamente
testform report testrun-summary -filter "label=@smoke" -filter "assignee=flavio"

2. Filtrado por Campos Personalizados (main.yml)

Si tu configuración define campos como priority, sprint o component:

testform report testcase-summary -filter "priority=high" -filter "sprint=SP-24"

3. Búsqueda de Texto Libre Inferida (sin =)

Cualquier término que no contenga = se evalúa automáticamente como búsqueda difusa sobre el ID, título o tags:

testform report testcase-summary -filter "login"

4. Agrupación Dinámica (-groupBy)

Reorganiza las filas de datos automáticamente según el campo indicado:

testform report testcase-summary -groupBy status
testform report coverage -groupBy label

---

Alcance por target (-target)

El flag -target permite limitar el universo de datos del reporte a una entidad específica y sus dependencias de ejecución:

1. Target a un Test Run (-target="@tr-N")

Genera el reporte considerando únicamente la corrida de prueba indicada y los casos ejecutados en ella:

# Detalle paso a paso solo de la corrida @tr-1
testform report testrun-detailed -target="@tr-1"

# Resumen de casos de prueba ejecutados en sprint1.run.feature
testform report testcase-summary -target="sprint1.run.feature"

2. Target a un Test Plan con Múltiples Runs (-target="@tp-N")

Cuando se apunta a un plan de pruebas (testplan), Testform inspecciona las corridas vinculadas (attributes.testruns), localiza automáticamente todas las corridas asociadas e incluye todos los casos de prueba ejecutados en ellas:

# Resumen de las corridas pertenecientes al plan @tp-1
testform report testrun-summary -target="@tp-1"

# Listado de defectos detectados exclusivamente dentro del plan @tp-1
testform report defects -target="@tp-1"

# Matriz de cobertura del plan de release
testform report coverage -target="tests/plans/release-v2.plan.feature"

3. Combinación de -target con -filter

Puedes combinar -target para fijar el plan o corrida y -filter para afinar la búsqueda:

# Ver solo casos fallidos dentro del plan @tp-2
testform report testrun-detailed -target="@tp-2" -filter "status=failed"

---

Formatos nativos de salida

Paquetes Opcionales para Word y Excel

Para mantener la instalación de Testform ultra ligera y sin dependencias pesadas, los motores de generación de Word (docx) y Excel (exceljs) están configurados como dependencias opcionales (peer dependencies). Si deseas utilizar estos formatos binarios, solo necesitas instalar el paquete correspondiente de forma global o local:

# Para reportes en Word (.docx)
npm install -g docx

# Para reportes en Excel (.xlsx)
npm install -g exceljs

Markdown (-format=md)

Genera tablas Markdown estándar con bloques de métricas clave. Ideal para stdout, consolas de CI/CD o resúmenes de PR.

testform report testrun-summary -format=md

JSON (-format=json)

Genera una estructura de datos normalizada con title, metrics, headers y rows. Ideal para integraciones con dashboards o ingesta en bases de datos.

testform report defects -format=json -out=dist/defects.json

CSV (-format=csv)

Exporta filas tabulares con escape estándar RFC 4180 para análisis en herramientas de BI o spreadsheets.

testform report traceability -format=csv -out=traceability.csv

Documento Word (-format=docx)

Genera un documento Word corporativo con estilos profesionales, métricas destacadas y tablas coloreadas.

testform report testrun-summary -format=docx -out=informe-ejecutivo.docx

Libro Excel (-format=xlsx)

Genera un archivo Excel profesional con auto-ajuste de columnas, celdas de métricas estilizadas y formato de celdas.

testform report coverage -format=xlsx -out=cobertura.xlsx

---

Plantillas dinámicas con marcadores ${...}

Para mantener total consistencia con el sistema de variables de Testform y evitar colisiones sintácticas, todas las plantillas Word y Excel utilizan marcadores ${...}:

Marcador	Descripción	Ejemplo de Resolución
${var.<nombre>}	Variable de entorno o proyecto cargada desde vars.yml o -var.	${var.company} -> ACME Corp
${report.title}	Título del reporte activo.	${report.title} -> Test Run Summary
${date}	Fecha y hora de generación.	${date} -> 2026-10-26 14:30:00
${<metrica>}	Métricas del reporte (total, passed, failed, etc.).	${total} -> 45
${table} o ${report.table}	Punto de anclaje de la tabla dinámica. Se sustituye por la tabla completa generada.	Tabla con cabeceras y filas

testform report testrun-summary -format=docx -template=templates/informe-qa.docx -var="company=FinTech SAC" -out=informe.docx

---

Extensibilidad y autocarga desde .testform/reports/

Puedes incorporar nuevos reportes, nuevos formatos o plantillas corporativas sin modificar main.yml:

mi-proyecto/
├── .testform/
│   └── reports/
│       ├── report.docx              # Plantilla Word por defecto para el proyecto
│       ├── report.xlsx              # Plantilla Excel por defecto para el proyecto
│       ├── sprint-metrics.ts        # Nuevo reporte: "testform report sprint-metrics"
│       └── slack.format.ts          # Nuevo formato: "testform report ... -format=slack"
├── main.yml
└── tests/

Consulta la Referencia de API de Reportes para ver contratos de desarrollo, tipos y ejemplos de código.

---

Integración con CI/CD (GitHub Actions)

- name: Generar Reporte de Pruebas
  run: |
    # Publicar resumen Markdown en el Job Summary de GitHub
    testform report testrun-summary -format=md >> $GITHUB_STEP_SUMMARY

    # Generar informe Word formal para entrega
    testform report testrun-summary -format=docx -out=dist/informe-qa.docx

- name: Subir Informe Ejecutivo
  uses: actions/upload-artifact@v4
  with:
    name: informe-qa-word
    path: dist/informe-qa.docx