Pruebas de regresión visual en un design system con navegador fijo

El test de regresión visual de un design system es una comprobación que dibuja cada estado de cada componente, compara cada imagen con una baseline aprobada y hace fallar la pull request cuando cambian píxeles que nadie quería cambiar. Detecta lo que la revisión de código no ve: un token de padding que se toca para un botón y mueve otros cuarenta componentes, un peso de fuente que se pierde tras actualizar una dependencia, un tema oscuro que se queda sin un borde.
Al final de esta guía la librería tiene uno. En cada pull request se captura cada story de Storybook en un único navegador fijo, con umbrales ajustados al componente. En una rama sin cambios la comprobación no encuentra diferencias; un cambio hecho a propósito muestra justo las stories que toca, y ninguna más.
Qué hace falta antes de empezar
- Una librería de componentes con sus stories, una por cada estado que merezca protección (variante, tamaño, tema, deshabilitado, error).
- Un pipeline de CI que se lance en cada pull request.
- Docker en la CI, o un servicio externo que se encargue del renderizado.
- Una persona concreta que apruebe los cambios de baseline. Sin responsable, cada diferencia la acepta quien tenga más prisa.
Paso 1: cada estado, una story
La unidad del test visual es la story. La documentación de Storybook lo dice tal cual: con los tests visuales activados, cada story se convierte automáticamente en un test. Así que la cobertura se decide al escribir las stories. Un botón con tres variantes, tres tamaños y dos temas tiene 18 estados, y una story que los pone todos en una cuadrícula cuesta menos que 18 stories sueltas y los enseña igual.
En la primera vuelta, las páginas se quedan fuera. Una página completa mezcla una docena de componentes con contenido real, y una diferencia ahí puede significar cualquier cosa. Las stories de componente fallan con nombre: ha cambiado Button/Primary/Dark, y quien revisa sabe dónde mirar.
Una cuenta rápida fija el presupuesto del paso 5. Cuarenta componentes con una media de seis stories cada uno, en dos temas, son 480 capturas por ejecución completa.
Paso 2: fijar el navegador que dibuja la baseline
Es el paso que más se saltan las suites inestables. La guía de comparaciones visuales de Playwright avisa de que el renderizado del navegador cambia con el sistema operativo, la versión, la configuración, el hardware, la fuente de alimentación y el modo headless, y de que para tener capturas coherentes hace falta el mismo entorno que generó la baseline. El suavizado de fuentes de macOS y el de Linux se diferencian lo suficiente como para hacer fallar cualquier story con texto.
Por eso la baseline nunca se genera en un portátil. Se genera en el mismo contenedor que usa la CI. Playwright publica una imagen oficial para esto, atada a cada versión (mcr.microsoft.com/playwright:v1.64.1-noble mientras escribimos, según su página sobre Docker). En local, el comando de actualización también se lanza dentro de esa imagen:
docker run --rm -v $(pwd):/work -w /work mcr.microsoft.com/playwright:v1.64.1-noble npx playwright test --update-snapshotsPlaywright pone a cada baseline el nombre del navegador y de la plataforma (chromium-linux), así que una baseline de Mac y una de Linux no se confunden. La imagen se actualiza en una pull request aparte, la baseline se regenera en esa misma pull request y ahí no cambia nada más.
Paso 3: congelar todo lo que se mueve
Dos ejecuciones del mismo código tienen que dar la misma captura. Todo lo que depende de la hora, del azar o de la red lo impide. Una parte ya la resuelve toHaveScreenshot de Playwright, según su referencia de aserciones:
- Las animaciones vienen desactivadas por defecto. Las animaciones y transiciones CSS finitas se adelantan hasta el final; las infinitas vuelven a su estado inicial.
- El cursor de texto se oculta por defecto.
- La aserción espera a dos capturas consecutivas idénticas antes de comparar, y así absorbe los movimientos tardíos del layout.
El resto depende de las stories. Se fija la fecha que ve el componente. Se pone semilla a cualquier dato aleatorio. Los avatares y las imágenes se sirven desde archivos locales. Antes de la captura se espera a document.fonts.ready, para que una fuente de reserva nunca acabe en una baseline. Para el contenido que tiene que seguir vivo, como una hora relativa, la opción mask tapa el locator con un recuadro sólido. Conviene usarla poco: un área enmascarada es un área que el test ya no comprueba.
Paso 4: ajustar el umbral al componente
Dos números deciden cuándo falla una diferencia. threshold marca cuánto tiene que cambiar un píxel para contar, medido en el espacio de color YIQ de 0 (estricto) a 1 (permisivo), con 0,2 por defecto. maxDiffPixels o maxDiffPixelRatio marca cuántos píxeles cambiados tolera el test.
El error habitual es una proporción única para toda la suite. Una captura de 1280 × 800 tiene 1.024.000 píxeles, así que una proporción del 1 % tolera 10.240 píxeles cambiados. Un botón de 120 × 40 ocupa 4.800. Con esa regla, un botón puede desaparecer de una página y el test sigue pasando. Las stories recortadas al componente mantienen las cuentas claras: en una captura pequeña, un maxDiffPixels absoluto y bajo (unas decenas de píxeles para el ruido del antialiasing) detecta un borde que cambia un píxel e ignora las oscilaciones por debajo del píxel.
El umbral de una story concreta solo se sube con un comentario que explique el motivo, igual que cuando se desactiva una regla de lint en una línea.
Paso 5: elegir dónde se ejecutan las capturas
Hay dos opciones razonables, y decide la cuenta de capturas del paso 1.
En la nube, con Chromatic. Lo lleva el propio equipo de Storybook, la revisión se hace en una interfaz web y los planes de pago prueban también Safari, Firefox y Edge. La página de precios de Chromatic recoge un plan gratuito con 5.000 capturas al mes, Starter a 179 dólares al mes por 35.000 y Pro a 399 dólares por 85.000. TurboSnap solo captura las stories afectadas por un cambio, y las no afectadas cuentan como una fracción de captura (la página de precios equipara 35.000 capturas facturadas a 175.000 turbosnaps, un quinto cada una). Con 480 capturas por ejecución completa, el plan gratuito da para unas diez ejecuciones completas al mes; con TurboSnap activado, una pull request que toca dos componentes cuesta mucho menos.
En casa, con Playwright. Sin factura por captura. Las baselines son archivos PNG en el repositorio, la revisión es el informe HTML de Playwright y los navegadores cubiertos son los que figuren en la configuración. El coste pasa al espacio en git y al tiempo de quien lee los informes.
Por defecto elegimos Playwright en casa para librerías de menos de unos cientos de stories con un solo responsable, y un servicio en la nube cuando contribuyen varios equipos y hace falta una cola de revisión compartida. Los pasos 1 a 4 no cambian en ninguno de los dos casos.
Paso 6: convertir cada diferencia en una decisión
Un test visual que falla hace una sola pregunta: ¿el cambio era intencionado? La respuesta está en la pull request que lo provocó. Si lo era, esa misma pull request actualiza la baseline y el responsable aprueba la imagen nueva junto a la antigua. Si no lo era, se corrige el código y la baseline se queda como estaba.
Dos reglas mantienen limpia la cola. Las actualizaciones de baseline nunca se agrupan en un commit aparte del tipo «actualizar capturas», porque así se pierde qué cambio de código movió qué imagen. Y una diferencia en un componente compartido es una cuestión de versiones: un layout que se mueve para quien actualiza sin tocar su propio código puede ser un cambio incompatible, como contamos en el artículo sobre cómo versionar un design system.
Cómo comprobar que la suite funciona
- Lanzar la suite dos veces sobre main sin cambios. Las dos ejecuciones tienen que dar cero diferencias. Una story inestable aquí se ignorará para siempre.
- Cambiar un token a propósito, por ejemplo un radio de 6 a 8 píxeles. Tienen que fallar las stories que lo usan, y solo esas.
- Quitar el borde de un componente en una rama de prueba. La comparación tiene que fallar con el nombre de la story de ese componente.
Fallos habituales y cómo corregirlos
- En la CI fallan todas las stories y en local pasan. La baseline viene de otro sistema operativo. Hay que regenerarla dentro del contenedor fijado (paso 2).
- Tras una actualización fallan todas las stories con texto. Con el test runner cambió también la versión del navegador. La baseline se regenera en una pull request que solo contenga esa actualización.
- La misma story falla una vez de cada diez. Algo sigue moviéndose: una fuente web, una imagen con carga diferida, un valor sin semilla. Hay que encontrarlo antes de subir el umbral.
- Ha pasado una regresión real. Revisar las máscaras y la proporción. Una máscara grande o una proporción calculada sobre la página esconden componentes enteros (paso 4).
Los tests visuales son una de las comprobaciones contra el drift que describimos en el artículo sobre cómo se degrada un design system. Ven qué ha cambiado en pantalla. El porqué no lo ven, y para eso está la revisión del paso 6.
Preguntas frecuentes
Compensan desde el día en que un segundo producto usa la librería, porque a partir de ahí un cambio de token llega a pantallas que nadie del equipo de la librería abre. Con menos de 20 componentes y un solo producto que los usa, a menudo basta con un repaso manual en Storybook antes de cada release. Playwright en casa no cuesta nada por captura, así que el único coste real de empezar pronto es escribir una story por estado, algo que la librería necesita igualmente para su documentación.
Chromatic encaja con equipos que quieren una interfaz de revisión compartida, renderizado en varios navegadores sin tener que mantenerlo y TurboSnap para capturar solo lo que toca un cambio; su plan gratuito cubre 5.000 capturas al mes y Starter cuesta 179 dólares al mes por 35.000. Playwright encaja con un único responsable que prefiere no pagar por captura y no tiene problema en revisar un informe HTML, con las baselines guardadas como PNG en git. Los dos se apoyan en lo mismo: una story por estado, datos congelados y umbrales ajustados a cada componente.
No. Una captura enseña cómo se ve un componente en un estado; no dice si un lector de pantalla lo anuncia, si el foco se mueve bien o si un clic ejecuta la acción. Un botón puede verse idéntico y haber perdido su nombre accesible. Las comprobaciones de accesibilidad como axe y los tests de interacción se lanzan junto a la suite visual, sobre las mismas stories, para que cada estado quede cubierto por los tres.
Artículos relacionados
1 de septiembre de 2026 · 8 min de lectura
3 de noviembre de 2026 · 9 min de lectura
21 de junio de 2026 · 7 min de lectura