Pruebas de regresión visual: guía práctica

Una captura solo se convierte en prueba cuando el equipo puede explicar qué estado representa, cómo repetirlo y quién decide si una diferencia es aceptable. Restar la imagen de ayer de la de hoy es sencillo. El trabajo importante consiste en conseguir que ambas capturas representen condiciones comparables y que la decisión posterior quede registrada.

Esta guía usa una página de precios como ejemplo porque combina diseño, datos en vivo, texto y una decisión comercial importante. El mismo método sirve para registro, compra, documentación, ajustes y paneles de clientes. También separa los usos de Playwright, Cypress o Selenium, una API de capturas y RenderLog, en lugar de presentar herramientas diferentes como si resolvieran exactamente el mismo problema.

Empieza por un estado reproducible, no por el número de capturas

Describe el estado antes de elegir una herramienta. Para una página de precios puede ser un viewport de 1440 por 1000 píxeles, tema claro, español, zona horaria UTC, sesión anónima y una respuesta fija del servicio de precios. La página está lista cuando se ven el título y todas las tarjetas de planes. Una captura anterior a esas condiciones no demuestra el mismo estado.

Cada zona dinámica necesita una decisión concreta. Congela una fecha o un precio si no forma parte de la comprobación. Oculta el lanzador del chat solo cuando es ajeno al resultado. Espera a que aparezca un gráfico si sí forma parte de la página. No tapes una tarjeta completa porque cambia una marca de tiempo. Cada máscara elimina cobertura y por eso debe ser pequeña, tener un nombre y resultar fácil de localizar en la definición de la prueba.

Fija viewport, idioma, zona horaria, esquema de color y sesión.
Espera una señal visible de que la página está lista, no una pausa arbitraria.
Sustituye datos inestables solo si su valor no es objeto de la prueba.
Guarda máscaras y zonas ignoradas junto a la definición del control.

La línea base es una decisión aprobada, no simplemente el primer resultado

La primera captura que termina correctamente puede mostrar una fuente sin cargar, un precio vacío o un aviso de cookies sobre la llamada a la acción. Una persona debe revisar el resultado completo antes de convertirlo en referencia. Conserva la captura junto con el viewport, el estado y el motivo de aprobación. Sin ese contexto, más adelante será difícil distinguir una decisión de diseño de un cambio accidental en el entorno.

Cuando el producto cambia a propósito, crea la nueva línea base desde un resultado ya revisado. No regeneres todas las imágenes a ciegas después de una publicación. La operación masiva es rápida, pero también puede aprobar la regresión que la prueba debía detectar. Revisa las páginas afectadas en grupos pequeños y mantén el estado aprobado anterior en el historial.

Revisa toda la primera captura antes de aprobarla.
Guarda viewport y estado de la página como metadatos.
Promueve una nueva línea base desde un resultado revisado.
Conserva la versión aprobada anterior tras la promoción.

Usa el umbral para variaciones del renderizado, no para cambios del producto

El umbral indica cuánta variación de bajo nivel puede tolerar la comparación. No decide si un cambio de negocio es aceptable. Una pequeña diferencia de suavizado en los bordes del texto puede no importar. Una tarjeta de plan ausente, una etiqueta desplazada o un botón invisible sí importan, aunque ocupen pocos píxeles en una página larga.

Empieza con una comparación estricta en un navegador y un ejecutor estables. Mira los primeros fallos antes de aumentar la tolerancia. Si toda la diferencia rodea letras, iguala primero las fuentes y las versiones del navegador. Si cambia siempre una miniatura o un testimonio, estabiliza o enmascara solo esa zona. Un umbral global capaz de ocultar el componente también ocultará defectos independientes que aparezcan cerca.

Trata el porcentaje de píxeles distintos como señal de diagnóstico.
Corrige el entorno antes de aumentar la tolerancia general.
Usa capturas de elemento cuando un componente necesite otra política.
Distingue una página que no terminó de una diferencia visual real.

Elige la superficie de prueba según quién sea responsable del resultado

Una prueba de Playwright o Cypress pertenece cerca del código. Puede preparar datos, simular APIs y bloquear una solicitud de cambio. Suele ser el lugar adecuado para componentes y controles de publicación que pertenecen a ingeniería. Selenium sigue siendo útil cuando ya existe un conjunto funcional o una parrilla de navegadores y la captura es otro artefacto del mismo recorrido.

Una API de capturas basta cuando el producto final es un PNG, PDF o imagen de página y otro sistema se encarga de comparar y revisar. RenderLog encaja cuando la página necesita una línea base aprobada, ejecuciones repetidas, diferencias visibles, historial y avisos compartidos con producto, marketing, operaciones, una agencia o un cliente. Un equipo puede usar los tres enfoques, pero no debería duplicar el mismo control sin un responsable y una decisión diferentes.

Mantén componentes y bloqueos de código dentro del repositorio.
Usa una API si la aplicación solicitante es dueña de la revisión.
Usa una superficie compartida para páginas programadas y varios equipos.
Evita repetir la misma captura completa sin un responsable claro.

Clasifica la causa del fallo antes de actualizar cualquier referencia

Un fallo útil responde a tres preguntas: qué cambió, si la página terminó y qué evidencia está disponible. Compara la línea base, la captura actual y la diferencia al mismo tamaño. Después revisa el estado, la señal de disponibilidad, los registros del navegador y las aserciones. Una imagen vacía después de un tiempo de espera es un fallo de ejecución. Una página completa sin una tarjeta es una diferencia de producto. No deben aparecer como la misma alerta roja.

Pon nombre a las causas repetidas. El ruido del entorno apunta al navegador, las fuentes o los datos. Una diferencia inesperada del producto requiere investigación. Un cambio esperado necesita aprobación. Un control roto necesita una condición de disponibilidad o un selector mejor. Esta clasificación evita que el equipo actualice imágenes una y otra vez hasta perder la confianza en todo el sistema.

Fallo de ejecución: la página o la captura no terminaron.
Diferencia del entorno: los estados no son comparables.
Cambio inesperado del producto: investigar antes de aprobar.
Cambio esperado del producto: aprobar con un motivo registrado.

Construye un conjunto pequeño que alguien vaya a mantener

Empieza con tres a cinco estados cuyo fallo tenga un responsable: precios, registro completado, resumen de compra, una página crítica de documentación y un estado móvil representativo. Ejecútalos con cada publicación o con una frecuencia acorde a sus cambios. Cien capturas sin dueño producen más ruido que cinco controles vinculados a decisiones reales.

Revisa el conjunto cada trimestre. Elimina un control si nadie actúa cuando falla. Divide una página si una zona inestable esconde otra estable e importante. Añade un estado tras un defecto real o una revisión manual repetida, no simplemente porque exista otra URL. Una cobertura útil sigue el riesgo y la responsabilidad, no el tamaño del sitemap.

Asigna a cada control un responsable y una razón para existir.
Cubre escritorio y móvil solo cuando ambos estados importen.
Vincula los fallos a decisiones de publicación, cliente u operación.
Elimina controles cuyos resultados ya no cambian ninguna acción.

¿Qué forma de prueba visual encaja con el trabajo?

Las herramientas coinciden al tomar la captura. La diferencia útil está en quién controla el estado, dónde se revisa y qué debe ocurrir después de encontrar un cambio.

Decisión	Playwright, Cypress o Selenium	API de capturas	RenderLog
Responsable ideal	Ingeniería y revisión de código	Aplicación que solicita la imagen	Producto, operaciones, agencia o equipo mixto
Control del estado	Fixtures, simulaciones y recorridos	Opciones de la petición y lógica del cliente	Controles guardados, escenarios, horarios y API
Revisión	Artefacto de CI o cambio de código	La construye el cliente	Línea base, resultado actual, diferencia e historial
Elegir cuando	El control debe bloquear código	Solo se necesita el archivo	La página requiere revisión repetida y compartida

Ejemplos mínimos para tres tecnologías habituales

Los fragmentos muestran el punto de captura, no un conjunto de producción completo. Añade datos reproducibles, retención de artefactos y un camino de revisión con responsable antes de considerar que el primer resultado correcto ya ofrece cobertura.

Playwright

import { test, expect } from "@playwright/test";

test("pricing page visual baseline", async ({ page }) => {
  await page.goto("https://example.com/pricing");
  await page.getByRole("heading", { name: "Pricing" }).waitFor();
  await expect(page).toHaveScreenshot("pricing-desktop.png", {
    animations: "disabled",
    fullPage: true
  });
});

Cypress

describe("pricing page", () => {
  it("matches the approved state", () => {
    cy.visit("https://example.com/pricing");
    cy.contains("h1", "Pricing").should("be.visible");
    cy.matchImageSnapshot("pricing-desktop");
  });
});

Selenium

await driver.get("https://example.com/pricing");
const screenshot = await driver.takeScreenshot();
await writeFile("artifacts/pricing-current.png", screenshot, "base64");
// Compare the current image with an approved baseline in the same viewport.

Fuentes primarias utilizadas en la guía

Los detalles de las APIs cambian. Consulta la documentación oficial al implementar un ejecutor y usa esta guía para tomar decisiones sobre reproducibilidad, responsabilidad y revisión.

Empieza con una página que alguien ya revisa a mano

Crea un control guardado para precios, registro o una página de cliente que ya tenga responsable. Aprueba la primera línea base solo cuando el estado, el viewport y los datos se puedan repetir.

Crear un espacio de RenderLog

Pruebas de regresión visual sin ruido de capturas poco fiables