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:

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.
Usa el navegador siempre en modo headless (nunca --headed) porque el entorno es un tunnel remoto sin display.
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).
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

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

# ¿@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

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

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).
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.
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).
Confirmar que el reporte en el chat es un resumen (no snapshot/HTML crudo).

8.5 KiB Raw Blame History