CommunityProgramación y desarrollogithub.com

visual-verify

Conduce un navegador headless real (Playwright: Chromium, o WebKit para iPhone; ejecuta en la imagen Docker de Playwright cuando Docker está instalado) para capturar una aplicación web en ejecución en un viewport de dispositivo específico, examinar el resultado y confirmar que algo realmente se renderiza/funciona, o producir un compuesto etiquetado lado a lado ANTES/DESPUÉS para un cambio visual. Úsalo cada vez que el usuario pida verificar visualmente algo, ver cómo se ve una página/componente, comprobar una IU en un ancho de teléfono/tableta, capturar la aplicación, obtener un antes y después de un cambio de estilo, o probar el tacto móvil en iOS/Android (tamaños de objetivos táctiles, tocar, arrastrar/redimensionar con el dedo). Funciona en cualquier proyecto. Utiliza la librería Playwright a través de scripts Node en scripts/ — no hay un MCP de Playwright aquí.

¿Qué es visual-verify?

Visual-verify es una habilidad para agentes de IA (como Claude Code, Cursor, Codex) que permite realizar verificaciones visuales automatizadas de aplicaciones web en un navegador headless real usando Playwright. Su propósito principal es que el agente pueda capturar capturas de pantalla de la aplicación en ejecución, examinarlas y emitir un juicio verificado sobre su estado (correcto/incorrecto) o generar composiciones ANTES/DESPUÉS para cambios visuales. Soporta tres modos: 'Verificar' (captura una o varias capturas de pantalla y las lee para confirmar el estado), 'Antes/Después' (alterna un cambio visual para producir una imagen compuesta etiquetada) y 'Táctil' (emula un teléfono, toca y arrastra con un dedo, y audita tamaños de objetivos táctiles). La habilidad se ejecuta mediante scripts Node.js incluidos en el directorio de la habilidad, sin depender de un MCP de Playwright. Utiliza Docker cuando está disponible para lanzar contenedores aislados de Playwright, o bien navegadores locales instalados. Es fundamental que el agente siempre lea las imágenes capturadas antes de reportar, que muestre los resultados visualmente en la respuesta (con rutas absolutas o adjuntos), y que elija el viewport correcto según el dispositivo del usuario (derivando el ancho CSS de las capturas del usuario). La habilidad incluye scripts para captura de pantalla, composición de imágenes y pruebas táctiles, junto con un instalador y un comando 'doctor' para verificar requisitos previos.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/conorjwryan/skills/tree/main/visual-verify

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Vista previa

Del README del skill

descripción

Documentación

Verificación visual

Versión: 1.1.0. Las versiones anteriores a la 1.0.0 no se rastrean en este repositorio.

Mira la aplicación real en ejecución en un navegador headless e informa honestamente sobre lo que ves. Dos modos:

  • Verificar (por defecto) — captura una (o algunas) capturas de pantalla del estado actual y léelas tú mismo para confirmar que una funcionalidad se renderiza, una corrección funcionó o un diseño es correcto en un ancho determinado.
  • Antes/después — para un cambio visual, alterna el cambio entre apagado y encendido y produce una única composición etiquetada lado a lado ANTES/DESPUÉS.
  • Táctil (iOS / Android) — emula un teléfono, toca y arrastra con un dedo, y audita los tamaños de los objetivos táctiles. Consulta Comprobaciones de tacto móvil a continuación.

Elige el modo según lo que el usuario haya pedido. "¿Esto se ve bien / está funcionando / muéstrame en ancho de teléfono" → verificar. "Antes y después / ¿esto lo arregló visualmente?" → antes/después.

Cuando el usuario lo pida, hazlo

Cuando el usuario te pida verificar visualmente algo (o capturar una captura de pantalla / comprobar cómo se ve), esa solicitud es tu luz verde — ejecuta la comprobación completa tú mismo: captura, lee las imágenes y declara claramente si es correcto. No te limites a ofrecer y detenerte.

No ejecutes esto sin que te lo pidan por iniciativa propia después de cada cambio — ya que maneja un navegador y lee imágenes, lo que cuesta tokens. Después de un cambio visual no solicitado, puedes ofrecerlo ("¿quieres un compuesto antes/después — móvil, escritorio o ambos?") y dejar que el usuario decida.

Muestra lo que verificaste — cada vez

El usuario debe poder ver el resultado sin abrir archivos. En la respuesta que informa el trabajo, muestra la imagen posterior para cada funcionalidad que verificaste — una imagen por funcionalidad, así que tres cosas comprobadas significan al menos tres imágenes. Pon cada imagen junto a un título de una línea que diga lo que muestra y si es correcta (por ejemplo, "Confirmación de eliminación, ancho de teléfono — enfoque en Cancelar").

  • Muestra las imágenes en línea con Markdown y una ruta absoluta, ![descripción](/ruta/absoluta/a/imagen.png), donde el cliente las renderice. De lo contrario, adjúntalas (por ejemplo, SendUserFile). Da siempre también la ruta.
  • Elige la toma más clara: recorta o limita a la funcionalidad donde la página completa la ocultaría.
  • Para un antes/después, muestra el compuesto.
  • Si algo no se pudo mostrar honestamente (IU del sistema, área segura), dilo en lugar de mostrar una imagen engañosa.

Siempre mira lo que capturaste

La captura de pantalla no es el entregable — tu juicio verificado lo es. Lee cada imagen que captures antes de informar y antes de enviar un compuesto, para que puedas confirmar que realmente muestra lo que afirmas. Si no muestra lo que esperabas, investiga; no informes éxito basado en una toma no leída.

Elige el viewport correcto — esto es importante

Un error de diseño responsive a menudo solo se reproduce en un ancho específico. Coincide con el dispositivo del usuario. Si enviaron una captura de pantalla, deriva el ancho CSS:

css_width = ancho_píxel_captura / devicePixelRatio

Los iPhones modernos son DPR 3 (por ejemplo, una captura de pantalla de 1320 px de ancho ⇒ 440 px CSS; clase Pro Max). Android común es DPR ~2.6–3. Cuando no estés seguro, barre algunos anchos (por ejemplo, 320, 360, 390, 440) — el script de captura hace que esto sea económico. Pasa --mobile para emulación táctil/móvil. Para un cambio de diseño general que se aplica a todos los anchos, comprueba tanto escritorio como móvil.

Los scripts (ejecuta con Bash; no hay MCP)

No busques una herramienta MCP de browser_* / Playwright — no está instalada. Todo se ejecuta a través de scripts Node simples. Resuelve el directorio absoluto que contiene este SKILL.md instalado, luego establece VISUAL_VERIFY_DIR en ese directorio en tu shell. Esto puede ser una instalación de proyecto o una instalación global; usa la copia cuyas instrucciones estás leyendo, no una ruta global fija. Mantén el directorio de trabajo en la raíz del proyecto de la aplicación. Reutiliza esta variable en cada comando de shell (o vuélvela a establecer si el estado del shell no se conserva):

VISUAL_VERIFY_DIR="/ruta/absoluta/a/instalado/visual-verify"

Los scripts incluidos son:

"$VISUAL_VERIFY_DIR/scripts/screenshot.mjs"   # captura una URL → png
"$VISUAL_VERIFY_DIR/scripts/composite.mjs"     # dos png → antes/después etiquetado
"$VISUAL_VERIFY_DIR/scripts/touch.mjs"         # tacto en teléfono: tocar, arrastrar, auditoría de objetivos

Configuración de tiempo de ejecución y navegador. Esta habilidad posee una dependencia exacta de Playwright y un archivo de bloqueo. Nunca resuelve un paquete global o de proyecto de Playwright. Ejecuta el instalador explícitamente después de instalar o actualizar la habilidad; las comprobaciones normales nunca descargan paquetes, imágenes o navegadores. Usa Node.js 20+, npm y Bash. No instales paquetes de sistema del host para esta habilidad.

Dónde se ejecuta el navegador. Con Docker disponible, cada lanzamiento inicia su propio contenedor desde la imagen de Playwright exacta correspondiente, ya instalada. Docker asigna un puerto loopback único; el ayudante verifica la identidad de su contenedor y se conecta a ese endpoint. Las dependencias de Node instaladas de la habilidad se montan como solo lectura, por lo que el servidor no necesita descargas de paquetes. Playwright reenvía las solicitudes loopback al cliente, permitiendo URLs de aplicaciones locales sin red del host. El cierre normal, el fallo de inicio y la terminación controlada limpian solo el contenedor de esa ejecución. Un cierre forzado o un fallo del host pueden dejar un contenedor etiquetado; inspecciona la propiedad antes de una limpieza explícita. No se reemplazan ni detienen contenedores preexistentes. La red de Docker Desktop/macOS aún requiere validación separada; no lo afirmes basándote en una comprobación de Linux.

Sin Docker, el ayudante utiliza binarios de navegador local instalados. Establece VISUAL_VERIFY_DOCKER=0 para forzar el modo local; la API de lanzamiento también acepta un backend explícito. La salida JSON nombra el backend y la versión reales.

Lanzador compatible para scripts de proyecto

// Resuelve esta importación relativa al directorio de habilidad instalada.
const { launchBrowser } = await import("<habilidad-instalada>/scripts/load-playwright.mjs");
const { browser, where } = await launchBrowser("chromium", {
  backend: "auto", // auto, docker, local
  timeout: 30000,
  launchOptions: { headless: true },
});
try {
  // Usa browser.newContext(), etc. Informa `where` con la evidencia.
} finally {
  await browser.close();
}

launchOptions van al launch local o a la solicitud de lanzamiento del navegador del servidor Docker fijado. El servidor completo de Playwright habilita el reenvío loopback del cliente solicitado; Docker posee el host y puerto del servidor; las rutas ejecutables específicas del host y otras opciones específicas de la máquina son responsabilidad del llamante. Las exportaciones existentes loadChromium() y loadBrowser(nombre) siguen siendo APIs de compatibilidad solo locales: no lanzan Docker ni reparan navegadores faltantes. Migra a los llamantes deliberadamente en lugar de asumir que la configuración cambia su comportamiento.

Los lanzamientos de Docker utilizan un contenedor de servidor nuevo, con nombre único, para cada llamada. Docker asigna atómicamente un puerto loopback; el cliente valida los metadatos del contenedor y se conecta a su ruta WebSocket informada. Playwright reenvía el tráfico loopback del cliente, preservando el acceso a aplicaciones de desarrollo locales sin red del host. Los contenedores se eliminan al cerrar, en fallos de inicio y en terminación controlada. Esto intercambia la reutilización de servidores cálidos por el aislamiento de endpoints; los contenedores de puerto compartido más antiguos se dejan en paz. Un cierre forzado o un fallo de Docker pueden dejar un huérfano. Inspecciona la salida de doctor y verifica la propiedad del contenedor exacto antes de eliminarlo explícitamente; nunca detengas todos los procesos/contenedores coincidentes. El comportamiento de Docker en múltiples plataformas aún requiere validación independiente.

Banderas de screenshot.mjs: --url --out [--width 390] [--height 844] [--dpr 2] [--mobile] [--wait 2000] [--click "Texto o selector"] [--scroll-bottom "sel"] [--eval "js"] [--clip x,y,w,h] [--full]. --click es repetible y coincide primero con el nombre accesible de un botón, luego con un selector CSS — úsalo para alcanzar un estado detrás de una pestaña/menú/diálogo.

Instalación única (por máquina)

bash "$VISUAL_VERIFY_DIR/scripts/install.sh"

Instala la dependencia bloqueada en el propio node_modules de esta habilidad. La configuración auto por defecto descarga la imagen Docker correspondiente si Docker está disponible; de lo contrario, instala Chromium local. Pasa docker o local al instalador para seleccionar explícitamente. WebKit local no se instala con este comando. No se modifican paquetes npm globales ni paquetes del sistema.

Inspecciona los requisitos previos sin iniciar navegadores, descargar imágenes ni cambiar contenedores:

node "$VISUAL_VERIFY_DIR/scripts/doctor.mjs"

Doctor informa la versión de la habilidad/tiempo de ejecución, la ruta de tiempo de ejecución, la presencia del ejecutable local, la disponibilidad de la imagen Docker y los contenedores/endpoints activos de Visual Verify (incluyendo nombres heredados). Su código de salida verifica los requisitos previos de Chromium para el backend predeterminado seleccionado; no demuestra el lanzamiento del navegador ni la disponibilidad de WebKit. La instalación de archivos y el lanzamiento exitoso de un navegador son evidencia separada.

Verifica con:

node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
  --url https://example.com --out /tmp/_vv_check.png --width 390 --height 844

Inspecciona la imagen y el JSON del backend para confirmar que esta comprobación de humo funcionó.

Espera por el estado que se está comprobando

Los comandos de captura de pantalla y táctil admiten estas opciones post-acción:

  • --ready-selector "<selector>": espera a que el primer elemento coincidente sea visible.
  • --ready-js "<expresión>": sondea hasta que una expresión de página (incluyendo una promesa) sea verdadera.
  • --ready-timeout 10000: tiempo de espera de preparación positivo en milisegundos; compartido por las esperas de selector y predicado. También acota la evaluación de --eval y --report por separado.
  • --settle 0: retraso no negativo opcional después de la preparación para animaciones.

Estas condiciones se ejecutan después de todos los clics/toques, desplazamientos, evaluación y arrastres, antes de la auditoría y captura. Ambas condiciones, cuando se proporcionan, deben cumplirse. Un fallo sale con un código distinto de cero y no escribe una nueva captura de pantalla de éxito (un archivo de salida existente no se elimina). Elige rutas de salida únicas. --wait retiene su retraso pre-acción heredado; los retrasos fijos de clic/arrastre siguen siendo ajustes de compatibilidad, no evidencia de preparación. Indica lo que demuestra la condición seleccionada.

node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
  --url "<url-app-local>" --out visual-checks/search-desktop.png \
  --click "Buscar" --ready-selector "[data-search-results]" \
  --ready-js "document.querySelectorAll('[data-result]').length > 0"

Usa una condición específica para el nuevo estado esperado, no un elemento obsoleto que ya esté en la página. Para pasos intermedios que requieren resultados asíncronos, usa la API de lanzamiento y los localizadores de Playwright con aserciones entre acciones. Si esperas una respuesta, registra la espera antes de activar su solicitud y luego afirma el estado renderizado; una respuesta por sí sola no demuestra la renderización. No trates los retrasos arbitrarios o network-idle como garantías de finalización para aplicaciones con rebote.

Ubicación de salida

Escribe las imágenes generadas en un directorio visual-checks/ ignorado por git en la raíz del repositorio (mkdir -p visual-checks). Si no estás en un repositorio, o no deseas agregar archivos a él, usa un directorio temporal en su lugar. Referencia las rutas estables al enviar archivos al usuario.

Dale a cada imagen de una misma ejecución un prefijo <cambio> compartido que describa lo que se muestra (por ejemplo, import-export-tab, header-nav) — no genéricos como before.png/after.png — para que un vistazo al directorio indique a qué ejecución pertenece un archivo:

visual-checks/<cambio>-<viewport>.png                 # modo verificar: una sola toma
visual-checks/<cambio>-<viewport>-before.png          # modo antes/después
visual-checks/<cambio>-<viewport>-after.png
visual-checks/<cambio>-<viewport>-before-after.png    # el compuesto

donde <viewport> es mobile o desktop.

Flujo de trabajo — modo verificar

  1. Asegúrate de que la aplicación se esté ejecutando y tengas su URL (iníciala de la manera en que este proyecto se ejecuta — consulta Ejecutando la aplicación a continuación). mkdir -p visual-checks.
  2. Captura el estado a comprobar, alcanzándolo con --click / --eval / --scroll-bottom si es necesario:
    node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
      --url "<url de aplicación en ejecución>" --out visual-checks/<cambio>-mobile.png \
      --width 440 --height 800 --mobile --wait 2000
    
    Barre algunos anchos, o elimina --mobile y usa, por ejemplo, --width 1280 --height 800 para escritorio, según sea necesario.
  3. Lee cada imagen e informa claramente si es correcta. Si estás verificando una corrección, confirma que lo que estaba roto realmente ha desaparecido; si es una funcionalidad, confirma que realmente se renderiza.
  4. Muestra la(s) toma(s) relevante(s) en tu respuesta — una por funcionalidad (consulta Muestra lo que verificaste).

Flujo de trabajo — modo antes/después

  1. Confirma el alcance y el/los viewport(s). mkdir -p visual-checks. Elige el prefijo <cambio> compartido.
  2. Captura DESPUÉS — el árbol de trabajo ya tiene el cambio:
    node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
      --url "<url de aplicación en ejecución>" --out visual-checks/<cambio>-mobile-after.png \
      --width 440 --height 800 --mobile --wait 2000
    
    Para escritorio, elimina --mobile, usa, por ejemplo, --width 1280 --height 800, y el sufijo -desktop-after.png.
  3. Captura ANTES — deshace temporalmente solo el cambio visual, captura la pantalla en <cambio>-<viewport>-before.png, luego restaura. Prefiere git para que no puedas olvidar restaurar:
    • Cambio no confirmado: git stash push -- <archivo> → captura → git stash pop
    • Cambio confirmado: git show HEAD~1:<ruta> > <ruta> (o git checkout <padre> -- <archivo>) → captura → git checkout -- <archivo> Espera a que el servidor de desarrollo recargue en caliente entre la alternancia y la toma (--wait).
  4. Compuesto — mismo prefijo, sufijo -before-after.png:
    node "$VISUAL_VERIFY_DIR/scripts/composite.mjs" \
      --before visual-checks/<cambio>-mobile-before.png --after visual-checks/<cambio>-mobile-after.png \
      --out visual-checks/<cambio>-mobile-before-after.png \
      --title "Encabezado a 440px (ancho de iPhone)" \
      --before-label "ANTES — título comprimido" \
      --after-label  "DESPUÉS — título a ancho completo"
    
  5. Lee el compuesto, confirma que muestra lo que afirmas, luego muéstralo en tu respuesta.
  6. Restaura la alternancia ANTES. Nunca confirmes ni despliegues con el cambio temporal ANTES todavía aplicado — vuelve a verificar git status / git diff antes de finalizar.

Comprobaciones de tacto móvil

Skills relacionados