Pruebas visuales de regresión para actualizaciones de TYPO3 con BackstopJS

Poner el sitio web a prueba después de una actualización de TYPO3 es una de las tareas que más tiempo y estrés consumen en el trabajo diario de un integrador. Hacer clic manualmente en cada página, comprobar cada tipo de contenido, comprobar cada vista... todo esto puede consumir rápidamente horas o incluso días. Y, sin embargo, la sensación de inquietud se apodera de uno: ¿Realmente lo tengo todo?

Por ello, muchos integradores crean páginas de prueba especiales en las que se agrupan todos los elementos de contenido: un enfoque pragmático para comprobar los componentes más importantes de un vistazo. Pero ni siquiera esto cubre todas las eventualidades: diferentes contextos de plantilla, estructuras anidadas, páginas especiales con casos especiales. La página de prueba muestra que el elemento texto-imagen funciona, pero no si tiene el mismo aspecto en todas las páginas reales.

En los últimos meses, he desarrollado una herramienta que alivia precisamente este dolor: Un flujo de trabajo automatizado para pruebas de regresión visual con BackstopJS. Lo que solía ser manual y propenso a errores es ahora estructurado y reproducible.

Sí, lo sé: si tienes una tubería CI/CD totalmente automatizada con Playwright, Chromatic y Kubernetes, no necesitas esto. Cualquiera que haya estado usando Percy o Applitools en una configuración empresarial durante años no lo necesita de todos modos. Esta herramienta es para los demás - los autónomos y pequeñas agencias que no tienen un departamento de DevOps y todavía quieren probar profesionalmente. Sin tres semanas de tiempo de configuración.

El problema: las pruebas manuales después de las actualizaciones son ineficientes

Cualquiera que lleve a cabo actualizaciones de TYPO3 conoce el proceso: actualización de Composer, migración de la base de datos, borrado de la caché... esa es la parte técnica. Pero luego viene la prueba de estrés real: ¿Sigue funcionando el sitio web como antes?

El método clásico es el siguiente: Haces clic en el sitio web, abres diferentes páginas, compruebas diferentes elementos de contenido, compruebas diferentes plantillas. Para un sitio web pequeño de 20 páginas, esto sigue siendo manejable. Con 200 o 500 páginas, se convierte en un calvario.

Y no se trata sólo de errores evidentes, como diseños completamente rotos. Los errores más desagradables son los sutiles: Un elemento de contenido que se ha deslizado dos píxeles a la derecha. Un espacio que falta entre el titular y el texto. Una imagen que de repente ya no está alineada a la izquierda, sino centrada.

Estas desviaciones visuales sólo resultan evidentes cuando se miran de cerca, o cuando el cliente llama y pregunta: "¿Por qué esto tiene ahora un aspecto diferente?".

Pruebas de regresión visual: la idea que las sustenta

Las pruebas de regresión visual comparan capturas de pantalla de un sitio web antes y después de un cambio. El software toma imágenes del estado actual (referencia) y del nuevo estado (prueba), las superpone y marca todas las diferencias con precisión de píxeles.

Lo que la herramienta no puede hacer: Decirle si el cambio es intencionado o un error. Pero te muestra cada desviación - y tú decides si está bien o necesita ser arreglada.

BackstopJS es una herramienta de este tipo para pruebas de regresión visual. Se basa en Node.js, utiliza navegadores headless (Chrome/Firefox) y crea automáticamente capturas de pantalla en diferentes resoluciones. Los informes generados muestran de un vistazo qué páginas han cambiado y cómo son las diferencias.

Por qué he creado mi propia herramienta

BackstopJS es potente, pero no inmediatamente listo para grandes sitios web TYPO3. La configuración manual puede ser engorrosa, especialmente con docenas o cientos de URLs.

Es por eso que he desarrollado un flujo de trabajo automatizado que resuelve tres problemas clave:

1. rastreo automático de URL

En lugar de recopilar las URL manualmente, un script PHP rastrea el sitio web y escribe todas las URL encontradas en un archivo CSV. Como alternativa, desde la versión 1.1.0 también se puede leer un mapa del sitio XML existente. Esto es mucho más rápido que un rastreo completo, pero, por supuesto, sólo funciona si el sitio web ofrece un mapa del sitio. Esto ahorra tiempo y garantiza que no se pase por alto ninguna página.

2. procesamiento por lotes para sitios web grandes

Crear capturas de 500 URL al mismo tiempo sobrecargaría el sistema. La herramienta divide automáticamente las URL en lotes manejables de 40 páginas y los procesa uno tras otro.

3. gestión estructurada del flujo de trabajo

Una herramienta de línea de comandos le guía a lo largo de todo el proceso: activar el siguiente lote, crear las capturas de pantalla, comparar los resultados, marcar el lote como completo. Esto le permite realizar un seguimiento de grandes proyectos.

Mi flujo de trabajo típico para las actualizaciones de TYPO3

Cómo utilizo la herramienta en la práctica:

Paso 1: Crear una copia local

Creo una copia local del proyecto con DDEV, realizo la actualización y me aseguro de que todo está técnicamente en funcionamiento. Actualización de Composer, migración de la base de datos, personalización del código: los pasos habituales.

Paso 2: Rastrear el sitio web

Utilizo el script de rastreo para obtener todas las URL del sitio web activo. Aquí tengo dos opciones:

Opción 1: Realizar un rastreo completo

ddev exec php crawler.php --url example.com>

El script rastrea el sitio web, filtra automáticamente los archivos no HTML (PDFs, imágenes) y escribe todas las páginas encontradas en un archivo CSV. Todo se ejecuta en tiempo real: las URL se escriben inmediatamente, sin problemas de memoria con sitios grandes.

Al final obtengo un resumen detallado de los errores: qué páginas devuelven 404, cuáles 403, dónde hubo tiempos de espera. Esto ya me puede dar algunas pistas iniciales sobre dónde debería echar un vistazo más de cerca.

Opción 2: Leer el mapa del sitio XML (desde la versión 1.1.0)

ddev exec php crawler.php --sitemap example.com/sitemap.xml

Si el sitio web ofrece un mapa del sitio XML, esta opción es mucho más rápida. El script lee el mapa del sitio y extrae todas las URL directamente, sin pasar por cada enlace de cada página. También funciona con sitemaps anidados: Los grupos de sitemaps se reconocen automáticamente y se ejecutan de forma recursiva.

Paso 3: Generar escenarios de prueba

Utilizo las URL recopiladas para crear automáticamente escenarios BackstopJS:

ddev exec php create-backstop-scenarios.php \\
  --test=http://example.ddev.site
  --reference=https://example.com

El script divide las URL en lotes y crea un archivo de escenario independiente en la carpeta scenarios/pending/ para cada lote.

Paso 4: Probar lote por lote

Ahora viene la parte interactiva. Activo el primer lote:

ddev exec php gestionar-escenarios.php siguiente

Luego creo las capturas de pantalla de referencia desde el sitio en vivo y las capturas de pantalla de prueba desde mi instancia local:

backstop referencia --config ./backstop.js
backstop test --config ./backstop.js

BackstopJS abre automáticamente un informe HTML en el navegador. Allí puedo ver para cada URL

• Una imagen antes (sitio en vivo)
• Una imagen después (instancia local)
• Una vista diff con las diferencias resaltadas

Repaso los resultados y decido para cada desviación: ¿Se trata de un error o de un cambio intencionado? Si todo está bien, marco el lote como hecho:

ddev exec php manage-scenarios.php hecho

A continuación, activo el siguiente lote y repito el proceso. Con 200 URL, esto significa cinco ejecuciones con 40 URL cada una, estructuradas y sin perder la visión de conjunto.

Lo que la herramienta realmente hace por mí

Ahorro de tiempo

Por supuesto, en el caso de sitios web grandes, todo el proceso puede llevar de una a dos horas. Pero comparado con hacer clic manualmente en más de 200 páginas, es una broma. Y sobre todo: el programa no pasa nada por alto. Se acabó eso de "no lo había visto".

Seguridad

Tengo una buena sensación cuando subo el sitio web probado al entorno de producción. Las capturas de pantalla muestran en blanco y negro: se ve igual que antes. O muestran dónde hay problemas, y así puedo solucionarlos antes de la puesta en marcha.

Documentación

Las capturas de pantalla y los informes también son útiles más adelante. Si un cliente me dice: "Esto parecía diferente antes" meses después de la actualización, puedo sacar las antiguas capturas de pantalla de referencia y mostrárselas: No, era exactamente igual.

Los límites de la herramienta

Quiero ser sincero: La herramienta no es perfecta. Tiene puntos débiles.

Dependencia de DDEV

El flujo de trabajo se basa actualmente en DDEV. Esto significa que usted necesita ya sea DDEV o un PHP nativo en su sistema. Si trabaja con otras configuraciones, tendrá que hacer ajustes.

Requiere interpretación manual

La herramienta le muestra todas las desviaciones, incluso las inofensivas. Un banner cookie que se comporta de forma diferente la primera vez que se llama. Un elemento dinámico que carga contenido aleatorio. Una marca de tiempo que es naturalmente diferente. Tiene que decidir usted mismo qué es relevante y qué no.

Esfuerzo de configuración para sitios complejos

Si un sitio web tiene muchos elementos dinámicos (áreas de inicio de sesión, formularios, componentes con mucho JavaScript), deberá personalizar la configuración de BackstopJS. Ocultar ciertos selectores, aumentar los retardos, definir interacciones. Puede ser complicado.

Sin embargo, para mis propósitos, la herramienta funciona tan bien que la utilizo para cada actualización importante de TYPO3.

¿Para quién es adecuada la herramienta?

Si gestiona sitios web TYPO3 y realiza actualizaciones con regularidad, merece la pena echar un vistazo a la herramienta. Ya sea como autónomo con proyectos más pequeños o en una agencia con clientes más grandes - las pruebas estructuradas siempre ayudan.

Es particularmente útil si usted

• gestiona sitios web con muchas páginas y diferentes plantillas
• está actualizando a través de varias versiones de TYPO3 (por ejemplo, de 9 a 12)
• tiene clientes que prestan mucha atención a la coherencia visual
• desea profesionalizar sus procesos de prueba

Los requisitos técnicos son sencillos: debe ser capaz de trabajar con DDEV, Docker y la línea de comandos. BackstopJS puede instalarse con npm install -g backstopjs. Si ya estás trabajando con esta pila, la curva de aprendizaje es plana.

Pruebe la herramienta y proporcione comentarios

El repositorio está disponible públicamente en GitHub: https://github.com/wwagner-net/create-backstop-scenarios

Allí encontrarás

• Un LÉEME detallado con todos los comandos
• Instrucciones paso a paso para empezar
• Explicaciones de todos los scripts y opciones
• Ejemplos para varios casos de uso

La herramienta está bajo licencia MIT, puedes usarla, adaptarla y extenderla libremente.

Me encantaría que la probaras y me contaras tu experiencia:

• ¿Funciona el flujo de trabajo en tus proyectos?
• ¿Dónde se atasca?
• ¿Qué echas en falta?
• ¿Qué mejoras le gustaría ver?

Puedes enviarme tus comentarios a través de un issue en GitHub. Sigo desarrollando la herramienta y agradezco cualquier sugerencia.

Conclusión: No es una cura milagrosa, pero es una ayuda útil

Las pruebas de regresión visuales no sustituyen a las pruebas manuales, pero las hacen mucho más eficientes. En lugar de navegar a ciegas por cientos de páginas, se obtiene una visión estructurada de todos los cambios visuales.

La herramienta que he desarrollado hace que BackstopJS sea manejable para proyectos TYPO3 más grandes. Automatiza el rastreo, organiza el procesamiento por lotes y le guía a través del flujo de trabajo de una manera estructurada.

¿Es perfecto? No. ¿Tiene puntos débiles? Sí. Pero me ayuda a dormir mejor cada vez que actualizo TYPO3, porque sé que no he pasado por alto nada importante.

Si pruebas la herramienta, cuéntame cómo te ha ido. Estoy deseando conocer tus experiencias.