Flujo E2E de kbspec

Cómo se crean y se corren las pruebas E2E de un requerimiento: desde la app sin preparar hasta la revisión antes del Pull Request, con quién hace cada paso y dónde queda cada cosa. El detalle de cada pieza está en Las pruebas de fábrica.

Quién hace cada paso

Persona. El desarrollador: decide, aprueba y graba.
Agente. La IA en el chat: escribe y termina las pruebas.
kbspec. Corre solo: separa, arma, valida y revisa.

Dónde queda cada cosa

Ficha de la app. Cómo se entra y cómo se llega. aplicaciones/<APP>/arquitectura.md
Expediente. El 02, el brief, las grabaciones, la evidencia y el 07. requerimientos/<año>/<TICKET>/
Proyecto E2E. El kit y las pruebas. <app>/pruebas-e2e/

Comandos de la persona

kb pruebas validar antes de escribir
kb pruebas grabar para recorrer la app
kb pruebas --solo e2e para correrlas
kb pruebas revisar antes del PR
kb pruebas pipeline para staging y la CI

0. La base de la app

Una vez por app. Después la reusan todos los requerimientos.

0.1Preparar el proyecto E2Ekbspec

Siembra la carpeta de pruebas de la app con Playwright en la versión que kbspec probó, la configuración y el kit: login, entrada, navegación y controles. Instala con npm ci y elige el navegador que lanza en la máquina, primero el Edge instalado.
Ventana de terminal
```
kb pruebas preparar --app <APP>
```
- Proyecto E2E · pruebas-e2e/
- e2e/kb.config.json, generado desde la ficha
0.2Describir cómo se entra y cómo se llegaPersona

La ficha de la app dice cómo es el login —el de la app, el de la organización (Entra ID, AD FS, lo que abre «Mis aplicaciones»), o los dos si la app se configura con uno u otro—, cómo se llega a la app (un portal, el módulo, el perfil, el iframe con token, una pestaña nueva), qué usuarios de prueba hay y cómo se llega a cada pantalla. Los pasos del inicio de sesión de la organización se declaran una vez, en su propia ficha, para todas las apps. Lo más corto es grabar el recorrido una vez. Si no, el agente lo arma con la persona mirando la app (/kb-e2e-descubrir), partiendo de un borrador del mapa que sale del código.
Ventana de terminal
```
kb pruebas grabar --app <APP>
kb pruebas mapa --app <APP>    # el borrador del mapa
```
- Ficha · Autenticación de las pruebas
- Entrada a la app
- Usuarios de prueba
- Mapa de navegación
0.3Poner las clavesPersona

Una variable por usuario de prueba en el .env del proyecto E2E —y en los secretos del pipeline, una por ambiente—. La ficha nombra la variable; el valor nunca va en la ficha ni en el código. Con el inicio de sesión de la organización, las cuentas de prueba van sin MFA.
Ventana de terminal
```
KB_CLAVE_QA_ADMIN=…
KB_CLAVE_QA_CONSULTA=…
```
- Proyecto E2E · .env (fuera de git)
0.4Levantar el ambiente localPersona

Cada vez que se trabaja, no una vez por app. Las dependencias de la ficha —el backend y los APIs— arrancan juntas y después la app, cada una cuando responde su ruta de salud (/health): la misma URL que espera Playwright. Queda arriba mientras se trabaja, y la validación, el grabador y cada corrida la reutilizan en vez de levantarla y bajarla. Lo que se consume de un ambiente publicado (seguridad, catálogos) se verifica, no se levanta. Ctrl+C lo baja; un agente usa --fondo y --bajar.
Ventana de terminal
```
kb pruebas levantar --app <APP>
kb pruebas levantar --app <APP> --fondo    # vuelve cuando todo responde (un agente, un script)
kb pruebas levantar --app <APP> --bajar
```
- e2e/.kb/levantar/ — el log de cada proceso
0.5Validar la basekbspec

Prueba en orden y corta en el primer rojo: el navegador y el certificado, el login de cada usuario, la entrada de cada usuario y cada pantalla del mapa con cada usuario que la ve.
Ventana de terminal
```
kb pruebas validar --app <APP>
```
- e2e/.kb/validacion.md
- el árbol real de cada pantalla en e2e/.kb/humo/
¿Dice LISTO?

Síse sigue con la fase 1.

Nose hace el arreglo que trae el primer rojo. Si es el login, la entrada o una pantalla y no se sabe el camino, propone grabarlo. kb pruebas demo dice si el problema es la máquina o la app.

1. Qué se prueba

Por requerimiento. Sale de los criterios de aceptación.

1.1Los criterios de aceptaciónPersonaAgente

El 02 dice qué tiene que pasar, en Dado / Cuando / Entonces, y qué rol hace cada cosa en su tabla de actores.
- Expediente · 02-requerimiento.md
1.2Las condicioneskbspec

De cada criterio salen las condiciones a probar: el camino feliz, la falla, el rol que no puede, los obligatorios y el ejemplo de cada regla. Cada una con su usuario de prueba y el resultado esperado copiado del 02.
Ventana de terminal
```
kb pruebas condiciones
```
1.3Las pruebas de otros requerimientoskbspecPersona

kbspec lista las E2E de otros requerimientos que nombran las pantallas de este y las deja en el 03 para decidir cada una con la persona: mantener (si falla, es una regresión), actualizar (este requerimiento la reescribe) o retirar. Sin esa decisión no se tocan.
Ventana de terminal
```
kb pruebas afectadas --escribir
```
- Expediente · 03 · «Pruebas existentes afectadas»
1.4El brief de pruebaskbspecPersona

kbspec lo siembra con una fila por condición. La persona borra lo que sobra, suma sus propias pruebas con su clave (por ejemplo RF-01/segmento-personal) y anota en qué pantalla pasa cada una.
Ventana de terminal
```
kb pruebas brief
```
- Expediente · pruebas/a-construir-<TICKET>.md
¿La persona lo aprobó?

Síescribe «aprobado pruebas» en el chat, o kb aprobar pruebas. Lo aprobado es exactamente lo que se construye: una prueba por fila.

Nono se escribe ninguna prueba. Se puede grabar igual: las pruebas se arman cuando se apruebe.

2. Grabar

Opcional y recomendado. Las veces que haga falta.

2.1Recorrer la app con el grabadorPersona

Se abre el grabador de Playwright en el portal o en el login, con el certificado, el idioma y la zona de la ficha. Se entra como siempre, se llega a la app y se recorren las pantallas del requerimiento. Lo que el 02 dice que se ve se marca con «Assert text» o «Assert visibility». Lo corre la persona en su terminal, porque alguien tiene que usar el navegador.
Ventana de terminal
```
kb pruebas grabar --app <APP>
kb pruebas grabar --app <APP> --para RF-02/feliz    # dice con qué usuario y qué hacer
```
2.2Separar lo grabadokbspec

Al cerrar el navegador, cada parte va a su lugar. Lo que la ficha ya tenía se compara: lo distinto se dice y no se pisa.
- El logina la ficha del portal, o de la app si se entra directo
- La entradaa la ficha de la app: módulo y perfil de cada usuario, el iframe, la señal de que cargó
- Las pantallasal mapa de navegación, con quién las ve según el 02
- El recorridoal expediente, con el usuario y el perfil de quien grabó
La clave que se tipeó no se guarda en ningún lado.
- Ficha · Autenticación, Entrada, Mapa
- Expediente · pruebas/grabaciones/<id>.json
2.3Varias grabacioneskbspec
- Se graba con el perfil que ve un menú y con el que no, la falla, o lo que faltó.
- Todas las grabaciones vigentes se usan. Cada prueba toma la hecha para ella; si no hay, la de su rol; si no, la que mejor coincide.
- Una igual a otra, con el mismo perfil y el mismo recorrido, reemplaza a la anterior aunque se hayan tipeado otros datos.
Ventana de terminal
```
kb pruebas grabar --lista
kb pruebas grabar --descartar <id>
kb pruebas grabar --rehacer    # arma todo de nuevo sin grabar
```

3. Armar las pruebas

Con el brief aprobado. Una prueba por fila.

3.1Una prueba por fila del briefkbspec

Se arma sola después de grabar, o con kb pruebas grabar --rehacer. Cada parte sale de su fuente:
Del criterio · 02 y brief
- el usuario y su rol
- los pasos: Dado y Cuando
- los datos que el criterio dice
- el resultado esperado
De la grabación de su rol
- por dónde se llega
- qué controles hay
- los localizadores que se ejecutaron
Lo que se grabó y el criterio no pide queda como comentario, no como afirmación. Si en el mismo control se grabó otro texto que el que promete el 02, se afirma el del 02.
- Proyecto E2E · e2e/<TICKET>/<condición>.spec.ts (borrador)
- Expediente · pruebas/grabacion-<TICKET>.md
Una fila sin grabación: kbspec propone el comando exacto, kb pruebas grabar --app <APP> --para <condición>.

Sin grabar nada: el agente las escribe con el CLI de Playwright desde el plan, una por condición (kb pruebas sesion --escenario 1.1).
Cómo se ve un borrador
```
test.use({ alias: "qa_admin" });                  // del brief: quién
// Dado que el administrador está en Nuevo cliente
await irA(app, "Nuevo cliente");                  // de la grabación: cómo se llega
// Cuando registra un cliente con su nombre y su segmento
await app.getByRole("textbox", { name: "Nombre" }).fill(nombre);   // control grabado
await app.getByLabel("Segmento").selectOption("Pyme");
await app.getByRole("button", { name: "Guardar" }).click();
// Entonces se ve «Cliente creado» y el cliente aparece en la lista
await expect(app.getByRole("status")).toContainText("Cliente creado");   // texto del 02
await expect(app.getByTestId("tabla-clientes")).toContainText(nombre);
```
3.2Terminar los borradoresAgente

Con /kb-e2e-disenar, afirma el resultado del 02 donde quedó un pendiente, saca la marca // kbspec:borrador y deja cada prueba limpia y estable. Si no sabe cómo se llega o qué control es, no lo adivina: propone grabar esa parte.
Ventana de terminal
```
npm run check
npx playwright test e2e/<TICKET> --repeat-each=3
```

4. Correr y revisar

Hasta que el veredicto deje abrir el Pull Request.

4.1Correr las pruebaskbspec

Corre el preflight, el login y la entrada de cada usuario, y cada prueba con su usuario. Guarda el reporte y las capturas como evidencia, y llena el 07 solo. El detalle está más abajo, en «Dentro de una corrida».
Ventana de terminal
```
kb pruebas --solo e2e
```
- Expediente · evidencias/E04-…
- 07-resultados-pruebas.md
4.2Leer cada rojokbspec

Distingue por qué falló cada prueba y dice qué hacer con cada una. Las cinco salidas posibles están más abajo, en «Cuando algo falla».
4.3Revisar antes del Pull Requestkbspec

Da un veredicto: PASA, CON RESERVAS o FALLA. Revisa que cada fila del brief tenga su prueba, que no queden borradores, que cada prueba afirme el resultado del 02 y que la evidencia esté en verde.
Ventana de terminal
```
kb pruebas revisar
```
¿PASA?

Síse abre el Pull Request con la evidencia.

Nodice qué falta: una prueba, un borrador sin terminar o una evidencia en rojo, y propone grabar lo que no tiene prueba.

5. Staging, preproducción y el pipeline

Las pruebas se escribieron y se corrieron en local. Corren iguales contra un ambiente publicado: la URL y el certificado de cada ambiente salen de la ficha; las cuentas y las claves, de sus secretos.

5.1Probar la base contra stagingPersona

Con el ambiente declarado en «Ambientes» de la ficha, la misma validación de la fase 0, contra staging: el login de cada usuario y cada pantalla.
Ventana de terminal
```
kb pruebas validar --ambiente staging
```
5.2Generar el pipelinekbspec

El de Azure DevOps y el de GitHub Actions: eligen el ambiente, el filtro (las pruebas de un requerimiento), el navegador y con qué se entra; mapean un secreto por usuario de prueba y publican el JUnit, el reporte y las trazas de lo que falló.
Ventana de terminal
```
kb pruebas pipeline --app <APP>
```
- pruebas-e2e/azure-pipelines-e2e.yml
- .github/workflows/e2e-<app>.yml
5.3El pipeline corre las mismas pruebaskbspec

Sin nadie mirando y sin kbspec: el proyecto E2E corre solo, con reintentos y de a un worker. La app no se levanta —ya está publicada—, y el inicio de sesión de la organización entra con la cuenta de prueba de cada usuario.

Dentro de una corrida

Lo que pasa cuando corre kb pruebas --solo e2e, en orden.

Preflight
El navegador, la red, el certificado y la pantalla de login. Si falla, no corre nada más: una causa, no cuarenta pruebas rojas.
Un setup por usuario
Inicia sesión —en la app, en su portal o en el inicio de sesión de la organización; si la app tiene su login y el SSO, en el que esté habilitado—, recorre la entrada y prueba si alcanza con reabrir la página que contiene la app. Guarda la sesión fuera de git.
Cada prueba
Su usuario, la app ya abierta (el iframe o la página, con los avisos cerrados), irA por la receta del mapa, los pasos y la afirmación del 02.
Reporte
HTML para el revisor, JSON para kbspec y una captura por caso.
kbspec
La evidencia E04, el 07 al día y qué hacer con cada rojo.

Cuando algo falla

kbspec separa las fallas en cinco tipos, porque cada una se arregla en otro lugar.

AmbienteNo corrió o no entra

El navegador, el certificado, la clave o el SSO.

kb pruebas validar dice el primer rojo y su arreglo. La prueba no se toca.

No llegóNo llegó o no encontró el control

Un paso del mapa que no aparece, un clic que vence el tiempo.

kbspec propone kb pruebas grabar --app <APP> --para <condición>. No se adivina otro localizador.

HallazgoLa app no cumple el 02

El texto o el valor que promete el criterio no aparece.

Lo esperado no se cambia. /kb-e2e-sanar lo confirma y va a Hallazgos del 07.

PendienteFalta una prueba

Una fila del brief sin prueba, o un borrador sin terminar.

kb pruebas revisar lo marca y propone grabar lo que falta.

RegresiónFalla una prueba de otro requerimiento

Pasaba antes del cambio y ahora no: el cambio tocó algo que esa prueba cuida.

Si el cambio lo pide a propósito, se declara en el 03 (kb pruebas afectadas --escribir: «actualizar» o «retirar») y se reescribe; si no, se corrige el código, no la prueba.

El registro de las E2E

Cada corrida, cada arranque del ambiente y lo que el agente hace con las pruebas quedan en un registro de la máquina (~/.kb/log/e2e.jsonl). Con él se ve dónde se va el tiempo y por qué fallan, sin depender de lo que alguien recuerde:

el arranque: cuánto tardó cada servidor en responder, o por qué no respondió, con la memoria libre de la máquina antes y después;
cada corrida: la configuración con que corrió (el kit y si su config está editado, Playwright, Node, el navegador, el filtro, los topes), cuánto tardó, cómo terminó, las fallas por clase y si es un reproceso de lo mismo;
el agente: las pruebas que corrió por su cuenta, las que escribió y lo que la compuerta le negó.

kb pruebas registro                          # el resumen
kb pruebas registro --exportar e2e.jsonl     # las líneas, sin secretos, para mandarlas

No lleva secretos ni contraseñas, ni el nombre de los usuarios (van contados) ni el de la máquina. KB_SIN_REGISTRO_E2E=1 lo apaga.