Fase 2: 04_sanitize.py - scrubbing de secretos de skills/agentes/plans (10 secretos unicos, gate en verde)
This commit is contained in:
@@ -0,0 +1,145 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user