Pruebas de regresión visual: ¿deriva o error?

Un fallo en las pruebas de regresión visual indica que una comparación no cumplió sus reglas configuradas. No identifica la causa. Un archivo de fuente, una versión del navegador, una ventana gráfica o un motor de renderizado distintos pueden mover píxeles sin cambiar el código de la aplicación. BotBrowser proporciona inventarios de fuentes y controles de renderizado basados en perfiles que favorecen la coherencia entre plataformas, pero no garantiza píxeles de glifos idénticos entre motores, no decide si el CSS es correcto ni elige las tolerancias de las capturas.

Resumen

• Compara las dimensiones y los datos de renderizado antes de calcular o aceptar una diferencia entre píxeles.
• Una tolerancia de color decide qué píxeles cuentan como diferentes. Una cantidad o proporción permitida decide cuánta diferencia ya clasificada se acepta.
• Una ejecución controlada de Chrome estándar separó cambios de fuente, ventana gráfica, escala y CSS. Tanto un presupuesto amplio como una tolerancia de color amplia aceptaron un cambio de color deliberado.
• La coincidencia repetida demuestra repetibilidad con los datos registrados. No demuestra que la interfaz, la fuente elegida o la referencia sean correctas.

Contenido

• Separar una comparación fallida de su causa
• Comprobar cuatro fuentes de deriva
• Reproducir un solo cambio cada vez
• Interpretar las capturas controladas
• Elegir por separado la tolerancia de color y el presupuesto
• Decidir entre restaurar investigar o actualizar
• Preguntas frecuentes sobre regresión visual

Separar una comparación fallida de su causa

Empieza por las dimensiones de ambas imágenes decodificadas. Una captura con el doble de anchura y el doble de altura contiene cuatro veces más posiciones de píxel. Compararla directamente con la imagen pequeña no produce una cantidad ordinaria de diferencias entre posiciones correspondientes. Reducirla introduce una operación de remuestreo y otra fuente de diferencias. Registra primero la incompatibilidad de dimensiones; adopta una normalización explícita solamente si forma parte del contrato que la prueba pretende verificar.

Después compara el registro de captura: versión del ejecutable, sistema operativo, modo de renderizado, viewport en píxeles CSS, deviceScaleFactor, fuentes disponibles y revisión de la aplicación. Una etiqueta de contenedor sirve como referencia, pero una etiqueta modificable no demuestra por sí sola que esos datos se mantuvieran iguales. Conserva la versión resuelta del navegador y la identidad de los archivos tipográficos junto a la referencia. Una comparación con datos diferentes exige una investigación distinta de otra con los mismos datos.

Examina luego dónde aparece la diferencia. Los cambios con forma de texto sugieren una cuestión de fuente o composición; una región rectangular aislada sugiere un estilo o contenido local; los cambios extensos pueden implicar distribución, escala u otro dato de renderizado compartido. Son indicios, no diagnósticos. Cambiar una etiqueta del producto también altera píxeles con forma de texto, y sustituir una fuente puede modificar la distribución mucho más allá de los propios glifos.

Las comprobaciones de captura ya cubren la preparación y sus metadatos. Declara esos datos en lugar de tratar la aserción de imagen como detector de preparación de la aplicación. La aserción de Playwright espera que dos capturas consecutivas coincidan antes de comparar la última con la referencia. Dos fotogramas estables aún pueden mostrar una tabla vacía, una fuente alternativa o un error de carga. La condición de preparación de la aplicación debe nombrar el estado que se quiere capturar.

Separa tres preguntas en el registro del fallo: si se utilizaron datos comparables, qué regiones cambiaron y si la interfaz modificada es aceptable. Las dos primeras son mediciones. La tercera requiere el contrato de la aplicación o una revisión de diseño. Actualizar automáticamente la referencia no responde ninguna: solamente cambia la imagen con la que se comparará en el futuro.

Comprobar cuatro fuentes de deriva

Versión del navegador y modo de captura

Fija el ejecutable empleado para generar la referencia, además de la versión de la biblioteca de automatización. Una actualización del entorno puede seleccionar otro navegador incluido, mientras que el navegador del sistema puede actualizarse independientemente. Registra la versión real durante la captura. Si la referencia procede de otra versión, ejecuta la revisión anterior de la aplicación con el navegador nuevo antes de atribuir el cambio al código de la aplicación.

Incluye también el modo con o sin ventana en el registro. La documentación de comparaciones visuales de Playwright enumera sistema operativo, versión, configuración, hardware, alimentación eléctrica y modo sin ventana entre los factores que afectan al renderizado. Esa advertencia justifica controlar el entorno; no establece que uno de esos factores causara un fallo concreto. Para investigar una actualización hace falta un experimento emparejado entre versiones. La ejecución controlada siguiente no cambia la versión del navegador.

Archivos tipográficos y estado de carga

Un nombre de familia CSS es una solicitud, no una prueba del archivo utilizado para dibujar cada glifo. La fuente solicitada puede faltar, estar cargándose o no incluir un carácter. Una fuente alternativa diferente puede cambiar formas, anchuras y saltos de línea. Registra los archivos suministrados y examina texto representativo después de que se resuelvan las promesas de carga pertinentes. Esperar una fuente no hace aparecer un glifo ausente.

document.fonts.ready corresponde al trabajo de carga tipográfica y composición del documento. No promete que ya se hayan iniciado todas las solicitudes o todo el contenido futuro. Si después la aplicación inserta otra región, espera su propia condición de preparación antes de capturarla. Cuando una prueba cambia deliberadamente una fuente, deja que la distribución se recalcule antes de tomar la siguiente imagen. Comparar la imagen antigua con una captura anterior a la aplicación de la fuente nueva confunde el tiempo con la selección tipográfica.

Los controles de fuentes de BotBrowser describen inventarios y renderizado basados en perfiles sin prometer resultados idénticos para todos los glifos. Las fuentes del sistema siguen importando cuando el modo elegido permite alternativas del equipo o utiliza sus fuentes reales. Por tanto, declarar un inventario y definir una política de comparación resuelve problemas diferentes; ninguna de las dos cosas vuelve innecesaria la otra.

Ventana gráfica y factor de escala

La anchura de la ventana modifica la distribución adaptable y el ajuste del texto. El factor de escala cambia la relación entre coordenadas CSS y píxeles de imagen. Registra ambos en lugar de usar la anchura de la captura como sustituto del tamaño de la ventana. Una captura de página completa también puede crecer porque creció el documento, aunque la ventana no cambiara.

Comprueba los valores observados dentro de la página además de las opciones solicitadas a la automatización. Una referencia generada con una anchura CSS y una imagen actual generada con otra deben clasificarse primero como incompatibilidad geométrica. Aumentar los píxeles diferentes permitidos no restaura las condiciones de distribución de la referencia original. Si varios tamaños son proyectos intencionados, conserva referencias e identidades de proyecto separadas.

Motor gráfico y renderizado del equipo

Un valor de GPU declarado no demuestra que el mismo rasterizador dibujara la imagen. Los rasterizadores de software y las rutas gráficas del equipo pueden producir píxeles diferentes para operaciones equivalentes. La documentación del motor gráfico de Linux de BotBrowser diferencia explícitamente estos motores y sus resultados. Una cadena de identificación del renderizador no basta como procedencia de una referencia exacta.

Conserva la configuración del motor cuando el entorno la exponga y evita mezclar referencias generadas en tipos de ejecutores distintos. Si sospechas de un controlador o motor nuevo, realiza un experimento emparejado manteniendo constantes aplicación, fuentes y geometría. El experimento de aislamiento siguiente no cambia controladores ni demuestra una causa de GPU. Su finalidad es mostrar cómo se clasifica un cambio conocido antes de relajar una tolerancia.

Reproducir un solo cambio cada vez

Utiliza una página propia con contenido fijo, dos archivos tipográficos locales y ninguna solicitud externa. Captura una referencia y crea grupos separados que solamente cambien la fuente seleccionada, la anchura de la ventana, el factor de escala o un color CSS conocido. Repite cada grupo con nuevos procesos del navegador. El cambio CSS es un control positivo: confirma que la comparación puede revelar una modificación introducida deliberadamente en la aplicación.

La ejecución utilizó cinco grupos de tres arranques independientes, 15 tareas en total. Un único grupo global de ejecución tenía un límite solicitado de 20 y otro efectivo de 15 porque solamente había 15 tareas. El equipo Ubuntu tenía 32 núcleos y memoria disponible suficiente antes del arranque; utilizó el servicio existente :88. Se alcanzaron 15 navegadores activos simultáneos. Es un experimento acotado, no una recomendación de abrir 15 navegadores en cualquier máquina.

Descarga el script autónomo de reproducción y el JSON de la ejecución registrada. El script requiere Linux, Node 20 o posterior, Chrome estándar, Playwright Core, Python con Pillow, dos archivos TTF locales y el servicio existente xvfb-88.service. No instala nada. Asigna las cuatro variables de ruta a esas dependencias y ejecuta:

DISPLAY=:88 node visual-regression-baseline-drift.mjs \
  --browser "$CHROME_BIN" --playwright-root "$PLAYWRIGHT_ROOT" \
  --font-a "$FONT_A" --font-b "$FONT_B" \
  --workers 20 --out /tmp/visual-regression-result.json

El script sirve la página fija y las fuentes mediante la interfaz local, registra cada grupo y verifica la terminación de sus procesos. Conserva las imágenes y los directorios temporales para examinarlos. Su modo --self-test permite comprobar los casos límite del comparador antes de iniciar navegadores. Las cantidades siguientes pertenecen a la ejecución entregada; otros archivos tipográficos pueden dar cantidades diferentes sin invalidar el método.

El patrón de captura mantiene separadas la preparación de la página y la comparación de imágenes. Sustituye el selector de aplicación por un estado implementado realmente en la página propia:

import { chromium } from 'playwright';
import { writeFile } from 'node:fs/promises';

const browser = await chromium.launch({ headless: false });
try {
  const context = await browser.newContext({
    viewport: { width: 1280, height: 900 },
    deviceScaleFactor: 1,
  });
  const page = await context.newPage();
  await page.goto('http://127.0.0.1:4173/fixture');
  await page.locator('[data-ready="true"]').waitFor();
  await page.evaluate(async () => {
    await document.fonts.ready;
    await new Promise(resolve =>
      requestAnimationFrame(() => {
        requestAnimationFrame(resolve);
      })
    );
  });
  const manifest = await page.evaluate(() => ({
    viewport: [innerWidth, innerHeight],
    devicePixelRatio,
    fontStatus: document.fonts.status,
  }));
  manifest.browserVersion = browser.version();
  await page.screenshot({ path: 'capture.png', animations: 'disabled' });
  await writeFile('capture.json', JSON.stringify(manifest, null, 2));
} finally {
  await browser.close();
}

El ejemplo captura evidencia; no compara imágenes ni define el servidor de prueba. Una imagen no permite recuperar la versión del navegador, los archivos tipográficos ni la condición de preparación funcional. Añade esos datos al registro de referencia en vez de deducirlos de los píxeles. Desactivar animaciones elimina una fuente concreta de movimiento, pero no congela datos dinámicos, relojes cambiantes o temporizadores de la aplicación.

En el experimento tipográfico, conserva texto, anchuras y navegador mientras cambias la fuente suministrada seleccionada. En el geométrico, conserva fuentes y contenido mientras cambias la ventana o la escala. En el control CSS, cambia únicamente la declaración de color conocida. Si cambian varios datos juntos, conserva ese hecho y clasifica la observación como comparación de configuraciones; no la presentes como un efecto causal aislado.

Interpretar las capturas controladas

Chrome estándar comunicó la versión de ejecución 154.0.8037.57 en las 15 tareas. La referencia medía 1280 × 900; cada grupo se repitió de forma coherente en sus tres arranques. El comparador decodificó PNG a bytes RGBA. Un píxel contaba como cambiado cuando la mayor diferencia absoluta entre canales superaba la tolerancia entera elegida. Esta regla exacta por bytes es una métrica ilustrativa, no la regla perceptual de pixelmatch que usa Playwright.

Grupo	Dimensiones	Píxeles cambiados en comparación exacta	Interpretación
Repeticiones de referencia	1280 × 900	0	Los datos controlados se repitieron en esta ejecución.
Cambio de fuente seleccionada	1280 × 900	26,962, aproximadamente 2.34%	Las diferencias quedaron en la región relacionada con texto.
Cambio de anchura de ventana	1024 × 900	No calculado	Primero se clasificó la incompatibilidad de dimensiones.
Cambio de factor de escala	2560 × 1800	No calculado	Cambiaron las dimensiones del muestreo de imagen.
Cambio de color CSS conocido	1280 × 900	9,600, aproximadamente 0.83%	Las diferencias quedaron en el bloque previsto.

El bloque CSS ocupaba 120 × 80 píxeles: 9,600 píxeles de área. El valor del canal modificado deliberadamente difería en 8. Con una tolerancia exacta de canal de 0, esos píxeles contaban como distintos. Un presupuesto de 10,000 aceptó la imagen pese al cambio conocido. Elevar la tolerancia ilustrativa de canal a 16 hizo que la cantidad de píxeles diferentes fuera cero. Los números muestran dos maneras distintas de aceptar un cambio conocido; no son ajustes propuestos para producción.

El grupo tipográfico cambió 26,962 píxeles dentro de la región textual registrada, sin diferencias fuera de ella. Esto apoya la atribución en esta página deliberadamente restringida. Una aplicación real puede responder a la sustitución de fuente con cambios de distribución mayores, por lo que esa restricción regional no es un detector general de fuentes. El control CSS también era intencionadamente sencillo; modificar una propiedad de distribución podría afectar a casi toda la página.

Todas las tareas cargaron solamente su página propia y el recurso tipográfico local. El registro conserva geometría observada, preparación de fuentes, procedencia del navegador y resultados de comparación. La verificación de limpieza no encontró navegadores ni trabajadores de las tareas restantes. Esto demuestra la finalización de la ejecución acotada, no la disponibilidad de las mismas fuentes o del mismo entorno gráfico en otra máquina. El script reproducible y sus resultados se conservan con la evidencia del experimento.

Elegir por separado la tolerancia de color y el presupuesto

Las opciones documentadas de comparación de imágenes de Playwright separan la diferencia perceptual de color permitida entre posiciones correspondientes de las cantidades totales permitidas. maxDiffPixels expresa una cantidad aceptable de píxeles clasificados como distintos, mientras que maxDiffPixelRatio la expresa respecto del área total de la imagen. Estos ajustes actúan en partes diferentes del proceso. Cambiar uno no equivale a cambiar otro, y los valores de otro algoritmo no son intercambiables.

Ajuste o acción	Pregunta que responde	Fallo que puede ocultar
Tolerancia de color por píxel	¿La diferencia de color basta para contar este píxel?	Un cambio pequeño pero deliberado de color en un componente importante.
Cantidad máxima de píxeles diferentes	¿Cuántas diferencias clasificadas puede contener la imagen?	Un icono ausente o un control modificado cuya área no supera el presupuesto.
Proporción máxima de píxeles diferentes	¿Qué fracción de la imagen puede cambiar?	Un defecto fijo que ocupa una fracción menor de una página más larga.
Nueva imagen de referencia	¿Qué referencia usarán las comparaciones futuras?	Cualquier cambio involuntario aceptado sin examinar la imagen.

Una proporción depende del área. El mismo control ausente ocupa una fracción menor en una captura de página completa muy alta que en un recorte del componente. El presupuesto por cantidad no tiene ese denominador, pero también ignora el significado de la región afectada. Ninguna métrica sabe si los píxeles pertenecen a una sombra decorativa, un precio o un botón de pago desactivado. Elige la región de interés como parte de la prueba, no después de un fallo solamente para aprobarla.

Construye la política de tolerancias a partir de repeticiones registradas en el entorno previsto y de cambios conocidos de la aplicación que deban seguir detectándose. Conserva ambos tipos de ejemplos. Si un ajuste propuesto acepta el defecto CSS conocido, silenciar ruido inocuo no lo convierte en adecuado para esa aserción. Examina la diferencia y decide si conviene comparar un componente estable más pequeño, estabilizar otro dato o mantener una configuración más estricta.

No traslades la tolerancia entera de canal de 16 al ajuste de distancia de color de Playwright. Sus escalas y significados son diferentes. Tampoco uses el presupuesto de 10,000 píxeles como configuración de ejemplo: se eligió antes de ejecutar para demostrar cómo una cantidad permitida puede absorber el control conocido de 9,600 píxeles. Un presupuesto defendible debe estar vinculado a las dimensiones, la región y los cambios específicos que la prueba tiene que rechazar.

Decidir entre restaurar investigar o actualizar

Si las dimensiones difieren inesperadamente, restaura primero viewport, deviceScaleFactor y área de captura previstas. Si difieren fuentes o navegador, determina si el cambio del entorno era intencional. Restaura la deriva accidental; ante una actualización deliberada, compara la revisión anterior de la aplicación en ambos entornos antes de aceptar una referencia nueva. Siempre que sea práctico, separa la migración del entorno de un cambio funcional.

Cuando los datos coinciden y una región estable aún difiere, investiga la revisión de la aplicación y su estado capturado. Comprueba estilos, texto, datos y resultados de carga. La clasificación de configuración y píxeles en Grid aborda la atribución entre nodos distribuidos; una prueba local debe conservar la misma separación entre evidencia de configuración y evidencia de imagen sin fingir que un registro coincidente demuestra un renderizado idéntico.

Actualiza la referencia después de aceptar la región modificada y registrar el entorno generador. Conserva la imagen anterior en el historial de versiones, la diferencia actual, el motivo de aceptación y los datos que generaron el reemplazo. Un comando de actualización escribe un resultado; no revisa el producto. Mantenerlo fuera de la recuperación automática de fallos evita convertir un defecto persistente en la referencia aceptada del día siguiente.

Para una actualización intencional del navegador, revisa texto representativo, controles y distribución además de la diferencia agregada. Un porcentaje pequeño puede ocultar un defecto local importante, mientras que uno alto puede proceder de cambios inocuos en bordes tipográficos. La tolerancia expresa una política de prueba elegida después de entender esas diferencias. No decide si el cambio debe formar parte del producto.

Preguntas frecuentes sobre regresión visual

¿La misma huella de captura demuestra que no hay errores?

No. Los bytes idénticos establecen igualdad para esa captura. Ambas imágenes pueden contener la misma fuente incorrecta, contenido ausente o datos antiguos. Combina la aserción visual con comprobaciones semánticas pertinentes, como el estado esperado de un control o la condición de datos cargados de la aplicación.

¿Todos los ejecutores deben compartir una referencia?

Solo cuando ese sea el contrato de renderizado previsto y los datos pertinentes estén controlados. Proyectos de navegador, rutas gráficas o ventanas diferentes pueden necesitar referencias separadas. Crear una referencia para cada diferencia accidental ocultaría deriva; clasifica primero la diferencia antes de añadir otra familia.

¿Un perfil declarado sustituye los registros de fuentes y GPU?

No. Los controles basados en perfiles describen ciertas superficies del navegador; la captura depende además del texto real y su ruta de renderizado. Registra el modo de fuentes y los supuestos sobre el motor; no interpretes el nombre de un perfil como garantía de identidad de píxeles entre equipos.

Fuentes

• Playwright: Visual comparisons, dependencia del entorno y opciones de comparación.
• Playwright: SnapshotAssertions, tolerancia de color, cantidad y proporción de píxeles.
• Playwright: PageAssertions.toHaveScreenshot, capturas consecutivas y tratamiento de animaciones.
• MDN: Document.fonts, carga y preparación tipográfica del documento.
• BotBrowser: Cross-platform profiles, controles declarados y límites del equipo.
• BotBrowser: Font controls, inventario, modos y límites de renderizado.
• BotBrowser: Linux GPU backend, rutas gráficas de software y diferencias de píxeles.

Conclusión práctica

Un fallo de captura necesita dimensiones comparables, datos registrados y una diferencia examinada antes que una tolerancia más amplia. Separa la tolerancia que clasifica píxeles del presupuesto total y verifica ambos frente a un cambio conocido que la prueba deba rechazar. Acepta una referencia nueva solamente después de revisar el cambio de interfaz y el entorno que la generó.