Guía de "Frontend UI Change PR"
Esta guía explica qué es un playbook de control de calidad (QA) y qué hace exactamente el playbook
1. ¿Qué es un "playbook"?
Que es un Playbook? Es por ejemplo la checklist que sigue un piloto antes de despegar: no improvisa cada vez, sigue una secuencia probada de pasos. Un playbook es esa misma idea aplicada a probar una aplicación: una receta escrita que le indica al modelo de IA, paso a paso, qué hacer usando diferentes elementos/herramientas llamadas "Skills".
¿Qué es una "Skill"?
Una skill es la herramienta puntual que ejecuta cada paso del Playbook. Interactúa con el playbook — el asistente se encarga de usar la herramienta correcta en cada momento.
2. ¿Qué hace el playbook "Frontend UI Change PR"?
Es el playbook que usás cuando un desarrollador ya modificó una pantalla y subió ese cambio como Pull Request (PR), y necesitás confirmar que no rompió nada antes de aprobarlo.
Pensalo así: un Pull Request (PR) es un cambio de código que un desarrollador ya armó, pero que todavía no llegó a los usuarios reales — está guardado aparte, esperando que alguien lo revise y diga "está bien, se puede publicar". Ese "alguien" es este playbook.
A diferencia de otros playbooks, acá no se arranca de una historia de usuario — se arranca de una pantalla que ya existe, construida. El asistente recorre esa pantalla nueva como lo haría un usuario real, y hace tres cosas con lo que encuentra:
- Si algo dejó de funcionar solo porque cambió un identificador interno (el botón sigue estando y haciendo lo mismo, pero por dentro cambió de "nombre"), lo repara él solo.
- Si encuentra algo que directamente no existía antes (un campo nuevo, un paso nuevo), te pregunta si hace falta cubrirlo con una prueba nueva.
- Si el comportamiento cambió de verdad (no es un tema de nombres, la pantalla no hace lo que el ticket dice que debería hacer), no lo esconde: lo deja anotado como un problema real.
Este playbook lo dispara un Pull Request ya subido — el punto de partida es el cambio que el desarrollador ya hizo, no una decisión de QA de revisar algo.
3. ¿Cuándo tengo que usar este playbook?
Usalo cuando estés frente a alguna de estas situaciones:
| Situación | Ejemplo de negocio |
|---|---|
| Un Pull Request modifica componentes, formularios o botones de una pantalla que ya existía | El equipo de desarrollo de TechStore subió un PR que mueve el botón "Finalizar compra" arriba de todo y agrega un campo nuevo para aplicar un cupón de descuento en el carrito |
| Las pruebas que ya existían empiezan a fallar después del cambio | Las pruebas automáticas del carrito de TechStore, que venían pasando bien, ahora fallan — hay que confirmar si es porque algo se rompió de verdad o porque solo cambió un identificador interno |
| Se necesita evidencia de QA antes de aprobar el merge | El líder técnico de TechStore no quiere aprobar el PR "de palabra" — quiere un reporte que confirme que el carrito sigue funcionando |
| El PR agrega una interacción nueva que no existía | El campo de cupón de descuento es una funcionalidad nueva dentro del carrito y necesita una prueba propia, no solo revisar que lo viejo siga andando |
¡IMPORTANTE!
- Si el cambio parte de una historia de usuario en blanco, sin pantalla previa construida, este no es el playbook indicado — ahí se usa "Feature New End to End".
- Este playbook necesita que el proyecto ya tenga el archivo con el stack tecnológico (qa-stack.yaml) armado de antes. Si es la primera vez que se hace QA automatizado sobre esta aplicación, primero hay que correr "New Project Bootstrap".
- Necesita que el cambio esté desplegado en un ambiente de pruebas (staging), accesible por una URL — no alcanza con el código sin desplegar.
4. Ejemplo guía: "TechStore", una tienda online con carrito de compras
Vamos a seguir el mismo caso de negocio de ejemplo que usan otras guías: TechStore, una tienda online de electrónica con las partes típicas de cualquier tienda que reconocerías por haber comprado online alguna vez: login, catálogo, carrito de compras y checkout.
Supongamos este escenario: el equipo de desarrollo de TechStore terminó de programar dos cambios en el carrito y los subió juntos como el Pull Request #142:
- Movieron el botón "Finalizar compra" desde el final de la página hacia arriba de todo.
- Agregaron un campo nuevo para aplicar un cupón de descuento.
El PR ya está desplegado en un ambiente de pruebas, esperando revisión antes de aprobar el merge a producción. Ese es exactamente el escenario para el que se usa este playbook.
A lo largo de los pasos siguientes vamos a ver qué le responderías al asistente en cada momento, usando este PR de TechStore como ejemplo.
5. Antes de arrancar: lo que necesitás tener a mano
No hace falta saber programar, pero sí tener a mano estos datos:
| Dato | Ejemplo con TechStore |
|---|---|
| El número o nombre del Pull Request | PR #142 |
| El ticket o la descripción de los cambios | Ticket TS-US-14 (o, si no hay ticket, la lista escrita: "botón movido" + "campo de cupón nuevo") |
| La URL del ambiente donde está desplegado el PR | https://techstore-staging.com/preview/142 |
| La suite de pruebas existente para esa pantalla (si la hay) | tests/carrito/ (si no existe todavía, no es un problema — el playbook lo contempla) |
¿No sabés de dónde sacar alguno de estos datos? Es normal, no hace falta ser una persona técnica para conseguirlos: - El número del PR te lo pasa el desarrollador cuando avisa "ya está listo para probar", o lo ves vos misma/o entrando al repositorio (GitLab o GitHub) → sección "Merge requests" / "Pull requests" → aparece listado con un número al lado del título. - El ticket normalmente te lo pasa el desarrollador como un link (Jira o Azure DevOps). Si no hay ticket, no pasa nada: alcanza con que el desarrollador te cuente en dos o tres frases qué cambió. - La URL de staging casi siempre queda escrita como comentario automático dentro del mismo Pull Request ("Preview deployed at..."), o te la pasa el desarrollador directamente. - La suite existente: esto no hace falta que lo sepas vos — si no tenés idea, escribí "no existe aún" y el asistente lo revisa solo en la configuración del proyecto.
6. Cómo arrancar
Antes de pedirle el primer paso, contale al asistente los datos del PR, todo junto en un solo mensaje. Siguiendo el ejemplo de TechStore:
Te brindo la información de los cambios implementados en el frontend, quiero
que solo lo tomes como contexto, no quiero que realices ninguna acción adicional.
Datos del trabajo:
- PR: PR #142
- Ticket / historia: TS-US-14
- URL del ambiente con el PR: https://techstore-staging.com/preview/142
- Suite existente: tests/carrito/
Cambios UI declarados por el dev:
- Botón "Finalizar compra" movido arriba de todo
- Campo nuevo para aplicar un cupón de descuento
El asistente va a usar ese contexto durante todos los pasos siguientes — no hace falta repetirlo cada vez.
7. Paso a paso
Paso 1 — "Leer el ticket o la descripción del cambio"
Trigger: /qa-read-user-story
Qué pasa: el asistente lee el ticket (o la descripción manual, si no hay ticket) y extrae qué cambió, en qué URL probarlo, y con qué credenciales. Si algo no coincide con lo que el desarrollador contó en el PR, te lo señala antes de seguir.
Cómo saber si salió bien: el resumen que te muestra el asistente coincide con lo que vos ya sabías del PR — si menciona algo que no esperabas, es momento de aclararlo con el desarrollador antes de continuar.
Paso 2 — "Recorrer la pantalla nueva como lo haría un usuario real"
Trigger: /qa-scripted-execution
Qué pasa: el asistente entra realmente a TechStore, navega el carrito, hace clic en el botón "Finalizar compra" desde su nueva posición, prueba el campo de cupón — y va anotando todo lo que encuentra, clasificado en tres categorías:
| Categoría | Qué significa | Qué hace el asistente con eso |
|---|---|---|
| Selector roto | El botón sigue funcionando igual para el usuario, pero cambió su identificador interno | Lo repara en el Paso 3, sin necesitar tu intervención |
| Flujo nuevo | Una interacción que directamente no existía antes (el campo de cupón) | Se te pregunta en el Checkpoint 1 si hace falta cubrirlo con una prueba nueva |
| Comportamiento inesperado | La pantalla no responde como el ticket dice que debería | Queda documentado como un defecto real |
Cómo saber si salió bien: queda un reporte con capturas de pantalla de cada componente tocado, y los hallazgos ya clasificados en una de las tres categorías de arriba.
⏸ Checkpoint 1 — "¿Hay algo nuevo que cubrir?"
| Resultado de la exploración | Qué significa | Qué le respondés al asistente |
|---|---|---|
| Se encontró al menos un flujo nuevo (en TechStore: el cupón) | Hace falta generar una prueba específica para eso | "Hay flows nuevos: 'Aplicar cupón de descuento'. Continuar con healing y generar tests nuevos." |
| Solo se encontraron selectores rotos, nada nuevo | Alcanza con reparar lo que ya existía | "Solo selectores rotos, no hay flows nuevos. Continuar solo con healing." |
Este es el único momento de todo el playbook donde el asistente se detiene a esperar tu decisión antes de seguir — por eso conviene revisar bien el reporte del Paso 2 antes de responder.
Paso 3 — "Reparar la suite existente"
Trigger: /qa-run-and-heal
Qué pasa: el asistente corre las pruebas que ya existían del carrito contra la pantalla nueva. Lo que falla solo porque cambió un identificador interno (por ejemplo, el botón "Finalizar compra" ahora tiene otro nombre técnico por haberse movido), lo corrige. Lo que falla porque el comportamiento cambió de verdad, no lo fuerza a pasar — lo deja marcado como un problema real.
Qué se puede reparar y qué no:
| Se puede reparar así | Nunca se repara así — se marca como defecto |
|---|---|
| Actualizar el identificador interno de un botón o campo que cambió de nombre | Cambiar lo que se esperaba que pasara para que coincida con un comportamiento incorrecto |
| Actualizar una URL o ruta de navegación que el PR modificó | Marcar una prueba como "saltear" sin dejar por escrito el motivo |
| Ajustar el tiempo de espera si la pantalla nueva tarda más en cargar | Borrar la verificación en lugar de corregir el identificador |
Cómo saber si salió bien: queda un resumen con cuántas pruebas fallaban al empezar, cuántas quedaron aprobadas al final, cuántos intentos hicieron falta (de un máximo de 3), y cuántos identificadores se corrigieron.
⏸ Checkpoint 2 — "¿Se reparó de más?"
Corregir muchas cosas no es un problema de las pruebas — es una señal de que el cambio real del PR es más grande de lo que el desarrollador declaró.
| Señal de alerta | Qué implica |
|---|---|
| Más de 5 correcciones en un mismo archivo | El componente fue rehecho, no retocado |
| 30% o más de la suite necesitó corrección | El alcance real es mayor al declarado |
| Se corrigieron flujos que el ticket no menciona | El PR tocó más pantallas de las anunciadas |
| Hicieron falta más de 2 intentos y seguía sin aprobar | La pantalla nueva puede tener inconsistencias propias |
Si ves alguna señal de alerta, respondele al asistente: "Hay reparación excesiva en el módulo de carrito — [detalle de lo que te llamó la atención]. Pausar y consultar con el dev si el alcance del PR es correcto."
Si el número de correcciones te parece razonable para el cambio descripto: "Reparación dentro de lo esperado. Continuar."
Paso 4 — "Generar pruebas para lo nuevo" (solo si en el Checkpoint 1 dijiste que había algo nuevo)
Trigger: /qa-generate-test-suite
Qué pasa: el asistente escribe pruebas puntuales para el cupón de descuento, usando los identificadores reales que capturó en el Paso 2 — sin tocar ni pisar las pruebas del carrito que ya existían.
Cómo saber si salió bien: aparece una carpeta de pruebas nueva, separada de la suite original, con al menos una prueba por cada flujo nuevo identificado.
Paso 5 — "Correr todo de nuevo hasta que quede aprobado" (solo si corrió el Paso 4)
Trigger: /qa-run-and-heal
Qué pasa: el asistente corre la suite reparada del Paso 3 junto con las pruebas nuevas del Paso 4, todas juntas, hasta que todo quede en verde. Si algo sigue fallando de verdad, queda documentado como un defecto de la aplicación — no se esconde.
Paso 6 — "Reporte final con evidencia"
Trigger: /qa-write-test-report
Qué pasa: el asistente junta todo lo hecho en los pasos anteriores y escribe un reporte final con capturas de pantalla, y un detalle línea por línea de cada identificador que se corrigió (de qué nombre a cuál), listo para adjuntar al PR como evidencia.
Cómo saber si salió bien: el reporte incluye la suite base aprobada, el detalle de cada corrección, las pruebas nuevas (si las hubo), y queda guardado con fecha y hora sin pisar reportes anteriores.
8. ¿Qué me queda al finalizar todos los pasos?
| Qué obtenés | Para qué te sirve |
|---|---|
| Un reporte de la exploración con capturas de pantalla | Evidencia de que alguien (el asistente) realmente probó la pantalla nueva del PR |
| La suite existente reparada y aprobada | Confirmación de que el cambio no rompió el carrito |
| El detalle de cada identificador corregido, de dónde a dónde | Trazabilidad para que el revisor del PR confirme que cada cambio de selector es correcto |
| Pruebas nuevas para lo que el PR agregó (si hubo algo nuevo) | Cobertura del cupón de descuento, lista para correrse en el futuro |
| Un reporte final con fecha y hora | El documento que adjuntás al PR como respaldo para aprobar — o frenar — el merge |
A partir de acá, el equipo de TechStore puede aprobar el merge del PR #142 con evidencia real de que el carrito sigue funcionando y que el cupón nuevo quedó probado.
9. Problemas comunes (y qué hacer)
| Lo que ves | Por qué puede pasar | Qué hacer |
|---|---|---|
| La exploración del Paso 2 no encuentra nada para hacer clic | El ambiente de staging del PR no terminó de desplegarse | Confirmar con el equipo técnico que la URL está activa antes de reintentar |
| La reparación del Paso 3 supera los 3 intentos sin converger | El componente fue rehecho desde cero, no retocado | Pausar y consultar con el desarrollador el alcance real del PR |
| Las pruebas nuevas del Paso 4 usan identificadores incorrectos | La exploración del Paso 2 no capturó todos los elementos del flujo nuevo | Repetir el Paso 2 con foco explícito en los elementos de ese flujo |
| La suite base vuelve a fallar en el Paso 5 (estaba verde en el Paso 3) | Las pruebas nuevas dejaron datos que interfieren con las demás | Agregar una limpieza de estado entre pruebas y repetir el Paso 5 |
| El reporte final no muestra ninguna corrección | Es el mejor escenario posible: el PR no rompió ningún identificador existente | No es un error — seguir normalmente |
10. Resumen visual del flujo
Pull Request de frontend subido (ej: PR #142 en TechStore — botón movido + cupón nuevo)
│
▼
Paso 1 — Leer el ticket o la descripción
│
▼
Paso 2 — Recorrer la pantalla nueva → selectores rotos / flujos nuevos / inesperado
│
▼
⏸ Checkpoint 1 — ¿Hay algo nuevo?
│
┌───────┴────────────────────┐
│ Sí, hay flujo nuevo │ No, solo selectores rotos
▼ ▼
Paso 3 — Reparar la suite Paso 3 — Reparar la suite
existente existente
│ │
▼ ▼
⏸ Checkpoint 2 — ¿Se reparó de más?
│ │
▼ ▼
Paso 4 — Generar pruebas Paso 6 — Reporte final
para lo nuevo con evidencia
│
▼
Paso 5 — Correr todo de nuevo hasta aprobar
│
▼
Paso 6 — Reporte final con evidencia
│
▼
PR listo para aprobar (o frenar) el merge, con evidencia real