Visual testing en GitLab CI: integra las pruebas visuales en tu pipeline de GitLab

Visual testing en GitLab CI: integra las pruebas visuales en tu pipeline de GitLab

Las pruebas visuales (visual testing) son un método de verificación automatizada que compara capturas de pantalla de una interfaz web entre dos versiones para detectar las regresiones gráficas (un elemento desplazado, un color modificado, un componente que se desborda de su contenedor).

En Delta-QA usamos GitLab a diario. Nuestros repos, nuestros pipelines, nuestras merge requests, nuestro CI/CD: todo funciona sobre GitLab. No es una elección por defecto: es una elección deliberada por una plataforma que ofrece un pipeline integrado de forma nativa, un registro de contenedores y una filosofía DevOps coherente de punta a punta.

Cuando hablamos de pruebas visuales en GitLab CI, no regurgitamos una documentación que hubiéramos leído la víspera. Compartimos lo que hemos aprendido usándolo de verdad. Este artículo cubre los enfoques disponibles, las particularidades de GitLab CI que afectan a las pruebas visuales y cómo obtener un pipeline de regresión visual fiable.

Lo esencial en una página (definición, automatización sin código, criterios para elegir una herramienta): Pruebas de regresión automatizadas, sin código.

¿Aún no estás listo para tocar tu .gitlab-ci.yml? Empieza con las pruebas visuales fuera del pipeline: Delta-QA compara tus pantallas sin código, con una cuenta gratuita y sin tarjeta bancaria. Probar Delta-QA gratis →

Por qué GitLab CI se presta bien a las pruebas visuales

GitLab CI tiene características que lo hacen especialmente adecuado para las pruebas visuales, características que los usuarios de GitHub Actions o Jenkins no tienen por defecto.

Los artefactos nativos

GitLab CI gestiona de forma nativa los artefactos de pipeline. Cuando una prueba visual produce informes HTML, imágenes de diff o capturas de pantalla, los declaras como artefactos y son accesibles directamente desde la interfaz de la merge request. No hace falta un servicio externo para almacenar y consultar los resultados.

Es una ventaja infravalorada. Con GitHub Actions, debes configurar una subida de artefacto aparte o usar un servicio de terceros para hacer accesibles los resultados. Con GitLab, es nativo.

Los entornos de revisión

GitLab ofrece las Review Apps: entornos efímeros desplegados automáticamente para cada merge request. Tu aplicación funciona en un entorno dedicado, accesible mediante una URL temporal. Es el entorno ideal para las pruebas visuales: estable, aislado y representativo de producción.

Los runners autogestionados

GitLab permite usar runners alojados en tu propia infraestructura. Para las pruebas visuales es crucial: controlas el entorno de renderizado (SO, fuentes, GPU), lo que reduce los falsos positivos debidos a las diferencias de entorno. Nosotros usamos runners dedicados con una configuración fija para garantizar la reproducibilidad de las capturas.

El registro de contenedores integrado

Cada proyecto de GitLab tiene un registro de contenedores. Puedes almacenar allí una imagen Docker preconfigurada para las pruebas visuales (con las fuentes adecuadas, el navegador adecuado, las dependencias adecuadas) y usarla como base de tus jobs de prueba. Eso elimina una fuente importante de inestabilidad.

Los enfoques para las pruebas visuales en GitLab CI

Playwright en un job de GitLab CI

Playwright es la herramienta open source más robusta para las pruebas visuales en CI. Su método nativo toHaveScreenshot() gestiona la captura, la comparación y los reintentos automáticos.

La integración con GitLab CI. Creas un job en tu .gitlab-ci.yml que usa la imagen Docker oficial de Playwright, ejecuta tus pruebas y publica los resultados como artefactos. Los informes HTML de Playwright se pueden consultar directamente en GitLab.

Para la estructura exacta del archivo YAML, pregunta a tu copiloto de IA (es imbatible en la sintaxis de GitLab CI, es más o menos lo único en lo que no alucina (todavía)). Más en serio, la documentación oficial de Playwright para entornos CI es tu mejor referencia.

Lo que funciona bien. La imagen Docker oficial de Playwright incluye todos los navegadores y las dependencias de sistema necesarias. Combinada con el registro de contenedores de GitLab, puedes crear una imagen derivada con tus fuentes y tus configuraciones específicas. Los artefactos de GitLab hacen accesibles los informes de prueba sin configuración adicional.

Los límites en el contexto de GitLab. Las baselines deben generarse en el entorno de CI, no en local. Es una regla universal de las pruebas visuales, pero GitLab lo facilita: puedes disparar un pipeline manualmente para regenerar las baselines. La gestión de las baselines en Git sigue siendo un desafío (archivos binarios, conflictos de merge), pero GitLab LFS está integrado de forma nativa.

Percy con GitLab CI

Percy (BrowserStack) ofrece una integración oficial con GitLab CI. El SDK de Percy captura los snapshots durante tu pipeline y los envía a la nube de Percy para su comparación y revisión.

Lo que funciona. Percy detecta automáticamente la rama y la merge request de GitLab. Los resultados aparecen como un estado externo en tu MR. El cross-browser se gestiona en la nube.

Los límites. La tarifa por snapshot sigue siendo un tema. Y añades una dependencia externa a tu pipeline: si Percy no está disponible, tu check se queda en espera. Para un equipo que ha elegido GitLab precisamente para controlar su infraestructura, esta dependencia externa puede ser contradictoria con la filosofía.

BackstopJS en GitLab CI

BackstopJS funciona en GitLab CI mediante su imagen Docker oficial. Los informes HTML encajan perfectamente con el sistema de artefactos de GitLab.

Lo que funciona. El informe HTML de BackstopJS es uno de los más visuales y legibles del ecosistema. Publicado como artefacto de GitLab, se puede consultar directamente en el navegador desde la interfaz de la MR. La configuración por escenarios JSON es explícita y versionable.

Los límites. El proyecto ha atravesado períodos de mantenimiento intermitente (comprueba la actividad reciente antes de comprometerte). La configuración puede volverse verbosa en aplicaciones complejas, y debes gestionar a mano la iteración sobre tus páginas o componentes.

Delta-QA en GitLab CI: el SDK Vision

Delta-QA entra en un pipeline de GitLab CI a través de tus pruebas Playwright, con el SDK Vision.

Cómo funciona. Guardas la clave de API en una variable CI/CD enmascarada (DELTAQA_API_KEY) y añades vision.check() en las páginas que tus pruebas deben verificar. El job lanza npx playwright test como de costumbre. Por cada check, Delta-QA compara la página con su referencia como lo haría el ojo humano: detecta los elementos que han cambiado y los nombra en el informe.

Lo que es distinto. Sin baselines que almacenar en tu repo: las referencias viven en tu espacio de Delta-QA, una por rama; el SDK no lee ni git ni la CI: una línea de tu job le da la rama, la rama base y el commit. Una diferencia sin juzgar hace fallar el job, y su log da el enlace del informe, que dice qué elemento ha cambiado; allí se juzga «Intencionado» o «Error». Las pruebas que indican el mismo commit forman una versión, aunque estén repartidas en varios jobs en paralelo.

Y sin código. Los recorridos grabados en Delta-QA por el equipo de QA se juzgan en el mismo espacio. El SDK cubre Playwright en TypeScript y JavaScript, sobre Chromium; se ofrece en primer lugar en acceso anticipado, el acceso se solicita desde su página.

Antes de escribir el menor job de CI, mide lo que las pruebas visuales detectan en tus páginas. Delta-QA captura y compara tus pantallas en unos clics, con una cuenta gratuita y sin tarjeta bancaria. Probar Delta-QA gratis →

Las particularidades de GitLab CI que conviene conocer para las pruebas visuales

La caché vs los artefactos

Es una distinción que muchos confunden. La caché de GitLab CI se comparte entre los pipelines de un mismo proyecto (sirve para acelerar los jobs: dependencias npm, navegadores de Playwright). Los artefactos son los outputs de un job concreto: los informes de prueba, las capturas, los diffs.

Para las pruebas visuales, usa la caché para los navegadores y las dependencias, y los artefactos para los resultados de las pruebas. No caches nunca las baselines (deben vivir en el repo para versionarse con el código).

Los stages y las dependencias entre jobs

GitLab CI organiza los jobs en stages secuenciales. Las pruebas visuales deben estar en un stage que se ejecute después del despliegue de tu Review App. Un patrón habitual:

  1. build: compilación de la aplicación
  2. deploy-review: despliegue de la Review App
  3. test-visual: prueba visual sobre la Review App
  4. cleanup: eliminación del entorno

La directiva needs de GitLab CI permite crear dependencias explícitas entre jobs sin pasar por los stages secuenciales, lo que puede acelerar tu pipeline.

Las variables de entorno protegidas

Los tokens de API de los servicios en la nube (Percy, Chromatic) deben almacenarse como variables CI/CD en GitLab. Cuidado: las variables protegidas solo están disponibles en las ramas protegidas. Si tus feature branches no están protegidas, las pruebas visuales con un servicio en la nube fallarán en silencio: una trampa clásica.

Los límites de tiempo y de memoria

Las pruebas visuales son voraces en recursos. El renderizado de páginas en un navegador headless consume memoria, y la comparación de imágenes lleva tiempo. Los runners compartidos de GitLab.com tienen límites de tiempo (generalmente una hora por job) y de memoria. Para suites de pruebas visuales considerables, se recomiendan los runners autogestionados con recursos dedicados.

Construir un pipeline de pruebas visuales robusto

Este es el enfoque que recomendamos, basado en nuestra propia experiencia.

Empieza pequeño y acotado

No pruebes visualmente todas tus páginas desde el primer día. Identifica las cinco a diez páginas más críticas (las que tus usuarios ven primero, aquellas donde una regresión visual tiene más impacto en el negocio). Amplía después progresivamente.

Usa Review Apps como objetivo

En lugar de lanzar un servidor local en tu job de CI, despliega una Review App y pruébala. La ventaja: el entorno es estable, accesible y representativo. El inconveniente: añades la duración del despliegue al pipeline. El compromiso merece la pena.

Estabiliza tu entorno de renderizado

Crea una imagen Docker dedicada a las pruebas visuales, almacenada en tu registro de GitLab. Incluye las fuentes que usa tu aplicación, la versión exacta del navegador y todas las dependencias de sistema. Versiona esta imagen. Cuando tu entorno de renderizado está fijo, los falsos positivos caen drásticamente.

Empieza en modo no bloqueante

Configura tu job de pruebas visuales con allow_failure: true durante las primeras semanas. Así tu equipo se familiariza con los resultados sin que las pruebas visuales bloqueen las merge requests. Una vez establecida la confianza y controlados los falsos positivos, pasa a modo bloqueante.

Notifica con inteligencia

GitLab CI puede enviar notificaciones por distintos canales (Slack, correo, webhook). Configura las notificaciones de pruebas visuales para que solo avisen en los fallos, no en los éxitos. El objetivo es llamar la atención cuando es necesario, no ahogar a tu equipo bajo los mensajes.

Aprovechar los artefactos como sistema de referencias

Los artefactos de GitLab no sirven solo para publicar informes: bien organizados, se convierten en la columna vertebral de tu estrategia de referencias. Dos prácticas marcan la diferencia.

Estructura los artefactos de forma legible

No amontones todas tus capturas en plano. Crea un árbol claro: una carpeta por página probada, que contenga dentro la captura de referencia, la captura actual y el diff. Coloca un informe HTML en la raíz para navegar entre los resultados. Cuando una prueba falla, quien revisa abre el explorador de artefactos integrado de GitLab, navega a la página afectada y ve de inmediato la diferencia sin salir de la interfaz.

Usa los artefactos de main como referencias

En lugar de almacenar las baselines en el repo, puedes aprovechar los artefactos del último pipeline exitoso en la rama principal como juego de referencias. GitLab CI permite descargar los artefactos de un job concreto en una rama concreta mediante su API.

En concreto, el job de pruebas visuales de tu rama feature empieza descargando las capturas de referencia desde los artefactos del último pipeline de main. Luego captura las pantallas de la rama feature, compara los dos juegos y almacena sus propios resultados como artefactos del pipeline actual. Ninguna baseline binaria contamina tu historial de Git.

Una política de retención en dos niveles

La duración de retención de los artefactos de GitLab es configurable, y para las pruebas visuales funciona bien una política en dos niveles:

  • Rama principal: 30 días (o más). Estos artefactos sirven de referencias estables para todas las comparaciones.
  • Ramas feature: 7 días. El tiempo de que la merge request se trate y se fusione.

Ajusta según tu ritmo: un equipo con ciclos largos (ramas que viven varias semanas) necesitará una retención más amplia en main, y tendrá que hacer rebase con regularidad o volver a descargar las referencias más recientes en cada run para evitar comparar con baselines caducadas.

FAQ

¿Es GitLab CI tan bueno como GitHub Actions para las pruebas visuales?

Para las pruebas visuales en concreto, GitLab CI tiene ventajas nativas: los artefactos integrados, las Review Apps, el registro de contenedores y los runners autogestionados. Estas funciones facilitan la puesta en marcha de un entorno de pruebas visuales estable y reproducible. GitHub Actions tiene su propio marketplace rico, pero algunas de estas funciones requieren configuraciones adicionales.

¿Hacen falta runners autogestionados para las pruebas visuales en GitLab CI?

No es obligatorio, pero se recomienda mucho. Los runners compartidos de GitLab.com funcionan, pero su configuración de hardware variable puede introducir diferencias de renderizado. Un runner autogestionado con una configuración fija (fuentes, navegador, resolución) elimina esa fuente de falsos positivos y suele ofrecer mejor rendimiento.

¿Cómo gestionar las baselines de pruebas visuales en un repo de GitLab?

Si usas Playwright o BackstopJS, las baselines (archivos PNG) viven en tu repo. Activa GitLab LFS para evitar que los archivos binarios engorden tu historial de Git. Para los conflictos de merge en las baselines, la estrategia más simple es aceptar las nuevas baselines de la rama de origen y regenerar si es necesario. Con Delta-QA, las baselines las gestiona la herramienta y no contaminan tu repo.

¿Se pueden usar las Review Apps de GitLab como entorno de pruebas visuales?

Sí, y es incluso el enfoque que recomendamos. La Review App ofrece un entorno estable y aislado para cada merge request. Tu job de pruebas visuales espera a que la Review App esté desplegada, captura las pantallas en la URL temporal y compara con las referencias. Es más fiable que un servidor lanzado al vuelo en el job de CI.

¿Funcionan las pruebas visuales en GitLab CI con monorepos?

Sí. GitLab CI soporta reglas condicionales que permiten disparar las pruebas visuales solo si se han modificado los archivos front-end. Combinado con la directiva only:changes, evitas ejecutar pruebas visuales inútiles cuando solo ha cambiado el backend. Es esencial para mantener un pipeline rápido en un monorepo.

¿Cuál es la mejor imagen Docker para las pruebas visuales en GitLab CI?

La imagen oficial de Playwright (mcr.microsoft.com/playwright) es un excelente punto de partida. Incluye los navegadores y las dependencias de sistema. Para un entorno aún más estable, crea una imagen derivada que añada las fuentes de tu aplicación y fije las versiones exactas. Almacénala en el registro de contenedores de tu proyecto de GitLab para un acceso rápido.

Conclusión

GitLab CI es una plataforma naturalmente adaptada a las pruebas visuales. Sus funciones nativas (artefactos, Review Apps, registro de contenedores, runners autogestionados) resuelven problemas que otras plataformas de CI obligan a tratar a mano.

Pero la plataforma no lo hace todo. Las pruebas visuales en CI siguen siendo un desafío de ingeniería: estabilizar el renderizado, gestionar las baselines, tratar los falsos positivos y construir un flujo de revisión que funcione para todo el equipo.

Si estás en GitLab y quieres añadir las pruebas visuales a tu pipeline sin la complejidad de los scripts de prueba y de la gestión manual de baselines, Delta-QA está diseñado para integrarse de forma nativa en tu flujo de GitLab CI.

¿Listo para dar fiabilidad a tus merge requests con las pruebas visuales? Lanza tu primera comparación con Delta-QA, gratis y sin tarjeta bancaria, antes incluso de tocar tu .gitlab-ci.yml. Probar Delta-QA gratis →