Configurar las pruebas E2E

Las E2E se escriben con Playwright, en un proyecto propio de cada aplicación (pruebas-e2e/, separado del código de la app y de sus versiones). Esta página es la base, que se arma una vez por aplicación; el recorrido de un requerimiento está en El flujo E2E, paso a paso.

Antes de escribir una prueba, la base se valida. Casi todas las E2E que fallan «por la prueba» fallaban por el ambiente: el navegador, el certificado, el login, una pantalla que no se sabía cómo alcanzar.

Lo que necesita la máquina

	Versión	Nota
Node.js	20+ (22 recomendado)	Con Volta, cada proyecto usa el suyo: la app puede ser Node 16 y Playwright, 22
Playwright	1.63.0	No se instala a mano: lo fija el `package.json` del proyecto E2E
Navegador	Edge o Chrome instalado	Si no hay, el Chromium que baja Playwright
La app	corriendo y alcanzable	En local o en el ambiente donde se prueba

1. Preparar el proyecto E2E

kb pruebas preparar --app OPERACIONES

Siembra pruebas-e2e/ con Playwright en la versión probada, la configuración y el kit —login, entrada a la app, navegación, controles de PrimeNG, Material y Kendo—, instala con npm ci y elige el navegador que funciona en la máquina, primero el Edge instalado. Si falta algo que no puede instalar (Node, permisos, un proxy), lo pide con el comando exacto.

La carpeta la declara la ficha («Dónde viven las pruebas»): kb pruebas rutas dice cuál es y si hay pruebas escritas fuera de ahí.

2. Decir cómo se entra y cómo se llega

Va en la ficha de la aplicación y lo usan todas las pruebas de todos los requerimientos. Lo más corto es grabarlo una vez:

kb pruebas grabar --app OPERACIONES

Abre el grabador de Playwright; recorrés la app desde el login hasta una pantalla y kbspec separa lo que es de la app —el login, la entrada (portal, módulo, perfil, iframe con token), la navegación— y lo escribe en la ficha:

Sección de la ficha	Qué dice
Autenticación de las pruebas	El tipo de login (`formulario`, `formulario-pais`, `sso`, `token-url`, `windows`, `api`) y sus pasos. Un login por API en dos pedidos —el login y después, con su token, el que deja la cookie de la sesión— lleva una fila `luego`
Entrada a la app	Lo que pasa entre el login y la primera pantalla, si la app se abre desde otra
Usuarios de prueba	Un alias por cuenta, con sus roles y módulos, y el nombre de la variable de su clave
Mapa de navegación	Cómo se llega a cada pantalla desde el home, por los menús, como el usuario
Ambientes	La URL de local, staging, preproducción; qué hacer con el certificado

Sin grabar, /kb-e2e-descubrir lo arma con la persona mirando la app, y kb pruebas mapa --app OPERACIONES propone un borrador del mapa leyendo las rutas y los menús del código. Lo que significa cada fila: kb ficha guia autenticación.

El inicio de sesión de la organización (Entra ID, AD FS, «Mis aplicaciones») se declara una vez, en su propia ficha (aplicaciones/SSO/), y cada app lo nombra.

3. Poner las claves

Una variable por usuario de prueba en el .env del proyecto E2E (fuera de git) y, para el pipeline, en sus secretos, una por ambiente:

KB_CLAVE_QA_ADMIN=…
KB_CLAVE_QA_CONSULTA=…

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; si tienen MFA, kb pruebas login --asistido deja entrar a la persona una vez y guarda la sesión (no sirve para el pipeline).

4. Comprobar el ambiente

En este orden. Cada uno corta en el primer problema y dice el arreglo.

kb pruebas ambiente --app OPERACIONES     # esta máquina: Node, navegador, proxy, si la app responde
kb pruebas login --verificar              # el login de cada usuario de prueba, uno por uno
kb pruebas validar --app OPERACIONES      # la base entera, de punta a punta

kb pruebas validar prueba, en orden: la ficha, Node, 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. Deja el árbol real de cada pantalla en e2e/.kb/humo/ y el resultado en e2e/.kb/validacion.md. Hasta que no dice LISTO, no se escribe una prueba.

¿El problema es la máquina o la app?

kb pruebas demo

Corre lo mismo contra una app de prueba que trae kbspec. Si la demo pasa y tu app no, el problema está en la app o en su ficha; si la demo tampoco pasa, en la máquina.

En otro ambiente:

kb pruebas validar --app OPERACIONES --ambiente staging

Cuando algo falla

Síntoma	Qué mirar
`node` en rojo o «Playwright pide 22»	`volta install node@22`, o `kb pruebas preparar` lo hace si Volta está
No abre el navegador	`kb pruebas ambiente`: dice cuál encontró. En una red con proxy, el `.env` del proyecto E2E lleva `HTTPS_PROXY`
Error de certificado	En la fila del ambiente: `ignorar` (local, autofirmado) o `confiar` (la CA de la organización, con `NODE_EXTRA_CA_CERTS`)
El login falla para un usuario	`kb pruebas login --verificar`: la variable de su clave, el dominio o el país del alias
No llega a una pantalla	La fila del mapa de navegación: el menú cambió o el usuario no la ve. `kb pruebas grabar` la vuelve a grabar
Una E2E falla y no se sabe por qué	`/kb-e2e-sanar`: una falla, tres intentos, sin tocar lo esperado, y decide si es la prueba, el ambiente o la app

En el pipeline

kb pruebas pipeline --app OPERACIONES --azure      # o --github

Genera el pipeline que corre las mismas pruebas contra un ambiente publicado, con las claves en los secretos y el disparo que elijas (--disparo manual|noche|despliegue).

Si la app ya tenía pruebas de antes

Un equipo que ya probaba con Playwright suele tener un documento aparte con cómo se entra y cómo se levanta (arquitectura-e2e.md) y una configuración propia en el código (playwright.<algo>.config.ts, tests/playwright/). El kit no lee ninguno de los dos: arma su configuración solo desde la ficha. kb instalar y kb apps actualizar avisan cuando encuentran una base así, y la migración va en tres pasos:

kb pruebas migrar --app OPERACIONES            # qué sabe lo viejo y a qué sección de la ficha va
kb pruebas preparar --app OPERACIONES          # el kit nuevo, con lo que ya dice la ficha
kb pruebas validar --app OPERACIONES           # hasta LISTO
kb pruebas migrar --app OPERACIONES --aplicar  # retira el documento viejo y lista lo del código

--aplicar no retira nada mientras a la ficha le falte algo que solo sabía el documento o la base nueva no esté en LISTO. El documento sale de la documentación con git rm (recuperable hasta el commit). El código no lo toca: dice qué sacar —la configuración y las pruebas viejas, las sesiones guardadas, el script del package.json— para hacerlo en la rama de un ticket.