qwen3-6-lora/data/raw/sanitized/skills/web-ui-test/SKILL.md

name, description, effort, argument-hint

name	description	effort	argument-hint
web-ui-test	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".	medium	[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:

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:

  npm install -g @playwright/cli playwright
  

• Si BROWSER_OK=0 → instalar el navegador por defecto sin dependencias de sistema:

  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:

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).

# 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ó:

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":

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).