180 lines
7.9 KiB
Markdown
180 lines
7.9 KiB
Markdown
---
|
|
name: web-ui-test
|
|
description: >-
|
|
Prueba interfaces de aplicaciones web (navegación, interacción, capturas, errores de consola) usando
|
|
un navegador headless vía Playwright CLI — pensado para correr desde un tunnel remoto de VS Code sin
|
|
GUI. Instala Playwright y su navegador automáticamente si no están presentes. Triggers: "prueba esta
|
|
interfaz", "prueba la web app", "test this UI", "revisa la interfaz", "haz un smoke test", "prueba el
|
|
flujo de login/registro/checkout", "captura screenshots de la app".
|
|
effort: medium
|
|
argument-hint: "[URL a probar, o descripción del flujo a validar]"
|
|
---
|
|
|
|
# web-ui-test — Probar interfaces web con Playwright headless
|
|
|
|
Prueba interfaces de aplicaciones web navegando, interactuando y capturando evidencia con un navegador
|
|
**headless** vía `@playwright/cli`. Diseñada para correr desde un tunnel remoto de VS Code (sin display
|
|
local) — nunca intenta abrir un navegador con GUI.
|
|
|
|
Skill global, autosuficiente: no depende de ningún plugin instalado (por ejemplo `c3po`), solo de
|
|
`npm`/`npx` disponibles en el PATH.
|
|
|
|
## 1. Preflight — verificar/instalar Playwright de forma global
|
|
|
|
Ejecuta primero, siempre:
|
|
|
|
```bash
|
|
npm ls -g --depth=0 2>/dev/null | grep -q "@playwright/cli" && echo CLI_OK=1 || echo CLI_OK=0
|
|
npm ls -g --depth=0 2>/dev/null | grep -qw "playwright" && echo PW_OK=1 || echo PW_OK=0
|
|
ls ~/.cache/ms-playwright 2>/dev/null | grep -qi chromium && echo BROWSER_OK=1 || echo BROWSER_OK=0
|
|
```
|
|
|
|
- Si `CLI_OK=0` o `PW_OK=0` → instalar de forma global:
|
|
```bash
|
|
npm install -g @playwright/cli playwright
|
|
```
|
|
- Si `BROWSER_OK=0` → instalar el navegador **por defecto sin dependencias de sistema**:
|
|
```bash
|
|
playwright install chromium
|
|
```
|
|
- Si todo ya está OK (`CLI_OK=1`, `PW_OK=1`, `BROWSER_OK=1`) → **saltar este paso por completo** y pasar
|
|
directo a la sección 3.
|
|
|
|
**Importante**: `@playwright/cli` usa por defecto el canal `chrome` (Google Chrome real, no instalado
|
|
aquí), no el Chromium que acabas de instalar con `playwright install chromium`. Por eso **todo comando
|
|
que abra un navegador debe incluir `--browser chromium` explícitamente** (ver sección 3) — si lo omites,
|
|
falla con `Chromium distribution 'chrome' is not found at /opt/google/chrome/chrome` aunque la
|
|
instalación haya sido exitosa.
|
|
|
|
### Fallback automático (solo si falla, nunca por defecto)
|
|
|
|
Si al abrir una sesión (sección 3) el error indica librerías de sistema faltantes (mensajes tipo
|
|
"missing libraries", "host system is missing dependencies"), reintenta automáticamente, sin preguntar:
|
|
|
|
```bash
|
|
playwright install --with-deps chromium
|
|
# si falla por permisos:
|
|
sudo npx playwright install-deps chromium
|
|
```
|
|
|
|
Luego repite la operación que había fallado. Este camino solo se dispara ante ese error concreto — no lo
|
|
ejecutes de forma preventiva ni la primera vez que instalas el navegador.
|
|
|
|
## 2. Reglas headless (no negociable)
|
|
|
|
- **Nunca** pases `--headed` ni cambies `PWDEBUG`. Este entorno es un tunnel remoto sin display: todo
|
|
corre headless, siempre.
|
|
- Usa sesiones nombradas (`-s=<slug>`) en kebab-case para trazabilidad y para poder limpiar sesiones
|
|
huérfanas de corridas anteriores.
|
|
|
|
## 3. Ciclo de vida de sesión — abrir → interactuar → cerrar
|
|
|
|
Toda tarea sigue el patrón **abrir → interactuar → cerrar**. El cierre es obligatorio, incluso si algo
|
|
falló antes (equivalente a un `finally`).
|
|
|
|
```bash
|
|
# Abrir — SIEMPRE con --browser chromium (ver nota en sección 1)
|
|
npx @playwright/cli -s=$SESSION open "$URL" --browser chromium
|
|
|
|
# Interactuar (snapshot → actuar → re-snapshot)
|
|
npx @playwright/cli -s=$SESSION snapshot
|
|
npx @playwright/cli -s=$SESSION click e15
|
|
npx @playwright/cli -s=$SESSION snapshot
|
|
|
|
# Cerrar (SIEMPRE, incluso si algo anterior falló)
|
|
npx @playwright/cli -s=$SESSION close
|
|
```
|
|
|
|
### Comandos disponibles
|
|
|
|
- **Navegación**: `open <url> --browser chromium`, `goto <url>`, `go-back`, `go-forward`, `reload`
|
|
- **Inspección**: `snapshot` (árbol de accesibilidad con refs `e15`, `e21`...), `screenshot [--full-page] --filename ...`, `pdf --filename ...`
|
|
- **Interacción**: `click <ref>`, `fill <ref> "texto"`, `type "texto"`, `select <ref> "valor"`, `check/uncheck <ref>`, `upload /ruta/archivo`
|
|
- **Teclado/mouse**: `press <tecla>`, `hover <ref>`, `drag <ref-origen> <ref-destino>`
|
|
- **Pestañas**: `tab-list`, `tab-new <url> --browser chromium`, `tab-select <n>`, `tab-close <n>`
|
|
- **Estado de auth**: `state-save <archivo.json>`, `state-load <archivo.json>`
|
|
- **Diagnóstico**: `console error`, `network`, `eval "() => document.readyState"`
|
|
- **Gestión de sesiones**: `list`, `close`, `close-all`, `kill-all`
|
|
|
|
## 4. Verificación de carga de página
|
|
|
|
Antes de interactuar con el contenido, confirma que la página cargó:
|
|
|
|
```bash
|
|
npx @playwright/cli -s=$SESSION eval "() => document.readyState"
|
|
```
|
|
|
|
- `"complete"` → continuar
|
|
- `"loading"` / `"interactive"` → esperar ~2s y reintentar (máx. 3 chequeos, sin `sleep` arbitrario más
|
|
allá de esa espera corta)
|
|
|
|
## 5. Secuencia estándar de captura
|
|
|
|
Cuando la tarea es "revisar/probar esta página":
|
|
|
|
```bash
|
|
mkdir -p .local/screenshots
|
|
|
|
npx @playwright/cli -s=$SESSION open "$URL" --browser chromium
|
|
npx @playwright/cli -s=$SESSION eval "() => document.readyState"
|
|
npx @playwright/cli -s=$SESSION screenshot --filename .local/screenshots/$SESSION-viewport.png
|
|
npx @playwright/cli -s=$SESSION screenshot --full-page --filename .local/screenshots/$SESSION-full.png
|
|
npx @playwright/cli -s=$SESSION snapshot --filename .local/screenshots/$SESSION-snapshot.md
|
|
npx @playwright/cli -s=$SESSION console error
|
|
npx @playwright/cli -s=$SESSION close
|
|
```
|
|
|
|
**Artefactos siempre a disco** en `.local/screenshots/` (relativo al directorio del proyecto actual).
|
|
Nunca vuelques el snapshot completo, HTML crudo, o el contenido de las capturas en el chat — solo reporta
|
|
las rutas y un resumen.
|
|
|
|
## 6. Flujos interactivos (probar un flujo, no solo una página)
|
|
|
|
Cuando el usuario pide validar un flujo (login, checkout, registro, etc.):
|
|
|
|
1. `snapshot` para obtener refs frescos.
|
|
2. Actuar (`click`/`fill`/`select`/`check`) sobre esos refs.
|
|
3. **Re-snapshot después de cualquier acción que cambie el DOM** — los refs quedan obsoletos tras
|
|
mutaciones.
|
|
4. Si un elemento esperado no aparece tras 2 reintentos con snapshot fresco, repórtalo como fallo del
|
|
paso en vez de seguir a ciegas.
|
|
5. Captura screenshot en cada momento relevante del flujo (no solo al final).
|
|
|
|
## 7. App local vs URL remota
|
|
|
|
- Si el usuario pide probar "la app" sin dar URL y el proyecto tiene un servidor de desarrollo definible
|
|
(`package.json` con script `dev`/`start`, etc.), levanta ese servidor primero y espera a que responda
|
|
antes de abrir la sesión de Playwright.
|
|
- Si el usuario da una URL explícita, úsala directamente sin intentar levantar nada.
|
|
|
|
## 8. Formato de reporte final
|
|
|
|
Resumen breve, no el contenido crudo:
|
|
|
|
```
|
|
URL probada: ...
|
|
Sesión: ...
|
|
Acciones realizadas: ...
|
|
Artefactos: .local/screenshots/...-viewport.png, .../...-full.png, .../...-snapshot.md
|
|
Errores de consola: {cantidad, o "ninguno"}
|
|
Hallazgos: {bugs de UX/funcionalidad si los hay}
|
|
Estado de la sesión: cerrada / falló el cierre (requiere kill-all)
|
|
```
|
|
|
|
## 9. Limpieza y recuperación
|
|
|
|
- Cierra la sesión siempre, incluso si algo falló antes.
|
|
- Si el cierre mismo falla, ejecuta `npx @playwright/cli kill-all` como recuperación.
|
|
- Si hay sospecha de sesiones huérfanas de una corrida anterior, revisa con `npx @playwright/cli list`
|
|
antes de abrir una nueva con el mismo nombre.
|
|
|
|
## Qué NO hacer
|
|
|
|
- No pases `--headed` ni intentes abrir una GUI: este entorno no tiene display.
|
|
- No vuelques snapshots de DOM, HTML o contenido de screenshots en el texto de respuesta — guarda a
|
|
disco y reporta la ruta.
|
|
- No dejes una sesión abierta al terminar, ni siquiera cuando algo falló.
|
|
- No interactúes con refs sin un snapshot fresco después de cambios en el DOM.
|
|
- No instales dependencias de sistema (`--with-deps` / `sudo apt`) de forma preventiva — solo como
|
|
fallback automático ante un error concreto de librerías faltantes (ver sección 1).
|