UI Selector Repair
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é esperar cuando un cambio de frontend llega al pipeline.
En resumen
- Para qué sirve: cuando un cambio de frontend renombra botones, campos o pantallas, corregir automáticamente las pruebas que los usaban, antes de que empiecen a fallar.
- Cuándo se ejecuta: cuando llega un cambio de código de frontend al pipeline, antes de desplegarlo.
- Qué necesita: el "diff" del cambio (la lista de líneas de código que cambiaron) y el
qa-stack.yamldel proyecto. - Qué deja: las pruebas afectadas corregidas y ejecutadas, más la lista de lo que no se pudo corregir solo, para que lo revise una persona.
- Pasos: 3 — encontrar las pruebas afectadas, corregir sus selectores y ejecutarlas. 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, normalmente desde el pipeline de CI.
Ver Planes para la comparación completa entre plan y playbook.
¿Qué es un selector?
Una prueba automática necesita encontrar en la pantalla el botón o el campo que va a usar. Para eso usa un selector: una "dirección" del elemento, como su identificador o su texto (por ejemplo, data-test="checkout-btn"). Si el developer renombra ese identificador, la prueba ya no encuentra el botón y falla, aunque la aplicación funcione perfecto. Este plan corrige esas direcciones.
1. ¿Qué hace este plan?
Evita que un cambio de diseño rompa las pruebas automáticas. Cuando el equipo de frontend renombra identificadores de la pantalla, el plan lee exactamente qué cambió en el código y actualiza las pruebas que los usaban, sin esperar a que fallen.
Su intención es separar dos tipos de fallo que se confunden fácil: "la aplicación tiene un bug" y "la prueba quedó desactualizada". Este plan se ocupa solo del segundo, y lo hace con la información más confiable que hay: el propio código del cambio. Para eso:
- Busca qué pruebas tocan la parte de la aplicación que cambió.
- Corrige en esas pruebas solo los selectores cuyo reemplazo está claro en el código del cambio. Lo que es ambiguo no lo adivina: lo deja para que lo revise una persona.
- Ejecuta las pruebas que corrigió, para confirmar que funcionan.
Como trabaja leyendo el código del cambio, no necesita que la aplicación esté desplegada para corregir: está pensado para ejecutarse antes del deploy.
2. ¿Cuándo se ejecuta?
| Situación | Ejemplo de negocio |
|---|---|
| Llega al pipeline un cambio de frontend | El equipo de TechStore sube un cambio en el carrito: el botón "Finalizar compra" cambia de identificador |
| Se quiere evitar que las pruebas fallen por un renombre | El líder de QA de TechStore no quiere ver la suite en rojo cada vez que el equipo de diseño reorganiza una pantalla |
Se ejecuta con cada cambio de frontend, sin importar si es grande o chico: no hay un paso previo que decida si vale la pena. Los templates de CI de lippia-neo-ci-bootstrap traen un job ui-selector-repair que lo ejecuta con cada push a develop que modifica archivos de src/components/ o src/pages/.
Importante
- El plan solo corrige selectores. No genera pruebas nuevas para funcionalidades nuevas ni explora la aplicación: para eso está el playbook Frontend UI Change PR.
- Solo corrige lo que el código del cambio deja claro: si un identificador se borró sin reemplazo, o hay más de un candidato posible, lo deja sin tocar y lo informa.
- 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?
El plan se deriva del playbook Frontend UI Change PR, pero se queda solo con la parte de reparar la suite:
| Playbook Frontend UI Change PR | Este plan | |
|---|---|---|
| Quién lo ejecuta | El asistente de IA, conversando con vos | El engine, solo |
| De dónde saca qué cambió | Del ticket y de recorrer la pantalla desplegada | Del código del cambio (el diff) |
| Necesita la app desplegada | Sí, para recorrerla | No, para corregir. Solo la usa al ejecutar las pruebas corregidas |
| Pruebas para lo nuevo | Las genera, si vos decidís que hay algo nuevo | No genera pruebas nuevas |
| Pausas | Dos: decidir si hay algo nuevo y revisar si se reparó de más | Ninguna: lo dudoso queda sin tocar y se informa |
| Reporte | Reporte final con evidencia | No escribe un reporte; el resultado queda en result.json y, en el CI, en un MR con los cambios |
4. Ejemplo guía: "TechStore" renombra el botón de compra
Seguimos con el caso del playbook Frontend UI Change PR. El equipo de TechStore reorganizó el carrito: movió el botón "Finalizar compra" y, de paso, le cambió el identificador de data-test="checkout-btn" a data-test="finish-purchase-btn". Hay 3 pruebas automáticas del checkout que usan el identificador viejo.
4.1 Lo que el plan necesita recibir
| Dato | Qué es | Ejemplo con TechStore |
|---|---|---|
commit_id |
El identificador del commit del cambio. Se usa para nombrar la carpeta donde quedan los resultados | a1b2c3d |
code_diff_path |
La ruta al archivo con el diff del cambio (la salida de git diff) |
diffs/a1b2c3d.diff |
En el CI, el job genera el diff y arma estos datos solo.
4.2 Cómo se dispara
En el CI, el job calcula el diff del push, ejecuta el plan y, si se corrigió algo, abre un MR con las pruebas corregidas:
rules:
- if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "develop"'
changes:
- src/components/**/*
- src/pages/**/*
Para probarlo desde tu computadora:
git diff develop > diffs/a1b2c3d.diff
neo run plans/ui-selector-repair.yaml --workspace . --out result.json \
--data '{"commit_id":"a1b2c3d","code_diff_path":"diffs/a1b2c3d.diff"}'
4.3 Paso a paso
Paso 1 de 3 — Encontrar las pruebas afectadas por el cambio
Skill que se usa: lippia-neo-find-ui-tests-by-code-diff
Qué pasa: lee el diff y saca de ahí qué cambió: archivos, selectores agregados o quitados, rutas, clases y textos visibles. Después busca en la carpeta de pruebas las que usan algo de eso. Solo lee: no ejecuta ni modifica nada.
Con TechStore: encuentra las 3 pruebas del checkout que usan checkout-btn.
Que una prueba coincida no significa que esté rota
Una coincidencia quiere decir "esta prueba toca la parte que cambió". Si ninguna prueba coincide, los pasos siguientes se saltean: no hay nada que corregir.
Paso 2 de 3 — Corregir los selectores
Skill que se usa: lippia-neo-repair-selectors-by-diff
Solo se ejecuta si el Paso 1 encontró pruebas
Qué pasa: en las pruebas que encontró el Paso 1, reemplaza solo los selectores cuyo cambio está claro en el diff ("antes era esto, ahora es esto"). No abre el navegador ni ejecuta nada: es una corrección sobre los archivos.
Lo que no está claro (un identificador que se borró sin reemplazo, o con más de un candidato) no se adivina: queda en una lista de pendientes para que lo revise una persona.
Con TechStore: reemplaza checkout-btn por finish-purchase-btn en las 3 pruebas.
Paso 3 de 3 — Ejecutar las pruebas corregidas
Skill que se usa: lippia-neo-run-and-heal
Solo se ejecuta si el Paso 2 corrigió alguna prueba
Qué pasa: ejecuta solo las pruebas que se corrigieron en el Paso 2, nunca la suite completa, para confirmar que funcionan. Si alguna falla por otro motivo menor, intenta repararla y la vuelve a ejecutar, hasta 2 veces.
Con TechStore: ejecuta las 3 pruebas del checkout con el selector nuevo y confirma que pasan.
4.4 ¿Cómo termina?
| Cómo terminó | Qué significa | Qué se hace |
|---|---|---|
| ✅ Se corrigieron pruebas y pasan | El cambio de frontend ya no rompe la suite | En el CI, revisar y aprobar el MR con las pruebas corregidas |
| ⚠️ Quedaron selectores pendientes | El diff no dejaba claro el reemplazo de algunos selectores | Revisar la lista de pendientes en result.json y corregirlos a mano |
| ➖ Ninguna prueba coincidió con el cambio | El cambio no toca nada que usen las pruebas | Nada: el plan termina sin cambios |
| ❌ Una prueba corregida sigue fallando | El problema no era solo el selector | Revisar si la pantalla cambió de comportamiento, o si es un bug |
En todos estos casos el plan termina en success: el detalle de qué se encontró, qué se corrigió y qué quedó pendiente está en result.json.
5. Problemas comunes (y qué hacer)
| Lo que ves | Por qué puede pasar | Qué hacer |
|---|---|---|
| El plan no encontró ninguna prueba, pero hay pruebas que fallan | Las pruebas usan selectores que no aparecen en el diff (por ejemplo, un texto que cambió en otro archivo) | Revisar esas pruebas a mano, o con el playbook Frontend UI Change PR |
| Muchos selectores quedaron pendientes | El cambio borró elementos o los reemplazó por varios | Es lo esperado: el plan no adivina. Corregirlos a mano |
| El Paso 3 falla al abrir la app | La aplicación no está accesible en la URL del qa-stack.yaml |
Confirmar la URL; las correcciones del Paso 2 igual quedan hechas |
| El diff está vacío | El job no pudo calcular el diff del push | Revisar que el job tenga el historial completo de git (GIT_DEPTH: "0") |
6. Resumen visual del flujo
flowchart TD
A([🎨 Cambio de frontend<br/>ej: TechStore renombra el botón de compra]) --> B["<b>Paso 1</b> — Encontrar las pruebas<br/>afectadas por el diff"]
B --> C{¿Encontró<br/>pruebas?}
C -->|No| X([➖ Nada que corregir])
C -->|Sí| D["<b>Paso 2</b> — Corregir los selectores<br/>con reemplazo claro"]
D --> E{¿Corrigió<br/>alguna?}
E -->|No| P([⚠️ Solo pendientes para revisar])
E -->|Sí| F["<b>Paso 3</b> — Ejecutar las pruebas corregidas"]
F --> G([✅ Pruebas al día + lista de pendientes])
Plan original
El archivo del plan es plans/ui-selector-repair.yaml, en el repositorio del engine (crowdar-engine-mvp). La referencia del formato está en Anatomía de un plan.