Aprende a instalar Testform globalmente, inicializar tu espacio de trabajo y comprender el ciclo de vida del estado según el tipo de backend configurado.
Si utilizas el proveedor local (provider: local y backend: local), no requieres ninguna cuenta externa, token ni conexión a internet. Testform opera de forma 100% autónoma y offline, guardando el ledger de pruebas en tu archivo local testform.state o en tu repositorio Git.
Al conectar Testform con GitHub para sincronizar casos de prueba, ejecuciones y suites en GitHub Issues y tableros de proyectos, tu organización y repositorio deben cumplir con los siguientes requisitos:
GitHub Project (Projects V2):
Un proyecto de GitHub activo (a nivel de organización o usuario) vinculado al repositorio de pruebas.
Un campo de selección única (Single-select field) denominado estrictamente Status, configurado con las siguientes opciones exactas:
Todo
Done
passed
failed
blocked
skipped
unexecuted
Etiquetas del Repositorio (Labels):
El repositorio requiere las siguientes 5 etiquetas para clasificar automáticamente las incidencias:
bug
testcase
testplan
testreport
testrun
Autenticación y Permisos del Token (PAT):
Un Personal Access Token (PAT) con los permisos adecuados:
Classic PAT: Scopes repo (control total de repositorios) y project (lectura y escritura de proyectos).
Fine-Grained PAT: Permisos de repositorio (Issues: Read and write) y permisos de organización (Projects: Read and write).
El token debe exportarse en tu terminal como variable de entorno (por ejemplo, export GITHUB_TOKEN="ghp_...") o configurarse mediante testform login.
Configuración Automatizada con Workflow (Recomendado):
Para automatizar la creación de etiquetas y la vinculación del proyecto en cuestión de segundos, recomendamos utilizar el workflow oficial Install Testform Labels and Project (.github/workflows/install.yml). Este flujo automatizado:
Para preservar un binario ultra-ligero (~1 MB), los motores generadores de documentos binarios (docx y exceljs) están desacoplados como dependencias opcionales. Si vas a generar reportes en Word (.docx) o Excel (.xlsx), instálalos bajo demanda:
Ventana de terminal
npminstall-gdocxexceljs
# O como dependencia de desarrollo en tu proyecto local:
Testform es una herramienta de línea de comandos (CLI) que se instala únicamente de forma global en tu sistema operativo, al igual que herramientas como Terraform o Git:
Ventana de terminal
npminstall-g@fromeroc9/testform@beta
Verifica la instalacion consultando la version del binario:
Ventana de terminal
testform-version
Salida esperada en terminal:
Testform v1.1.0
on win32_x64
Testform consulta automaticamente el registro de NPM para comprobar si existe una version mas reciente. Si tu CLI esta desactualizada, mostrara un aviso similar al de Terraform:
Your version of Testform is out of date! The latest version
Cuando utilizas el backend local por defecto, los archivos de estado se crean dinamicamente segun la fase del flujo de trabajo:
Tras testform init:
Unicamente existe main.yml. No se crea testform.state ni copias de respaldo.
Durante testform plan:
Si testform.state aun no existe, Testform lee un estado vacio en memoria (0 recursos) y calcula las adiciones planeadas (+ create) en modo de solo lectura, sin escribir nada en disco.
Tras el primer testform apply:
Al aplicar los recursos con exito, se crea por primera vez testform.state con serial: 1 y los metadatos de los casos conciliados. No se crea archivo .backup porque no habia un estado previo que respaldar.
A partir del segundo testform apply:
Antes de modificar el estado, Testform copia el estado previo a testform.state.backup (serial: 1) y escribe el nuevo estado en testform.state (serial: 2). Ambos archivos comparten exactamente el mismo formato JSON.
mi-proyecto/
├── main.yml # Manifiesto principal de configuracion
├── testform.state # Estado activo (creado tras el primer apply)
└── testform.state.backup # Respaldo automatico (creado a partir del segundo apply)
Ciclo de Vida en Backends Remotos (s3, oci, azurerm, gcs)
Cuando configuras un backend en la nube en tu main.yml:
mi-proyecto/
└── main.yml # Manifiesto principal de configuracion
Sin archivos de estado locales: En ningun momento se generan archivos testform.state ni testform.state.backup en tu disco local.
Persistencia en la Nube: Las operaciones de lectura y escritura (s3.putObject, UploadBlob, etc.) se comunican de forma directa y atomica con el bucket remoto.
Repositorio Git Limpio: Tu espacio de trabajo queda 100% libre de archivos de estado locales, previniendo conflictos en Pull Requests y filtraciones de credenciales.
Respaldos Nativos: La recuperacion ante desastres y el historial de cambios se gestionan con el Versionado de Objetos nativo (Bucket Versioning) del proveedor cloud.