CommunityImagengithub.com

before-after

Genera una imagen con una tabla de capturas de pantalla de antes y después que muestra cada cambio visual que la rama actual introduce respecto a una rama base.

¿Qué es before-after?

La habilidad 'before-after' automatiza la creación de una tabla visual comparativa (antes/después) a partir de los cambios de código de una rama. Es especialmente útil para desarrolladores que necesitan presentar evidencia visual de los cambios realizados en un pull request, para revisiones de diseño o para documentar modificaciones en la interfaz de usuario. Funciona sobre cualquier proyecto local que pueda construirse y servirse, y no requiere despliegue externo. El flujo incluye: identificar todos los cambios visuales a partir del diff de código, construir y servir localmente tanto la rama base como la rama de trabajo, capturar pares de capturas de pantalla en condiciones idénticas (mismos datos, viewport, tema), y componer una tabla en una imagen PNG. Soporta captura de estados de datos (cargando, vacío, error) e interactivos (hover, foco, popover) mediante mocking de red y pasos de interacción. La salida se almacena en `~/Documents/before-after/` y se puede recapturar filas individuales con `--only`. Está diseñada para su uso con herramientas como Claude Code (antropología), Cursor o agentes similares que pueden ejecutar scripts de Node.js y Playwright.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MagnusBrogie/agent-skills/tree/HEAD/before-after

Installed? Explore more Imagen skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Preguntar en tu IA favorita

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

Documentación

Antes y después

Genera un solo PNG: una tabla con una fila por cada cambio visual, y en cada fila el nombre del cambio, una nota de una línea, la captura de la base y la captura de la rama. Un lector que no haya visto el código debería poder deducir de la imagen qué es lo que se ve diferente y dónde.

La imagen solo es tan buena como su lista de cambios. Una tabla que muestre tres de cinco cambios, o que muestre una diferencia causada por datos diferentes en lugar del código, engaña al lector. La mayor parte del trabajo consiste en encontrar cada cambio visual y capturar cada par de modo que el código sea lo único que difiera.

Dónde van las imágenes. Todo lo que produce esta habilidad se almacena en la carpeta Documentos del usuario, en ~/Documents/before-after/<repositorio>/<rama>/: las capturas, el manifiesto, una copia de shots.mjs y el archivo before-after.png final. Los scripts eligen esta carpeta por sí mismos y no toman una ruta de salida; si el usuario desea una raíz diferente a ~/Documents/before-after, establece la variable de entorno BEFORE_AFTER_DIR, que es suya para configurar, no tuya. No escribas las imágenes en ningún otro lugar y no las muevas ni copies después; el bloc de notas es solo para el área de trabajo base y para redactar shots.mjs. Una ejecución posterior para la misma rama reutiliza la carpeta.

Dos scripts se encuentran en scripts/ junto a este archivo: capture.mjs toma las capturas y compose.mjs construye y verifica la tabla. Cada uno documenta su formato de entrada en su encabezado. Lee ambos encabezados antes de empezar.

Notas locales. Si un archivo llamado LOCAL.md se encuentra junto a este archivo, léelo antes de empezar. Contiene los valores predeterminados del usuario para los proyectos en los que trabaja (comandos, hosts, cuentas, rutas) y no forma parte de la habilidad publicada. Cuando cubre el proyecto en cuestión, cuenta como parte de las instrucciones del proyecto; cuando no lo cubre, ignóralo.

1. Recopila los cambios

Sin una rama base especificada, usa la base del pull request (gh pr view --json baseRefName --jq .baseRefName), o la rama predeterminada (git symbolic-ref --short refs/remotes/origin/HEAD), o origin/main. Prefiere la referencia de seguimiento remoto. Incluye el trabajo no confirmado:

base=$(git merge-base <base> HEAD)
git diff --stat "$base"; git diff "$base"; git status --short   # lee también archivos no rastreados
git log --oneline "$base"..HEAD

Lee también la descripción del pull request y el issue, si los hay. A menudo indican en qué pantallas se espera el cambio e incluyen capturas que la gente espera ver.

2. Enumera cada cambio visual

Rastrea cada fragmento (hunk) hacia afuera hasta lo que ve el usuario:

  • Código de vista, estilos, tokens, iconos, copia, traducciones. Cada uno de estos es candidato. Para código compartido (un componente de UI, un helper de formato, un token CSS), busca sus llamantes y enumera cada pantalla que lo renderiza. Un cambio en código compartido suele verse en más lugares de los que la rama pretendía cambiar.
  • Estados de datos. Para cada pantalla, lee qué ramas del código recorre el cambio: cargado, cargando, vacío, error, valor faltante, cero y negativo, texto largo, un elemento y muchos, cada modo o configuración. Conserva solo los estados cuyo renderizado cambie el diff.
  • Estados de interacción. Hover, foco, presionado, deshabilitado, seleccionado; un popover, menú, hoja o diálogo abierto; un campo que muestra un error de validación. Estos requieren pasos antes de la captura (paso 4).
  • Pantallas que la rama añade o elimina. Estas tienen solo un lado; la fila muestra un marcador de posición para el otro.
  • Entornos que soporta el proyecto, donde el cambio podría verse diferente: tema oscuro, anchos de móvil y escritorio, otra configuración regional.

Ordena los candidatos en tres listas:

  1. Visual: algo en pantalla es diferente. Estos se convierten en filas.
  2. No visual: el cambio solo afecta al árbol de accesibilidad, atributos, texto solo para lectores de pantalla, comportamiento o estructura de código. Estos no son filas. Menciónalos en el informe para que el lector sepa que se consideraron y no se omitieron. Si el usuario quiere mostrarlos de todos modos, una fila puede contener un extracto del árbol de accesibilidad capturado como imagen, etiquetado como tal.
  3. Dudoso: cambios de marcado o clases que se supone que son invisibles pero podrían mover o recolorear algo (un nuevo elemento envolvente, una clase de posicionamiento, un helper intercambiado). Captura estos y deja que la verificación de píxeles decida.

Un cambio de movimiento (una animación, una transición, su temporización) no puede mostrarse en una imagen fija. Ponlo bajo "No mostrado" en el informe y di cómo verlo.

Agrupa las filas de forma sensata: una fila por aspecto visual distinto, no por sitio de llamada. Si diez pantallas usan la celda modificada de la misma manera, muestra una o dos y nombra el resto en la nota. Apunta a una tabla que alguien realmente lea; más allá de unas doce filas, crea una segunda imagen por área y dila.

Si las listas visual y dudosa están ambas vacías, detente aquí. Dile al usuario que la rama no tiene cambios visuales, enumera lo que se consideró y por qué cada elemento no es visual, y no produzcas ninguna imagen. Si solo existen elementos dudosos y cada par resulta idéntico, el resultado es el mismo, y los pares idénticos son la evidencia: repórtalos como verificados y sin cambios.

3. Construye la base y la rama localmente

Captura ambos lados desde construcciones locales, nunca desde un despliegue: un despliegue va por detrás del árbol de trabajo y no puede mostrar trabajo no confirmado.

  • Rama: el árbol de trabajo actual, construido después del último cambio.

  • Base: un área de trabajo separada en el merge base, para que nunca se toque el árbol de trabajo del usuario. Nunca cambies de rama ni hagas stash en el checkout del usuario.

    git worktree add --detach <blocdeNotas>/before-after-base "$base"
    

    Instala las dependencias allí. Sincronizar el directorio de dependencias del checkout principal está bien solo cuando el diff no toca el archivo de bloqueo. Elimina el área de trabajo cuando termines (git worktree remove).

Usa los comandos documentados del proyecto (lee su README, AGENTS.md, CLAUDE.md, documentos de desarrollo y cualquier habilidad run). Ambos lados deben comunicarse con el mismo backend de staging o pruebas, nunca producción. Si no está claro qué comando apunta a qué backend, lee la configuración de compilación, y si aún así queda duda, detente y pregunta. Antes de capturar nada, verifica el host de una solicitud API real desde cada lado.

Prefiere la compilación de producción del proyecto servida estáticamente (una build seguida de un preview o cualquier servidor estático) sobre su servidor de desarrollo. Un servidor de desarrollo añade clientes de recarga en caliente y superposiciones, puede necesitar un proceso de vigilancia por área de trabajo y puede renderizar de manera diferente a lo que se envía. Si construyes con una herramienta que no es el comando de compilación propio del proyecto, verifica que la página se renderice: un proyecto puede post-procesar su paquete. Una compilación también puede vaciar o sobrescribir un directorio de salida en el árbol de trabajo del usuario. Esos son archivos generados, pero dilo en el informe qué reconstruiste, y vuelve a poner lo que la configuración de desarrollo espera si la compilación lo eliminó.

Antes de confiar en cualquier captura, confirma que las dos compilaciones difieren: lee el marcado del elemento cambiado en cada lado y ve el cambio del diff en él. Dos servidores que sirven el mismo código dan pares idénticos que no prueban nada.

Elige cómo servir las dos compilaciones:

  • Ambas a la vez, en dos puertos libres. Este es el más simple, y las dos capturas de un par se toman con segundos de diferencia. Funciona cuando las pantallas no necesitan inicio de sesión, o cuando el inicio de sesión sobrevive a un cambio de puerto. Las cookies se comparten entre puertos en el mismo host, pero el almacenamiento local no, y un backend puede solo aceptar ciertos orígenes. Verifica que una pantalla con inicio de sesión realmente cargue en el segundo puerto antes de confiar en ello.
  • Una después de la otra, en el mismo puerto. Sirve la base en el puerto habitual del proyecto, captura con --side=before, detenlo, sirve la rama en ese puerto y captura con --side=after. El estado de inicio de sesión guardado y los orígenes permitidos se aplican entonces a ambas. Las capturas están separadas por minutos, por lo que los datos deben estar simulados o saberse estables.

Si el proyecto tiene un catálogo de componentes (Storybook, una aplicación "taller" o similar) y el cambio está en un componente compartido, capturarlo allí es más barato y estable que en la aplicación completa, y generalmente no necesita inicio de sesión. Aún así, captura al menos una pantalla real por cambio donde puedas, para que la imagen lo muestre en contexto. Si no se puede alcanzar una pantalla real (por ejemplo, sin inicio de sesión de prueba), dilo en "No mostrado".

4. Captura cada par en condiciones idénticas

Escribe un shots.mjs en el bloc de notas, en el formato dado en el encabezado de scripts/capture.mjs, y ejecútalo desde la raíz del proyecto para que Playwright resuelva y la carpeta de salida obtenga el nombre correcto del repositorio y la rama:

node <estaHabilidad>/scripts/capture.mjs <blocDeNotas>/shots.mjs --before=http://localhost:<p1> --after=http://localhost:<p2>

El script ejecuta los mismos pasos contra ambas URL. Usa Chrome instalado, un factor de escala de dispositivo de 2 y movimiento reducido. Desactiva transiciones, reinicia animaciones infinitas (un brillo, un spinner) a su primer fotograma y finaliza las finitas, espera a las fuentes y a que la red se estabilice, y congela el reloj si le das una hora. Escribe shots/<slug>.before.png, shots/<slug>.after.png y el manifest.json para el paso 5 en la carpeta Documentos descrita arriba, copia shots.mjs allí e imprime la ruta de la carpeta como su última línea. --only=<slug> recaptura una fila. Una captura fallida deja un <slug>.<side>.FAILED.png de toda la ventana gráfica, que muestra cómo se veía la página en su lugar.

Si la configuración de pruebas de extremo a extremo del proyecto tiene un estado de inicio de sesión guardado, pásalo como storageState (lee los documentos del proyecto sobre cómo se crea). En Orca, el navegador integrado (la habilidad orca-cli) también funciona para uno o dos pares, pero un script hace que los pares sean repetibles.

Lo que debes acertar en shots.mjs:

  • Mismos datos en ambos lados. Los datos en vivo se desvían entre dos capturas: los precios cambian y las listas se reordenan. Prefiere simular las respuestas de las que depende la pantalla en el mock de la captura: captura un payload real del staging y complétalo en ambos lados. Dos límites:
    • Si la rama cambia la solicitud o la forma de la respuesta (un nuevo endpoint, un nuevo campo, un decodificador cambiado), un payload no puede servir a ambos lados. Dale a cada lado el payload que su código espera, construido a partir de los mismos valores subyacentes, y dilo en el subtítulo.
    • Los datos que llegan a través de un WebSocket o eventos enviados por el servidor no son tocados por page.route. Usa page.routeWebSocket, o elige una pantalla o un momento en que el flujo esté tranquilo, u oculta el elemento en vivo si no es el sujeto.
  • Alcanza el estado deliberadamente. Los estados de carga, error y valor faltante rara vez aparecen en cuentas de prueba: prodúcelos en mock (retrasa una respuesta, falla, anula un campo). Deriva las rutas de solicitud y los nombres de campo del código, no adivinando. Alcanza los estados de interacción en steps (hover, foco, clic para abrir).
  • Recorta al cambio con contexto. Establece target al elemento más pequeño que muestre el cambio y que siga siendo reconocible como parte de su pantalla: la tarjeta, la tabla, la hoja, no la página completa. Apunta a un recorte de como máximo unos 650 CSS px de ancho: eso es lo que cabe lado a lado a tamaño completo. Un recorte más ancho se apila (antes arriba de después), y uno más ancho de unos 1300 CSS px se encoge, por lo que su texto se vuelve más difícil de leer. Usa el mismo objetivo en ambos lados para que los recortes coincidan.
  • Oculta lo que no es el sujeto y se mueve constantemente (un ticker, un reloj, un avatar que carga tarde) con una etiqueta de estilo en steps, en ambos lados.

5. Compone y verifica

node <estaHabilidad>/scripts/compose.mjs <carpeta>/manifest.json [--diff] [--stack]

La imagen se escribe junto al manifiesto como before-after.png, y su ruta es la última línea de la salida. --diff añade una imagen por fila con los píxeles cambiados en magenta. Úsalo cuando el cambio sea pequeño o sutil (espaciado, un color, un glifo); omítelo cuando el cambio sea obvio. Cuando las dos capturas de una fila difieren en tamaño, la comparación se alinea en la esquina superior izquierda, por lo que todo después del desplazamiento cuenta como cambiado; la fila lo dice, y la imagen diff es entonces solo una guía aproximada.

El script dibuja ambas capturas de una fila a la misma escala. Imprime la proporción de píxeles cambiados por fila y cómo se diseñó cada fila, y sale con código 3 si algún par es idéntico. Entonces:

  1. Un par idéntico significa que la captura falló el cambio (estado incorrecto, pantalla incorrecta, una caché, una compilación base que en realidad no es la base) o el cambio no es visual. Averigua cuál. Arregla la captura, o saca la fila del manifiesto y mueve el elemento a la lista de no visuales como "verificado, ningún píxel difiere". Nunca entregues una fila con un par idéntico.
  2. Mira la imagen (lee el PNG) y verifica cada fila: la diferencia que ves es la que describe la nota, y nada más difiere. Una diferencia que no se explica por el diff (un precio diferente, una fila faltante, un diseño desplazado en otro lugar) es desviación de datos o una regresión inesperada. Recaptura, o repórtalo al usuario como una posible regresión. No lo ocultes.
  3. Verifica que el texto en cada captura se pueda leer. Actúa ante cualquier advertencia de "el texto puede ser ilegible" del script: recorta más estrecho y recaptura esa fila con --only.
  4. Si la imagen es muy larga, divídela por área: crea una subcarpeta por área dentro de la carpeta de la rama, cada una con su propio manifest.json cuyas rutas apunten a ../shots/..., y compón cada una.

6. Informe

Dale al usuario:

  • La ruta absoluta completa al PNG.
  • Las filas, una línea cada una.
  • No mostrado: los cambios no visuales, los elementos dudosos que la verificación de píxeles encontró sin cambios, los cambios de movimiento, los visuales que no pudiste capturar (y por qué), y los sitios de llamada omitidos como duplicados de una fila que se muestra.
  • Cualquier cosa inesperada que la verificación de píxeles o tu propio vistazo hayan descubierto.
  • Cómo se produjeron los pares (datos reales de staging, o qué respuestas fueron simuladas; un catálogo o la aplicación real), para que el lector sepa qué prueban las imágenes.

Detén los servidores de desarrollo que iniciaste y elimina el área de trabajo base. Las capturas, la copia de shots.mjs y el manifiesto permanecen en la carpeta de salida, para que una ejecución posterior pueda recapturar una sola fila con --only.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills relacionados