# Skill global: probar interfaces web con Playwright

## Contexto

El usuario trabaja siempre desde una sesión remota de VS Code (tunnel), sin display/GUI local. Necesita
una forma de que Claude pueda **probar interfaces de aplicaciones web** (navegar, interactuar, verificar
visualmente, detectar errores de consola) sin depender de un navegador con interfaz gráfica.

Investigación realizada (read-only):
- `~/.claude/skills/` solo tiene 3 skills globales hoy: `aleleba-pr`, `background-orchestrator`,
  `docmost-context`. Todas siguen el mismo formato: `SKILL.md` con frontmatter
  (`name`, `description`, `effort`, `argument-hint`) y cuerpo en Markdown.
- No hay `playwright` ni `@playwright/cli` instalados (ni global ni cache `~/.cache/ms-playwright`),
  ni binarios `chromium`/`google-chrome` en el sistema.
- No hay ningún MCP server de Playwright/Chrome DevTools configurado.
- El plugin `c3po` (ya instalado en este entorno) trae un agente `browser.md` que usa
  `npx @playwright/cli` (headless por defecto, sesiones nombradas, artefactos a disco) — es un patrón ya
  probado en esta máquina, pero la nueva skill **no debe depender del plugin c3po** para que funcione en
  cualquier proyecto/entorno donde se invoque como skill global.
- `npm config get prefix` apunta a un directorio de nvm en el home del usuario (`~/.nvm/versions/node/...`),
  así que `npm install -g` **no necesita sudo**. La instalación del navegador vía
  `npx @playwright/cli install-browser` tampoco. Solo `playwright install --with-deps` (deps de SO vía apt)
  podría requerir sudo — se trata como fallback, no como paso por defecto.

## Objetivo de la skill

Crear `~/.claude/skills/web-ui-test/SKILL.md`, una skill **global** que:
1. Verifica si `@playwright/cli` (y su navegador Chromium) ya están instalados; si faltan, los instala
   de forma global de manera automática (sin pedir permiso adicional más allá del prompt normal de Bash);
   si ya están instalados, salta ese paso.
2. Usa el navegador **siempre en modo headless** (nunca `--headed`) porque el entorno es un tunnel remoto
   sin display.
3. Dirige un flujo estándar de prueba de interfaz: abrir sesión → snapshot/interactuar → capturar
   screenshots + snapshot de accesibilidad + errores de consola → cerrar sesión (siempre, incluso si algo
   falla).
4. Reporta resultados de forma concisa (rutas de artefactos + hallazgos), sin volcar contenido crudo
   (HTML/snapshot completo) al chat.

## Archivo a crear

`~/.claude/skills/web-ui-test/SKILL.md`

### Frontmatter
```yaml
---
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]"
---
```

### Cuerpo (secciones)

**1. Preflight — verificar/instalar Playwright de forma global (idempotente, se salta si ya está listo)**
```bash
# ¿@playwright/cli y playwright globales disponibles?
npm ls -g --depth=0 2>/dev/null | grep -q "@playwright/cli" && CLI_OK=1 || CLI_OK=0
npm ls -g --depth=0 2>/dev/null | grep -qw "playwright" && PW_OK=1 || PW_OK=0

# ¿Navegador chromium ya descargado?
ls ~/.cache/ms-playwright 2>/dev/null | grep -qi chromium && BROWSER_OK=1 || BROWSER_OK=0
```
- Si `CLI_OK=0` o `PW_OK=0` → `npm install -g @playwright/cli playwright` (instalación global con `-g`;
  no requiere sudo en este entorno porque el prefix de npm es un directorio de nvm en el home del usuario).
- Si `BROWSER_OK=0` → por defecto, `playwright install chromium` (usando el binario global instalado en
  el paso anterior, sin `--with-deps`: solo descarga el binario de Chromium, sin tocar paquetes del
  sistema operativo ni requerir sudo).
  - **Fallback automático (no por defecto)**: si al abrir una sesión con `@playwright/cli` el error indica
    librerías de sistema faltantes (ej. "missing libraries"/"host system is missing dependencies"),
    reintentar automáticamente, sin preguntar, con `playwright install --with-deps chromium` (o
    `sudo npx playwright install-deps chromium` si el anterior falla por permisos) y luego repetir la
    operación que falló. Este camino solo se dispara ante ese error concreto, nunca de forma preventiva.
- Si todo ya está OK (`CLI_OK=1`, `PW_OK=1`, `BROWSER_OK=1`) → saltar directo al paso 2, sin ejecutar nada
  de instalación.

**2. Reglas headless (no negociable)**
- Nunca pasar `--headed` ni cambiar `PWDEBUG`. Este entorno no tiene display; todo corre headless.
- Usar sesiones nombradas (`-s=<slug>`) en kebab-case para trazabilidad.

**3. Ciclo de vida de sesión — abrir → interactuar → cerrar**
Documentar (embebido, sin depender de archivos externos del plugin c3po) los comandos base de
`npx @playwright/cli`, tomados del reference ya validado en este entorno
(`~/.claude/plugins/cache/crew/c3po/0.4.1/agents/refs/playwright-cli.md`):
- `open <url>`, `goto`, `snapshot`, `click <ref>`, `fill <ref> "texto"`, `select`, `check/uncheck`,
  `press`, `hover`, `screenshot [--full-page] --filename ...`, `console error`, `network`,
  `eval "() => document.readyState"`, `close`, `close-all`, `kill-all`.
- Patrón obligatorio: cerrar la sesión siempre al final, incluso si falló algún paso intermedio
  (equivalente a un `finally`).

**4. Verificación de carga de página**
Antes de interactuar, comprobar `document.readyState === "complete"` (máx. 3 reintentos con espera corta,
sin `sleep` arbitrario).

**5. Secuencia estándar de captura**
```bash
mkdir -p .local/screenshots
npx @playwright/cli -s=$SESSION open "$URL"
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 (`.local/screenshots/` en el directorio del proyecto actual), nunca volcar
snapshots/HTML crudo al chat.

**6. Flujos interactivos (cuando el usuario pide probar un flujo, no solo una página)**
Loop snapshot → act (click/fill/select) → re-snapshot tras cada cambio de DOM (los refs quedan obsoletos
tras mutaciones). Reportar cada paso relevante y detenerse si un elemento esperado no aparece tras
2 reintentos con snapshot fresco.

**7. Detección de app local vs URL remota**
- Si el usuario pide probar "la app" sin dar URL y hay un servidor de dev corriente/definible en el
  proyecto (package.json con script `dev`/`start`, etc.), primero levantar el servidor (reutilizar lo que
  ya haga la skill `run` si está disponible en ese proyecto) y esperar a que responda antes de abrir sesión
  de Playwright.
- Si se da una URL explícita, usarla directamente.

**8. Formato de reporte final**
Resumen corto: URL probada, acciones realizadas, rutas de artefactos, errores de consola (o "ninguno"),
hallazgos de UX/bugs si los hay. No pegar el snapshot completo ni el HTML en el chat.

**9. Limpieza y recuperación**
- Cerrar sesión siempre. Si el cierre falla, ejecutar `npx @playwright/cli kill-all` como recuperación.
- Mencionar `npx @playwright/cli list` para ver sesiones huérfanas si algo quedó colgado de una corrida
  anterior.

## Verificación

1. Confirmar que el archivo quedó bien formado: `cat ~/.claude/skills/web-ui-test/SKILL.md` y revisar que
   el frontmatter parsea (mismo formato que `docmost-context/SKILL.md`).
2. Probar la skill de punta a punta contra una URL real (ej. `https://example.com`):
   - Primera corrida: debe detectar que Playwright no está instalado, instalarlo (`npm install -g
     @playwright/cli` + `npx @playwright/cli install-browser`), y luego completar la prueba.
   - Segunda corrida: debe saltarse la instalación (ya presente) e ir directo a abrir sesión/capturar.
3. Verificar que se generaron los artefactos esperados en `.local/screenshots/` (viewport png, full-page
   png, snapshot md) y que la sesión se cerró (`npx @playwright/cli list` no debe mostrarla activa).
4. Confirmar que el reporte en el chat es un resumen (no snapshot/HTML crudo).