qa-evidence-reporter

Herramienta de línea de comandos para ejecutar sesiones de QA manual sobre features Gherkin (.feature), capturar evidencia (imágenes/videos/PDFs) paso a paso desde una UI web local, y generar un reporte HTML auto-contenido (dashboard + drill-down por feature, funciona offline, exportable a .zip).

Para el detalle completo de arquitectura, decisiones técnicas y el historial de cambios de cada fase de construcción, ver ARCHITECTURE.md — este README solo cubre lo que un usuario final necesita para instalar y usar la herramienta.

Instalación

Este paquete todavía no está publicado en el registro de npm, así que hoy se instala desde el código fuente. Requiere Node.js 18 LTS o superior — no hay dependencias nativas ni binarios externos que instalar aparte (los thumbnails de imagen se generan con jimp, puro JavaScript).

git clone https://github.com/quindcode/qa-evidence-reporter.git
cd qa-evidence-reporter
npm install
npm run build   # compila CLI/server (tsc) + la UI (vite build)
npm link        # deja el comando "qa-evidence-reporter" disponible en cualquier carpeta

Confirmá que quedó instalado:

qa-evidence-reporter --version

Cuando el paquete se publique en el registro de npm, este paso se va a reducir a npm install -g qa-evidence-reporter — mientras tanto, npm link desde el repo clonado cumple exactamente la misma función.

Flujo de uso

Tu proyecto de QA (los .feature, la evidencia, los reportes) vive en una carpeta separada del repo de esta herramienta — el repo es el programa, no el lugar donde guardás tus casos de prueba reales.

# 1. Creá (o entrá a) la carpeta de tu proyecto de QA, en cualquier lugar de tu máquina:
mkdir mi-proyecto-qa && cd mi-proyecto-qa

# 2. Inicializala:
qa-evidence-reporter init

# 3. Escribí tus .feature en features/ (ver la sección siguiente para la
#    estructura exacta) — init deja uno de ejemplo que podés editar o borrar.

# 4. Levantá el runner interactivo:
qa-evidence-reporter run

# 5. Cuando termines la sesión (o en cualquier momento, sobre el progreso
#    ya guardado), generá el reporte HTML final:
qa-evidence-reporter report

1. `init`

Crea, en el directorio actual:

features/ (con un .feature de ejemplo, comentado y editable/borrable)
evidence/ y reports/ (vacíos)
branding/logo.png + el bloque branding en qa-config.json, con el logo y la paleta estándar de Quind ya configurados — todo proyecto nuevo se ve igual desde el primer momento, sin que haya que configurar nada (ver branding más abajo si necesitás editarlo o desactivarlo).
qa-config.json (ver formato completo más abajo)

qa-evidence-reporter init --name "Mi Proyecto" # opcional, si no se toma el nombre de la carpeta
qa-evidence-reporter init --force              # sobreescribe qa-config.json si ya existe

2. Escribir tus `.feature`

Importante: el parser solo entiende Gherkin. Cualquier archivo .feature que no use las palabras clave de Gherkin (Feature, Scenario, Given, When, Then, etc. — lista completa abajo) no es un formato válido: no se puede escribir en texto libre, Markdown, ni una lista de pasos cualquiera. Si el archivo no respeta la sintaxis, run/report van a fallar con un error claro (FEATURE_PARSE_ERROR) señalando el archivo y el motivo.

Estructura mínima válida — un archivo .feature necesita, como mínimo, una línea Feature: con un nombre, y al menos un Scenario: con al menos un step:

Feature: Nombre de la funcionalidad a probar

  Scenario: Nombre de un caso de prueba concreto
    Given una condición inicial
    Then un resultado esperado

Ejemplo completo, con todo lo que el parser soporta (guardalo como features/login.feature):

# Los tags se muestran en el reporte y en el selector del runner
# (no filtran la ejecución todavía — ver "Usarlo para un test plan completo").
@smoke
Feature: Inicio de sesión
  Como usuario registrado
  quiero iniciar sesión con mis credenciales
  para acceder a mi cuenta.

  # Background: steps que se repiten al principio de cada Scenario de este Feature.
  Background:
    Given estoy en la página de inicio de sesión

  @regression
  Scenario: Inicio de sesión exitoso con credenciales válidas
    When ingreso un usuario y contraseña válidos
    And hago clic en "Ingresar"
    Then accedo correctamente a mi cuenta
    And veo mi nombre en la cabecera del sitio

  Scenario: Inicio de sesión fallido con contraseña incorrecta
    When ingreso un usuario válido con una contraseña incorrecta
    And hago clic en "Ingresar"
    Then veo un mensaje de error indicando credenciales inválidas

  # Scenario Outline + Examples: el mismo caso se ejecuta una vez por cada
  # fila de la tabla, sustituyendo los valores entre <> en cada step.
  Scenario Outline: Validación de campos obligatorios
    When dejo el campo "<campo>" vacío
    And hago clic en "Ingresar"
    Then veo un mensaje pidiendo completar "<campo>"

    Examples:
      | campo       |
      | usuario     |
      | contraseña  |

Palabras clave de Gherkin que el parser reconoce:

Categoría	Palabras clave
Encabezados	`Feature`, `Background`, `Scenario`, `Scenario Outline`
Steps	`Given`, `When`, `Then`, `And`, `But`
Datos	`Examples`, con una tabla de valores debajo (usada junto a `Scenario Outline`)
Tags	`@cualquier-palabra` (ej. `@smoke`, `@regression`) antes de `Feature` o `Scenario`

En español: agregá # language: es como primera línea del archivo para poder usar los equivalentes en español (Característica, Antecedentes, Escenario, Esquema del escenario, Dado, Cuando, Entonces, Y, Pero, Ejemplos) en vez de las palabras en inglés. Sin esa línea, el archivo se interpreta en inglés por defecto (que siempre funciona, con o sin la directiva). Podés mezclar archivos en español e inglés dentro del mismo proyecto (cada .feature declara su propio idioma). Más ejemplos reales de las tres variantes (simple, con Background, con Scenario Outline) en sample-project/features/.

Subcarpetas dentro de features/ están permitidas (se recorren recursivamente) — útil para organizar por módulo o área del proyecto.

3. `run`

Levanta el server HTTP interactivo (http://localhost:{puerto}, configurable en qa-config.json) y, si server.openBrowser es true, intenta abrir el navegador automáticamente (si falla — p. ej. sin entorno gráfico — el servidor sigue disponible igual por URL, solo se avisa por log). Si el puerto configurado ya está en uso (por ejemplo, porque hay otro proyecto de QA corriendo en paralelo en la misma máquina), prueba automáticamente los siguientes puertos hasta encontrar uno libre — nunca hace falta editar qa-config.json a mano solo para poder correr dos sesiones a la vez; el navegador se abre igual, apuntando al puerto real que consiguió. Desde ahí:

Seleccionás qué features correr.
Recorrés cada step, adjuntando evidencia (file picker, drag&drop o Ctrl+V sobre el área de evidencia) y marcando el resultado.
El progreso se autoguarda en .qa-evidence-reporter/session.json en cada acción — se puede cerrar la terminal/navegador y retomar exactamente donde quedó volviendo a correr run.
Al terminar (o en cualquier corte), generás el reporte y lo exportás como .zip desde el panel de "Reporte". Cuando ya no necesitás seguir viendo esa sesión, el botón "Cerrar sesión" (al lado de "Exportar como ZIP") la da por terminada — para empezar una selección nueva sin que el sistema te pida confirmar que descartás progreso (ver "Qué NO hacer" más abajo). No borra evidencia ni reportes ya generados.

El proceso queda corriendo en primer plano hasta que lo interrumpís con Ctrl+C (SIGINT) — cierra el servidor de forma prolija antes de terminar.

4. `report`

Genera el reporte HTML final (reports/index.html + reports/features/*.html) a partir de la última sesión guardada. El reporte es auto-contenido (CSS/JS inline, imágenes de evidencia copiadas junto al HTML) y funciona abriendo index.html directamente con file://, sin necesitar ningún servidor. Desde la UI del runner (o llamando a POST /api/report/generate + GET /api/report/export-zip) también se puede exportar como .zip para compartirlo.

Usarlo para ejecutar un test plan completo

La herramienta no reemplaza un test plan formal (objetivos de negocio, riesgos, cronograma, criterios de entrada/salida siguen siendo una decisión tuya, documentada aparte) — lo que hace es estandarizar la ejecución, evidencia y reporte de un conjunto de casos ya definidos como .feature. Esta es la forma recomendada de usarla para ese fin, y las trampas reales del modelo actual que conviene conocer antes de empezar.

Paso a paso

Definí el alcance como estructura de carpetas/archivos, no solo como tags. La selección de qué correr en run es por archivo .feature completo (todos sus scenarios se incluyen, no hay selección por scenario ni por tag desde la UI todavía). Si tu test plan necesita poder ejecutarse por partes (por ejemplo "solo smoke" o "solo el módulo de pagos"), organizá esa división como archivos/carpetas separados dentro de features/ (parseDirectory es recursivo), no confíes solo en tags para poder cortar el alcance después.
Escribí los .feature cubriendo todo el alcance del plan: usá Background para precondiciones compartidas dentro de un feature, Scenario Outline + Examples para variantes de datos, y tags (@smoke, @regression, @critico, lo que tenga sentido para tu equipo) para clasificar — hoy son informativos (se muestran en el reporte y en el selector) pero no filtran la ejecución.
Configurá qa-config.json antes de arrancar: projectName, team (quiénes ejecutan), y evidence.maxFileSizeMB/evidence.allowedFormats si vas a adjuntar screen recordings pesados o formatos fuera del default.
init (si el proyecto todavía no existe) y ubicá tus .feature en features/.
run, seleccioná los features que forman esta corrida del plan, y recorré cada step adjuntando evidencia real, marcando el resultado y completando notas/descripción de defecto donde corresponda. Si el plan es grande, hacelo en varias sesiones de trabajo — el progreso se autoguarda y run retoma exactamente donde quedaste.
Al completar la corrida (o en cualquier corte que necesites reportar parcialmente), generá el reporte y exportá el .zip inmediatamente — es tu snapshot de esa corrida.
Archivá ese .zip con un nombre que identifique la corrida (fecha, sprint, versión — reports/report-2026-08-10-sprint-14.zip, por ejemplo) ANTES de volver a correr report sobre una sesión nueva (ver el punto 2 de "qué NO hacer" — se sobreescribe).
Compartí el .zip (o el link al reports-static/ si el server sigue corriendo) con tus líderes, y usá los Issues del repo para centralizar el feedback que te den.

Qué NO hacer

No edites los .feature esperando que una sesión ya en curso los "recoja". Al seleccionar features, sus scenarios/steps quedan congelados dentro de session.json en ese momento — editar el archivo fuente después no actualiza la sesión activa. Terminá o descartá la sesión actual (ver punto siguiente) antes de editar y volver a seleccionar.
No vuelvas a pasar por la pantalla de selección "para actualizar" sin pensarlo. Si la sesión tiene progreso registrado (algún resultado marcado, evidencia adjunta, o notas) — esté "en curso" o ya "completada" — run te va a pedir confirmación explícita, porque selecciona de nuevo = descarta todo lo no exportado a un reporte. Una sesión "completada" NO es sinónimo de "ya está a salvo": es justamente el estado normal justo ANTES de generar el reporte, así que puede tener evidencia real que todavía no exportaste. Si no estás seguro, generá y exportá el reporte primero.
No corras dos instancias de run en paralelo sobre el mismo proyecto. Todas comparten el mismo .qa-evidence-reporter/session.json sin bloqueo de archivo — escrituras concurrentes se pueden pisar entre sí. Un server por proyecto a la vez.
No asumas que un reporte anterior queda guardado solo. report escribe siempre sobre la misma carpeta reports/; generar uno nuevo sobreescribe index.html y las páginas de feature. Si necesitás historial entre corridas (por sprint, por release), archivá el .zip exportado antes de la siguiente — la herramienta no versiona reportes por vos.
No adjuntes lo que el qa-config.json no permite (formatos fuera de evidence.allowedFormats, o archivos más grandes que evidence.maxFileSizeMB) esperando que "simplemente funcione" — se rechazan con error (415/413); ajustá la config antes si lo necesitás.
No esperes más trazabilidad de la que hay con Jira/Azure DevOps. Si configurás jira y/o azureDevOps (ver ## qa-config.json), el botón "Adjuntar a Jira"/"Adjuntar a Azure DevOps" del runner sube el .zip del reporte como adjunto al issue/work item que indiques y agrega un comentario con un resumen (feature + scenarios + % aprobado/fallado/ omitido) — pero nada más: no sincroniza estado, y no lee nada de vuelta. Ninguno de los dos comentarios incluye el detalle paso a paso ni la "descripción del defecto" de cada step — eso sigue viviendo solo en la sesión y en el reporte adjunto; si tu proceso necesita ese texto también en el ticket, copialo a mano.
No la uses como el único documento del test plan. Cubre ejecución + evidencia + reporte de casos ya escritos como .feature, no la planificación (objetivos, riesgos, cronograma, criterios de entrada/salida) ni la gestión de casos fuera de Gherkin — eso seguí documentándolo donde ya lo hacías.
No dejes que dos personas ejecuten sobre el mismo server sin coordinarse. Es una sesión compartida en tiempo real: dos personas marcando resultados o navegando steps a la vez sobre el mismo proceso van a pisarse (última acción gana, sin "carriles" por usuario).

Atajos de teclado (runner)

Activos mientras el foco NO esté sobre un campo de texto (notas, descripción de defecto) — ahí se desactivan por completo para no interferir con lo que estés escribiendo.

Tecla	Acción
`P`	Marcar el step actual como Pass
`F`	Marcar el step actual como Fail (requiere descripción de defecto)
`S`	Marcar el step actual como Skip
`N`	Ir al step siguiente
`B`	Ir al step anterior

También: Ctrl+V sobre el área de evidencia sube una imagen del portapapeles, y se puede arrastrar y soltar (drag & drop) uno o más archivos sobre esa misma área. El tema claro/oscuro tiene un toggle propio y se persiste en localStorage.

`qa-config.json`

{
  "$schema": "./node_modules/qa-evidence-reporter/config.schema.json",
  "projectName": "Mi Proyecto QA",
  "team": [],
  "featuresDir": "features",
  "evidenceDir": "evidence",
  "reportsDir": "reports",
  "server": { "port": 3000, "openBrowser": true },
  "evidence": {
    "maxFileSizeMB": 50,
    "allowedFormats": ["png", "jpg", "jpeg", "gif", "mp4", "webm", "pdf"]
  },
  "logging": { "level": "info" },
  "branding": {
    "logoPath": null,
    "primaryColor": null,
    "accentColor": null,
    "highlightColor": null,
    "ctaColor": null
  },
  "jira": {
    "baseUrl": null,
    "email": null
  },
  "reportTemplate": null
}

Todos los campos son opcionales (una config parcial se completa con estos defaults) — el bloque de arriba muestra el default a nivel de esquema, con branding en null (sin branding) y jira en null (sin integración).

qa-evidence-reporter init no usa ese default para branding: escribe siempre el logo y los 4 colores estándar de Quind (primaryColor "#1e3543", accentColor "#00c4e9", highlightColor "#ffb91c", ctaColor "#ff5530", con logoPath: "branding/logo.png"), y copia el archivo del logo dentro del proyecto — todo proyecto QA nuevo se ve igual desde el primer momento, sin configuración manual. El bloque branding con todo en null de arriba sigue siendo válido si armás un qa-config.json a mano (sin init) o si editás el que generó init para sacarle el branding.

Campo	Tipo	Descripción
`projectName`	`string`	Nombre mostrado en el header del runner y del reporte.
`team`	`string[]`	Lista libre de integrantes del equipo (informativo, se muestra en el reporte).
`featuresDir`	`string`	Carpeta (relativa al directorio del proyecto) donde viven los `.feature`.
`evidenceDir`	`string`	Carpeta donde se guardan los archivos de evidencia subidos (organizados por feature/scenario/step).
`reportsDir`	`string`	Carpeta donde `report` escribe el HTML final.
`server.port`	`number`	Puerto HTTP donde escucha `run`.
`server.openBrowser`	`boolean`	Si `run` intenta abrir el navegador automáticamente al arrancar.
`evidence.maxFileSizeMB`	`number`	Tamaño máximo por archivo de evidencia; archivos más grandes se rechazan (`413`).
`evidence.allowedFormats`	`string[]`	Extensiones permitidas (sin el punto); cualquier otra se rechaza (`415`).
`logging.level`	`"debug" \| "info" \| "warn" \| "error"`	Nivel de log interno (diagnóstico, no la salida de usuario de los comandos).
`branding.logoPath`	`string \| null`	Ruta al logo (relativa al proyecto). `init` la deja en `"branding/logo.png"`; `null` = no mostrar ninguno.
`branding.primaryColor`	`string \| null`	Color del header del reporte/runner (hex, ej. `"#1e3543"`). `null` = header neutro de siempre.
`branding.accentColor`	`string \| null`	Color de acento: links, botones, foco. `null` = acento neutro de siempre.
`branding.highlightColor`	`string \| null`	Color de detalle de marca (franja distintiva bajo el header).
`branding.ctaColor`	`string \| null`	Color de una acción destacada puntual (ej. "Exportar como ZIP").
`jira.baseUrl`	`string \| null`	URL del sitio Jira Cloud (ej. `"https://tuempresa.atlassian.net"`, sin `/rest/...`). `null` = integración desactivada.
`jira.email`	`string \| null`	Email de la cuenta Jira Cloud usada para autenticar. No es secreto — el token sí (ver más abajo).
`azureDevOps.organizationUrl`	`string \| null`	URL de la organización de Azure DevOps (ej. `"https://dev.azure.com/tuorganizacion"`). `null` = integración desactivada.
`azureDevOps.project`	`string \| null`	Nombre (o id) del proyecto de Azure DevOps donde viven los work items a publicar.
`reportTemplate`	`string \| null`	Ruta a un template Handlebars custom, o `null` para usar el template embebido (`templates/default`).

init deja los bloques jira/azureDevOps siempre presentes pero desactivados (sus campos en null — JSON no soporta comentarios, así que esta es la única forma de dejarlos "listos" sin arriesgar un archivo inválido), junto a un campo extra _ejemplo en cada uno, puramente documental (no lo lee el validador, no activa nada), que muestra la forma real de sus campos. Para activar cualquiera de las dos integraciones, reemplazá sus null por tus valores reales — _ejemplo podés borrarlo o dejarlo, es inofensivo.

Los colores semánticos de resultado (verde=Pass, rojo=Fail, gris=Skip, ámbar=Pending) nunca se ven afectados por branding — siguen siendo fijos, para no perder la lectura instantánea del estado de cada step.

Integración con Jira Cloud (opcional)

Con jira.baseUrl y jira.email configurados (y la variable de entorno JIRA_API_TOKEN seteada — nunca en qa-config.json, es secreto), el panel de "Reporte" del runner (qa-evidence-reporter run) muestra un botón "Adjuntar a Jira": escribís la clave de un issue (historia, épica, bug — cualquiera, la API de adjuntos de Jira no distingue tipo) y:

sube un .zip del reporte completo como adjunto a ese issue — el mismo que generarías con "Exportar como ZIP" directo, sin bajarlo a mano primero. No se sube solo el index.html: el reporte necesita también las páginas de cada feature (features/*.html), los estilos/JS y la evidencia (capturas/videos) para poder abrirse — sin ese resto, un HTML suelto no muestra nada útil, por eso siempre viaja empaquetado. Si volvés a publicar sobre el mismo issue, el .zip anterior (el que se llame exactamente qa-report.zip) se borra y se reemplaza por el nuevo — no queda acumulando copias.
agrega un comentario al issue con un resumen legible: el nombre de cada feature probada, sus scenarios (nombre + resultado — nunca el detalle paso a paso, eso sigue solo en el .zip), y el % de aprobado/ fallado/omitido de la sesión — calculado sobre SCENARIOS completos (cada uno cuenta 1 vez, con su resultado final: fail > pendiente > omitido > aprobado), la misma base que usa el dashboard del reporte HTML, para que ambos números coincidan siempre. Un scenario con, por ejemplo, 2 steps aprobados y 1 omitido cuenta como 1 scenario omitido — sus steps aprobados no "suman" por separado al total de aprobados.

Solo Jira Cloud (*.atlassian.net) — Jira Server/Data Center no está soportado (ver la sección "Qué NO hacer" para el alcance exacto de lo que sube). Para Azure DevOps, ver ## Integración con Azure DevOps más abajo — es una integración independiente, con su propio bloque de config y su propio botón.

Paso a paso: generar el token y probar la integración

Generá un API token de Atlassian, con la cuenta de Jira que vas a usar para publicar (necesita permiso para agregar adjuntos/comentarios en los issues donde vayas a publicar):
- Entrá a https://id.atlassian.com/manage-profile/security/api-tokens.
- "Create API token" → ponele un nombre que lo identifique (ej. qa-evidence-reporter) → copialo apenas se genera. Atlassian no lo vuelve a mostrar después; si lo perdés, hay que crear uno nuevo y revocar el viejo.
- Atlassian permite (y desde 2025 exige) ponerle una fecha de vencimiento al token — anotala en algún lado del equipo para renovarlo antes de que expire y la integración empiece a fallar con JIRA_AUTHENTICATION_ERROR.
- Anotá también el email de esa cuenta y la URL base de tu sitio (la que usás para entrar a Jira en el navegador, ej. https://tuempresa.atlassian.net, sin /jira ni /rest/... al final) — los vas a necesitar en los pasos siguientes.
Exportá el token como variable de entorno, en la terminal donde vas a trabajar (nunca lo pegues en un archivo, y nunca lo commitees):
```
export JIRA_API_TOKEN="EL_TOKEN_QUE_COPIASTE"
```
Probá las credenciales solas, antes de tocar la herramienta (no hace falta tener un proyecto QA armado todavía):
```
curl -u "tu-email@quind.io:$JIRA_API_TOKEN" \
  https://tuempresa.atlassian.net/rest/api/3/myself
```
- Si devuelve un JSON con tu nombre/cuenta → el email + token son válidos, seguí al paso 4.
- Si devuelve 401/Unauthorized → el token está mal copiado, vencido, o el email no corresponde a ese token — repetí el paso 1.
Configurá el proyecto QA (el que usa init/run, no este repo): en su qa-config.json, agregá el bloque jira. Como referencia, así queda con datos reales de ejemplo — dejalo comentado hasta que lo necesites (JSON no soporta comentarios: al descomentarlo tenés que borrar los // de cada línea, y reemplazar baseUrl/email por los de tu propio sitio, no dejar estos):
```
// "jira": {
//   "baseUrl": "https://vm-qa-quind-team.atlassian.net",
//   "email": "sebastian.alzate@quind.io"
// }
```
Volvé a exportar el token, en la terminal donde vas a correr qa-evidence-reporter run (nunca en el archivo, nunca commiteado — si es la misma terminal del paso 2, con que siga exportada alcanza; si abriste una nueva, repetí el comando):
```
export JIRA_API_TOKEN="EL_TOKEN_QUE_COPIASTE"
```
Probá el flujo completo: qa-evidence-reporter run, seleccioná alguna feature, marcá al menos un step, generá el reporte, y en el panel de "Reporte" escribí la clave de un issue real al que tengas acceso (ej. QA-1) → "Adjuntar a Jira". Si todo salió bien aparece un link "Ver issue en Jira"; si algo falla, el mensaje de error (banner rojo) dice cuál de los 4 casos fue: sin reporte generado todavía, Jira no configurado, el issue no existe (o no tenés acceso), o falló la autenticación.
Confirmá en Jira: abrí el issue por el link que te dio la herramienta (o buscalo a mano) y fijate que qa-report.zip esté en su lista de adjuntos, y que se haya agregado el comentario con el resumen (features, scenarios, porcentajes).

Integración con Azure DevOps (opcional)

Con azureDevOps.organizationUrl y azureDevOps.project configurados (y la variable de entorno AZURE_DEVOPS_PAT seteada — nunca en qa-config.json, es secreto), el panel de "Reporte" del runner (qa-evidence-reporter run) muestra un botón "Adjuntar a Azure DevOps": escribís el ID numérico de un work item (historia, bug, task — cualquiera, la API de adjuntos no distingue tipo) y:

sube un .zip del reporte completo como adjunto a ese work item — mismo criterio que Jira (ver arriba): nunca solo el index.html, y si volvés a publicar sobre el mismo work item, el adjunto anterior llamado exactamente qa-report.zip se borra y se reemplaza por el nuevo.
agrega un comentario al work item con el mismo resumen que Jira (feature + scenarios + % aprobado/fallado/omitido, calculado sobre SCENARIOS completos — ver arriba), aunque acá es HTML simple en vez de un documento ADF (así funciona la API de comentarios de Azure DevOps).

Es una integración independiente de Jira — podés tener las dos activas a la vez (cada una con su propio botón), o solo una, según qué gestor use tu equipo.

Paso a paso: generar el token y probar la integración

Generá un Personal Access Token (PAT), con la cuenta de Azure DevOps que vas a usar para publicar (necesita el scope "Work Items" → Read & Write como mínimo):
- Entrá a tu organización en https://dev.azure.com/ → ícono de usuario (arriba a la derecha) → "Personal access tokens" → "New Token".
- Ponele un nombre que lo identifique (ej. qa-evidence-reporter), elegí una fecha de expiración, y marcá el scope Work Items (Read & Write) — con eso alcanza, no hace falta darle acceso a todo.
- Copialo apenas se genera — Azure DevOps no lo vuelve a mostrar después; si lo perdés, hay que crear uno nuevo y revocar el viejo.
Exportá el PAT como variable de entorno, en la terminal donde vas a trabajar (nunca lo pegues en un archivo, y nunca lo commitees):
```
export AZURE_DEVOPS_PAT="EL_PAT_QUE_COPIASTE"
```
Probá las credenciales solas, antes de tocar la herramienta (no hace falta tener un proyecto QA armado todavía). A diferencia de Jira, un PAT de Azure DevOps autentica con Basic auth de usuario vacío (:PAT):
```
curl -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/tuorganizacion/_apis/projects/tu-proyecto?api-version=7.1"
```
- Si devuelve un JSON con los datos del proyecto → el PAT es válido y tiene acceso a ese proyecto, seguí al paso 4.
- Si devuelve 401/Unauthorized → el PAT está mal copiado, vencido, o le falta el scope "Work Items" — repetí el paso 1.
- Si devuelve 404 → revisá que tuorganizacion/tu-proyecto sean correctos (mayúsculas/espacios incluidos).
Configurá el proyecto QA (el que usa init/run, no este repo): en su qa-config.json, agregá el bloque azureDevOps. Como referencia, así queda con la forma esperada — dejalo comentado hasta que lo necesites (mismo motivo que con jira: JSON no soporta comentarios, así que al descomentarlo hay que borrar los // de cada línea):
```
// "azureDevOps": {
//   "organizationUrl": "https://dev.azure.com/tuorganizacion",
//   "project": "Mi Proyecto"
// }
```
Volvé a exportar el PAT, en la terminal donde vas a correr qa-evidence-reporter run (nunca en el archivo, nunca commiteado — si es la misma terminal del paso 2, con que siga exportada alcanza; si abriste una nueva, repetí el comando):
```
export AZURE_DEVOPS_PAT="EL_PAT_QUE_COPIASTE"
```
Probá el flujo completo: qa-evidence-reporter run, seleccioná alguna feature, marcá al menos un step, generá el reporte, y en el panel de "Reporte" escribí el ID de un work item real al que tengas acceso (ej. 123) → "Adjuntar a Azure DevOps". Si todo salió bien aparece un link "Ver work item en Azure DevOps"; si algo falla, el mensaje de error (banner rojo) dice cuál de los casos fue: sin reporte generado todavía, Azure DevOps no configurado, el work item no existe (o no tenés acceso), o falló la autenticación.
Confirmá en Azure DevOps: abrí el work item por el link que te dio la herramienta (o buscalo a mano) y fijate que qa-report.zip esté en su pestaña de "Attachments", y que se haya agregado el comentario con el resumen (features, scenarios, porcentajes) en "Discussion".

Proyecto de ejemplo (opcional)

No hace falta para usar la herramienta en un proyecto real — es solo material de referencia. sample-project/ (dentro de este repo) contiene un proyecto completo de ejemplo (3 .feature reales, mezclando español e inglés, con tags, Background y Scenario Outline) y sample-project/simulate-session.mjs, un script que ejercita el server real de punta a punta (selección, evidencia real, resultados mixtos, reporte, ZIP) sin necesitar un navegador. Útil como referencia de sintaxis Gherkin o para explorar rápido cómo se ve un reporte ya generado.

Cómo dar feedback

Cualquier hallazgo (bug, algo confuso, una mejora) — abrilo como Issue en el repo para que quede registrado y se pueda priorizar. Si es sobre un reporte HTML generado, adjuntá el .zip exportado (botón "Exportar como ZIP") para poder reproducir exactamente lo que viste.

Arquitectura (resumen)

core/: lógica de negocio pura (parser Gherkin, motor de sesión, almacenamiento de evidencia, generación de reportes, config, logger) — sin conocimiento de HTTP/CLI/UI.
adapters/cli/: los 3 comandos (init/run/report), sobre commander.
adapters/server/: API REST (express) que run levanta para la UI interactiva.
src/ui/: runner web (Preact + Vite), habla con el server solo por fetch.
templates/: templates Handlebars del reporte HTML.

Ver ARCHITECTURE.md para las decisiones técnicas completas, los contratos de cada módulo y el historial detallado de cada fase de construcción.

Name		Name	Last commit message	Last commit date
branding		branding
sample-project		sample-project
src		src
templates/default		templates/default
tests		tests
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
ARCHITECTURE.md		ARCHITECTURE.md
DESIGN.md		DESIGN.md
PRODUCT.md		PRODUCT.md
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Uh oh!

Repository files navigation

qa-evidence-reporter

Instalación

Flujo de uso

1. `init`

2. Escribir tus `.feature`

3. `run`

4. `report`

Usarlo para ejecutar un test plan completo

Paso a paso

Qué NO hacer

Atajos de teclado (runner)

`qa-config.json`

Integración con Jira Cloud (opcional)

Paso a paso: generar el token y probar la integración

Integración con Azure DevOps (opcional)

Paso a paso: generar el token y probar la integración

Proyecto de ejemplo (opcional)

Cómo dar feedback

Arquitectura (resumen)

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

qa-evidence-reporter

Instalación

Flujo de uso

1. init

2. Escribir tus .feature

3. run

4. report

Usarlo para ejecutar un test plan completo

Paso a paso

Qué NO hacer

Atajos de teclado (runner)

qa-config.json

Integración con Jira Cloud (opcional)

Paso a paso: generar el token y probar la integración

Integración con Azure DevOps (opcional)

Paso a paso: generar el token y probar la integración

Proyecto de ejemplo (opcional)

Cómo dar feedback

Arquitectura (resumen)

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

1. `init`

2. Escribir tus `.feature`

3. `run`

4. `report`

`qa-config.json`