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.yamldel 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:
- Lee el reporte del bug y, si menciona una historia de usuario, también la historia.
- Busca si ya hay pruebas automáticas que cubran esa parte de la aplicación.
- Revisa qué escenarios de la historia o del bug quedan sin cubrir.
- Recorre la aplicación real para confirmar que el bug de verdad ocurre.
- Si ocurre, genera la prueba que lo captura, más las pruebas de los escenarios que faltaban.
- 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-bootstraptraen un jobqa-bug-coverageque ejecuta este plan cuando el pipeline se lanza con la variableNEO_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.