Stirling-Tools/Stirling-PDF

¿Qué hace Stirling-PDF?

Analiza una rama o Pull Request y captura automáticamente capturas de pantalla de antes/después de cada superficie de UI que toquen los cambios, luego compara píxel a píxel los pares para revelar lo que realmente cambió y ensambla imágenes de montaje de antes/después listas para PR. Es genérico y basado en el diff: deriva los objetivos de captura a partir del diff (herramientas/rutas modificadas → URLs) en lugar de listar manualmente las pantallas, captura el estado "antes" desde la rama base y el estado "después" desde la rama de trabajo, luego conserva solo las vistas que difieren visualmente. Cada comparación se recorta automáticamente.

Características principales

• Automatización basada en diff: No necesitas especificar manualmente qué pantallas capturar; la herramienta lo deduce del código modificado.
• Comparación de píxeles: Detecta cambios visuales reales, no solo diferencias de código.
• Montajes listos para PR: Genera imágenes de antes/después que puedes insertar directamente en la descripción del Pull Request.
• Recorte automático: Cada comparación se recorta para eliminar áreas irrelevantes y centrarse en el cambio.

Cómo funciona

1. Análisis del diff: La herramienta analiza el diff de la rama o PR para identificar las rutas, herramientas o componentes modificados.
2. Mapeo a URLs: Convierte esas rutas en URLs específicas de la aplicación (por ejemplo, herramientas de Stirling-PDF como /pdf-to-image).
3. Captura de "antes": Despliega la aplicación desde la rama base y captura capturas de pantalla de todas las URLs identificadas.
4. Captura de "después": Despliega la aplicación desde la rama de trabajo y captura las mismas URLs.
5. Comparación de píxeles: Compara cada par de capturas usando diff de píxeles.
6. Filtrado: Conserva solo los pares donde se detectan diferencias visuales.
7. Generación de montajes: Crea imágenes de montaje que muestran el estado "antes" a la izquierda y "después" a la derecha.

Requisitos

• Node.js 18 o superior
• Puppeteer o Playwright para la captura de pantallas
• Acceso al repositorio y capacidad de cambiar entre ramas

Uso básico

# Analizar una rama específica
stirling-pdf-visual-diff --base main --head feature/new-tool

# Analizar un PR existente
stirling-pdf-visual-diff --pr 123

# Especificar un directorio de salida para las imágenes
stirling-pdf-visual-diff --pr 123 --output ./visual-diffs

Integración con CI/CD

Puedes integrar esta habilidad en tu pipeline de CI/CD para detectar automáticamente cambios visuales en cada PR. Por ejemplo, en GitHub Actions:

name: Visual Diff Check
on: [pull_request]
jobs:
  visual-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run visual diff
        run: |
          npx stirling-pdf-visual-diff --pr ${{ github.event.number }} --output ./diffs
      - name: Upload diffs
        uses: actions/upload-artifact@v3
        with:
          name: visual-diffs
          path: ./diffs

Opciones de configuración

Opción	Descripción	Valor por defecto
--base	Rama base para capturas "antes"	main
--head	Rama de trabajo para capturas "después"	Rama actual
--port	Puerto para el servidor de desarrollo	3000
--output	Directorio para las imágenes generadas	./visual-diffs
--threshold	Umbral de diferencia de píxeles (0-1)	0.1
--concurrency	Número de capturas simultáneas	4

Solución de problemas

• Capturas vacías: Asegúrate de que la aplicación se inicie correctamente en ambos estados.
• Demasiadas diferencias: Ajusta el umbral con --threshold para filtrar ruido.
• Problemas de resolución: Las capturas se toman en 1920x1080 por defecto; usa --width y --height si es necesario.

Limitaciones

• La aplicación debe ser ejecutable localmente o en el entorno de CI.
• Las rutas dinámicas o basadas en sesiones pueden no capturarse correctamente.
• Los cambios en estilos globales pueden afectar a múltiples vistas, generando muchas diferencias.

Contribuciones

Las contribuciones son bienvenidas. Por favor, abre un issue o un PR en el repositorio para sugerir mejoras o reportar errores.

Licencia

Este proyecto está licenciado bajo MIT. Consulta el archivo LICENSE para más detalles.