Saltar a contenido

QA Bug Coverage

Esta guía explica qué hace el engine de NEO cuando ejecuta este plan. La idea es que puedas leerla, entender qué pasa en cada paso sin que nadie intervenga, y saber qué información tiene que traer el bug para que el trabajo salga bien.

En resumen

  • Para qué sirve: cuando un bug pasa a QA, confirmar que realmente ocurre y dejar una prueba automática que lo captura, lista para que el developer la use mientras lo arregla.
  • Cuándo se ejecuta: cuando se pide cobertura para un bug, en texto libre (Modelo 2: el engine elige este plan) o desde el pipeline de CI.
  • Qué necesita: la referencia al bug (un archivo, un ticket de Jira / Azure DevOps o el texto del reporte), el qa-stack.yaml del proyecto y la aplicación accesible.
  • Qué deja: la evidencia de que el bug se reproduce, una prueba automática en rojo que lo captura (más los casos que faltaban cubrir) y un reporte de lo generado.
  • Pasos: 6 — leer el bug, buscar las pruebas que ya existen, revisar qué falta cubrir, reproducir el bug, generar las pruebas y reportar. Sin pausas.
¿Qué es un plan? (si es la primera vez que ves uno)

Un plan es una receta que ejecuta una máquina en lugar de una persona. Igual que un playbook, encadena varias skills en un orden fijo. La diferencia es que el playbook lo sigue el asistente de IA junto a vos, con pausas para que decidas; el plan lo ejecuta el engine de NEO solo, de punta a punta.

Ver Planes para la comparación completa entre plan y playbook.


1. ¿Qué hace este plan?

Es la primera mitad del ciclo de un bug: deja el bug confirmado y "atrapado" en una prueba automática, antes de que el developer lo arregle. La segunda mitad, después del arreglo, la hace el plan QA Bug Fix Verification.

Su intención es que ningún bug se arregle "a ciegas": antes de tocar el código, tiene que existir una prueba que falle por culpa del bug. Así, cuando el developer lo arregle, esa misma prueba va a pasar a verde y va a demostrar que el arreglo funciona. Para eso, el plan:

  1. Lee el reporte del bug y, si menciona una historia de usuario, también la historia.
  2. Busca si ya hay pruebas automáticas que cubran esa parte de la aplicación.
  3. Revisa qué escenarios de la historia o del bug quedan sin cubrir.
  4. Recorre la aplicación real para confirmar que el bug de verdad ocurre.
  5. Si ocurre, genera la prueba que lo captura, más las pruebas de los escenarios que faltaban.
  6. Escribe un reporte con todo lo que generó.

El plan no arregla el bug ni verifica ningún arreglo: termina con la prueba en rojo, lista para el developer.


2. ¿Cuándo se ejecuta?

Situación Ejemplo de negocio
Un bug pasa a QA y hay que confirmarlo y cubrirlo con una prueba El equipo de TechStore mueve a QA el bug del stock: el carrito deja agregar más unidades de las disponibles
Alguien pide cobertura para un bug en lenguaje natural "El bug TS-BUG-31 ya está en QA, armá la cobertura"

Se puede disparar de dos formas:

  • Modelo 2 — Híbrido adaptativo: alguien escribe el pedido en texto libre (neo run --input "..."), el engine lo clasifica y elige este plan. Ver Modelos de orquestación en el engine.
  • Desde el CI: los templates de lippia-neo-ci-bootstrap traen un job qa-bug-coverage que ejecuta este plan cuando el pipeline se lanza con la variable NEO_PLAN=increase_bug_coverage.

Importante

  • El reporte del bug tiene que describir cómo reproducirlo (pasos, resultado esperado y resultado obtenido). Si no se puede reproducir, el plan se detiene sin generar nada.
  • Si el bug está en Jira o Azure DevOps, el proyecto tiene que tener configurado ese MCP en qa-stack.yaml (ver Configurar los MCP).
  • La aplicación tiene que estar desplegada y accesible: el Paso 4 la recorre en vivo.
  • Si el proyecto todavía no tiene qa-stack.yaml, primero hay que ejecutar el playbook de puesta en marcha del proyecto.

3. ¿En qué se diferencia del playbook?

Este plan hace, sin nadie del otro lado, la primera mitad del playbook Bug Fix Cycle:

Playbook Bug Fix Cycle Este plan
Quién lo ejecuta El asistente de IA, conversando con vos El engine, solo
Alcance El ciclo completo: reproducir, crear la prueba, esperar el arreglo, verificarlo y reportar Solo hasta la prueba en rojo. La verificación del arreglo es otro plan: QA Bug Fix Verification
Pruebas existentes No las busca Busca primero las que ya cubren la funcionalidad y revisa qué escenarios faltan
Qué genera La prueba del bug La prueba del bug más las pruebas de los escenarios que faltaban cubrir
Pausas Confirmar que la prueba falla y esperar el arreglo Ninguna: si el bug no se reproduce, se detiene solo

4. Ejemplo guía: "TechStore" y el carrito que no controla el stock

Seguimos con el mismo caso que en el playbook Bug Fix Cycle. Un cliente de TechStore reporta:

"Intenté comprar 5 unidades de un mouse que en la web decía que solo quedaban 2 disponibles, y el sistema me dejó agregarlas igual al carrito sin avisarme nada."

La regla de negocio de la historia TS-US-08 dice que "el sistema debe mostrar un mensaje de error si el cliente intenta agregar más unidades de las que hay en stock". El equipo carga el bug como TS-BUG-31 y lo pasa a QA.

4.1 Lo que el plan necesita recibir

Dato Obligatorio Qué es Ejemplo con TechStore
description Sí La referencia al bug: la ruta a un archivo, la URL de un ticket de Jira o Azure DevOps, o directamente el texto del reporte https://techstore.atlassian.net/browse/TS-BUG-31
identifier No El identificador del bug, si no se puede deducir del reporte TS-BUG-31
credentials No Credenciales de prueba para entrar a la aplicación, si no están en el reporte Usuario y contraseña de prueba de staging

En el Modelo 2 estos datos los extrae el engine del pedido en texto libre. Si falta el obligatorio, no ejecuta nada y escala a una persona.

4.2 Cómo se dispara

Con el Modelo 2, desde la terminal o un script:

neo run --input "el bug https://techstore.atlassian.net/browse/TS-BUG-31 ya está en QA, armá la cobertura" \
  --plans-dir plans --workspace .

O directamente, eligiendo el plan:

neo run plans/qa-bug-coverage.yaml --workspace . \
  --data '{"description":"https://techstore.atlassian.net/browse/TS-BUG-31"}'

4.3 Paso a paso

Paso 1 de 6 — Leer el bug (y su historia, si la menciona)

Skills que se usan: lippia-neo-read-bug-report y, si corresponde, lippia-neo-read-user-story

Qué pasa: lee el reporte del bug (del archivo, del ticket o del texto) y extrae lo esencial: cómo reproducirlo, qué debería pasar, qué pasa en realidad, la severidad y el ambiente. Si el bug menciona una historia de usuario, también la lee, para tener sus criterios de aceptación reales.

Con TechStore: lee TS-BUG-31, detecta que se relaciona con TS-US-08 y trae la regla del stock.


Paso 2 de 6 — Buscar las pruebas que ya existen

Skill que se usa: lippia-neo-find-existing-tests

Qué pasa: busca en la carpeta de pruebas del proyecto las que ya cubren esa funcionalidad (por el identificador de la historia, sus criterios de aceptación o sus funcionalidades clave).

Con TechStore: encuentra las pruebas del carrito que ya existían, por ejemplo "agregar un producto al carrito".


Paso 3 de 6 — Revisar qué falta cubrir

Skill que se usa: lippia-neo-review-test-coverage

Qué pasa: compara las pruebas encontradas con los escenarios que describen la historia y el bug, y arma la lista de los escenarios que no tienen ninguna prueba.

Con TechStore: detecta que ninguna prueba valida qué pasa al superar el stock disponible.


Paso 4 de 6 — Reproducir el bug en la aplicación

Skill que se usa: lippia-neo-reproduce-bug

Qué pasa: abre un navegador y sigue los pasos del reporte en la aplicación real, para confirmar si el bug realmente ocurre. Guarda la evidencia: capturas de pantalla, errores y los selectores reales de la pantalla. Si no lo logra al primer intento, prueba algunas variantes.

Con TechStore: intenta agregar 5 mouses con stock 2 y confirma que el carrito los acepta sin mostrar ningún error.

Punto de corte: si el bug no se reproduce, el plan se detiene

Si el bug no se reproduce, el plan se detiene acá (stopped) y no genera nada: no tiene sentido escribir una prueba para un bug que no existe en el ambiente. El resultado queda documentado, con el motivo, para revisarlo.

Hoy siempre se intenta reproducir

Este paso se ejecuta aunque el Paso 2 haya encontrado pruebas que ya cubren el bug. Está previsto que, en una próxima versión, el plan ejecute esas pruebas en lugar de reproducir el bug a mano cuando ya existe cobertura.


Paso 5 de 6 — Generar las pruebas que faltan

Skill que se usa: lippia-neo-generate-test-suite

Qué pasa: genera, en el framework del proyecto, dos tipos de prueba:

  • La prueba del bug: reproduce el bug confirmado en el Paso 4. Hoy falla (está en rojo), y va a pasar a verde cuando el developer lo arregle. Se genera siempre que el bug se reprodujo.
  • Las pruebas de los escenarios faltantes: las que el Paso 3 marcó como sin cobertura.

Las pruebas nuevas se guardan junto a las que ya existían para ese módulo.


Paso 6 de 6 — Reporte de lo generado

Skill que se usa: lippia-neo-write-generation-report

Qué pasa: escribe un reporte con las pruebas que se generaron, las que ya existían y la evidencia de la reproducción del bug.

Qué queda: el reporte en la carpeta de reportes del proyecto, listo para que el developer arranque el arreglo.


4.4 ¿Cómo termina?

Cómo terminó Estado del plan Qué significa Qué se hace
✅ El bug se reprodujo y se generaron las pruebas success Hay una prueba en rojo que captura el bug El developer arregla el bug; después se ejecuta QA Bug Fix Verification
⏹ El bug no se reprodujo stopped No se generó nada Revisar el motivo en result.json: puede ser un ambiente distinto, datos de prueba o un bug ya corregido
❌ Una skill devolvió algo mal formado, o algo se rompió failed / error Falla del paso, no de la aplicación Revisar el log y result.json

Que la prueba del bug falle es lo esperado

Al terminar este plan, la prueba del bug tiene que estar en rojo: eso demuestra que captura el bug. Si pasara en verde, no estaría probando el problema reportado.


5. Problemas comunes (y qué hacer)

Lo que ves Por qué puede pasar Qué hacer
El plan termina stopped en el Paso 4 El bug no se reproduce en ese ambiente, el reporte no tiene pasos claros, o el bug ya fue corregido Completar los pasos de reproducción en el reporte y confirmar el ambiente, y volver a ejecutar
En el Modelo 2, el engine escala a una persona El pedido era ambiguo o no traía la referencia al bug Reformular el pedido con el link o el ID del bug, o ejecutar el plan directo con neo run plans/qa-bug-coverage.yaml
El Paso 1 no puede leer el ticket El MCP de Jira o Azure DevOps no está configurado, o faltan las credenciales Ver Configurar los MCP
El Paso 2 no encuentra pruebas aunque existen El bug no menciona la historia, y la búsqueda queda reducida al identificador del bug Mencionar la historia (por ejemplo TS-US-08) en el reporte del bug
No se generó ninguna prueba de escenarios faltantes El Paso 3 no encontró escenarios sin cubrir Es correcto: solo se genera la prueba del bug

6. Resumen visual del flujo

flowchart TD
    A([🐞 Bug en QA<br/>ej: TechStore, stock del carrito]) --> B["<b>Paso 1</b> — Leer el bug<br/>(y su historia)"]
    B --> C["<b>Paso 2</b> — Buscar las pruebas<br/>que ya existen"]
    C --> D["<b>Paso 3</b> — Revisar qué falta cubrir"]
    D --> E["<b>Paso 4</b> — Reproducir el bug<br/>en la app"]
    E --> F{¿Se reprodujo?}
    F -->|No| X([⏹ stopped: no se genera nada])
    F -->|Sí| G["<b>Paso 5</b> — Generar la prueba del bug<br/>y las que faltaban"]
    G --> H["<b>Paso 6</b> — Reporte de lo generado"]
    H --> I([🔴 Prueba en rojo, lista para el developer])
    I -.->|después del arreglo| J([QA Bug Fix Verification])

Plan original

El archivo del plan es plans/qa-bug-coverage.yaml, en el repositorio del engine (crowdar-engine-mvp). La referencia del formato está en Anatomía de un plan.