Una aserción visual se añade en cinco líneas y puede empezar a fallar de forma aleatoria una semana después. El problema rara vez es el comparador. La página se capturó con otra fuente, un precio en vivo, un fotograma distinto, otro estado de cookies o una versión nueva del navegador. La prueba hace visibles esas variables ocultas, pero solo resulta útil si el equipo las controla de manera deliberada.
Este proceso comienza con una página de precios y solo crece cuando sus fallos ya son explicables. También establece una frontera práctica: Playwright conserva cerca del código los controles que pueden bloquear cambios, mientras RenderLog permite a producto, marketing o una agencia revisar una URL publicada o programada sin entrar en los artefactos internos de CI.
Fija el estado del navegador antes de crear la primera línea base
Usa proyectos con nombre en lugar del navegador actual de una persona. Define viewport, idioma, zona horaria y esquema de color. Instala en CI el navegador y las fuentes desde la misma configuración bloqueada con la que se aprobó la referencia. Una captura creada en macOS no debe convertirse sin aviso en la imagen esperada para Linux, donde el texto puede renderizarse de otra manera.
Decide dónde guardar las líneas base. En el repositorio, cada cambio queda visible en la revisión y funciona bien para un conjunto moderado. Un almacén separado puede servir para matrices grandes, pero necesita versiones y reglas de acceso. En ambos casos, la prueba debe recuperar la referencia exacta para su proyecto, viewport y estado, no el último archivo que alguien haya subido.
- Usa un proyecto con nombre para cada destino de renderizado importante.
- Mantén reproducibles la versión del navegador y las fuentes de CI.
- Separa referencias por proyecto, viewport y estado esperado.
- No compartas una línea base entre navegadores que renderizan distinto.
Haz que la disponibilidad sea visible en la página
`networkidle` no garantiza que la página esté lista. Un temporizador puede alterar el DOM más tarde y una fuente puede cambiar después del primer pintado. Espera un título, un grupo completo de tarjetas o un estado de aplicación reconocible para el usuario. Si existe una marca exclusiva para pruebas, debe significar que el renderizado terminó y no solo que JavaScript montó el componente.
Evita pausas fijas. Dos segundos son lentos si la página termina en 200 milisegundos e insuficientes si CI necesita 2,2 segundos. Las aserciones web reintentan hasta ver el estado y fallan con un motivo relacionado con la página. La captura debe ir después, para que una tarjeta ausente se comunique como tarjeta ausente antes de convertirse en una diferencia misteriosa de toda la página.
- Espera un título, un conjunto estable o una marca real de disponibilidad.
- Comprueba el texto o estado crítico antes de tomar la captura.
- Desactiva animaciones desde Playwright y la configuración de pruebas.
- Trata el tiempo agotado como fallo de ejecución, no como cambio visual.
Controla los datos sin eliminar el comportamiento que quieres comprobar
Simula la respuesta de precios si la prueba trata del diseño y el valor cambia por separado. No la simules si quieres detectar un precio incorrecto en producción. Prepara una cuenta cuando importe el estado autenticado. Congela el reloj si una fecha relativa es incidental, pero conserva la fecha real cuando el objetivo sea comprobar un anuncio de publicación.
La regla es sencilla: estabiliza las entradas que quedan fuera de la decisión y conserva las que forman parte de ella. Documenta el límite en el nombre y los comentarios de la prueba. Quien revise `pricing.png` debe saber si prueba el precio real, el diseño con datos de ejemplo o solamente el renderizado de una ruta estática.
- Simula datos externos solo cuando su valor no esté bajo revisión.
- Nombra los fixtures para dejar claro qué demuestra la captura.
- Enmascara widgets ajenos de forma precisa, no zonas grandes.
- Define de forma explícita la autenticación y el consentimiento.
Decide el umbral después de observar fallos reales
Empieza con la comparación estricta de Playwright en el ejecutor fijado. Repite varias veces la misma prueba sin modificar la página. Si falla, mira los píxeles antes de cambiar `maxDiffPixels` o `maxDiffPixelRatio`. Los bordes del texto apuntan al entorno, un cursor o transición al estado y un bloque grande que se mueve a datos inestables o a un componente que merece su propia prueba.
Usa la menor tolerancia que absorba una variación conocida. Revisa cualquier cambio de umbral como código de producción y explica el caso que lo hizo necesario. Una proporción pequeña en una captura completa puede esconder un defecto del tamaño de un botón. Para un componente crítico conviene una captura de elemento, mientras la página completa conserva el contexto general del diseño.
- Repite pruebas sin cambios antes de elegir una tolerancia.
- Corrige causas deterministas antes de aceptar ruido de píxeles.
- Incluye cada cambio de umbral en la revisión de código.
- Usa capturas enfocadas para componentes pequeños y de alto riesgo.
Conserva todos los artefactos cuando CI detenga el cambio
Un fallo sin imágenes actual, esperada y diferencial obliga a repetir la ejecución localmente. Sube el informe de Playwright y el directorio `test-results` tanto en éxito como en fallo, con una retención suficiente para el ciclo habitual de revisión. Incluye el nombre del proyecto y de la prueba en la ruta para no confundir resultados móviles y de escritorio.
El informe es evidencia, pero no debe ser el único registro de una decisión aceptada. Actualiza la línea base en un cambio dedicado, sin mezclar modificaciones del producto. La imagen diferencial explica el fallo y el cambio de referencia registra lo que el equipo aceptó. Mantener separadas ambas decisiones ayuda mucho cuando aparece otra regresión meses después.
- Sube el informe HTML y las imágenes originales cuando falle la prueba.
- Nombra artefactos por prueba y proyecto de navegador.
- Conserva los archivos durante todo el ciclo habitual de revisión.
- Separa las actualizaciones de referencia de los cambios del producto.
Entrega la página publicada donde trabaje su responsable
La prueba del repositorio es adecuada cuando ingeniería controla el estado y el resultado debe bloquear código. Sin embargo, las páginas de precios, campañas, documentación o clientes pueden cambiar fuera de una única solicitud. Su responsable puede estar en producto, marketing o una agencia. Obligarle a buscar archivos de CI añade fricción, pero no crea un proceso claro de aprobación.
Mantén los controles de componentes y cambios en Playwright, y ejecuta la URL publicada en RenderLog después del despliegue mediante horario o API. Allí el responsable ve referencia, resultado actual, diferencia e historial. No copies la misma prueba sin motivo: define qué superficie bloquea código y cuál confirma el estado real de la página que ya está disponible para los usuarios.
- Usa Playwright para decisiones de código que pertenecen a ingeniería.
- Usa RenderLog para confirmar el estado de la página publicada.
- Asigna una persona a cada tipo de resultado.
- No dupliques capturas sin una acción posterior distinta.
Cómo clasificar un fallo visual de Playwright
No actualices primero la referencia. La forma de la diferencia y el estado de la ejecución suelen separar problemas del entorno, de la página y cambios esperados.
| Señal | Causa probable | Comprobar | Siguiente paso |
|---|---|---|---|
| Bordes alrededor del texto | Fuente o navegador | Imagen, versión y fuentes | Igualar el entorno antes del umbral |
| Bloque grande desplazado | Datos, estado o diseño | API, viewport y disponibilidad | Corregir estado o investigar regresión |
| Página vacía | Fallo de ejecución | Respuesta, registros y tiempo | Reparar la ejecución, no la referencia |
| Cambio de diseño conocido | Cambio esperado | Solicitud, diseño y zonas cercanas | Aprobar una nueva referencia concreta |
Configuración básica para capturas y artefactos de CI
Los ejemplos muestran comparación, proyecto de navegador, control de precios y entrega de artefactos. Sustituye selectores y datos por el estado real del producto, y decide los umbrales tras varias ejecuciones en el mismo CI.
playwright.config.ts
import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./tests/visual",
expect: {
toHaveScreenshot: {
animations: "disabled",
caret: "hide",
maxDiffPixelRatio: 0.001
}
},
use: {
locale: "en-US",
timezoneId: "UTC",
colorScheme: "light"
},
projects: [
{ name: "desktop-chromium", use: { ...devices["Desktop Chrome"] } },
{ name: "mobile-chromium", use: { ...devices["Pixel 7"] } }
]
});tests/visual/pricing.spec.ts
import { test, expect } from "@playwright/test";
test("pricing page", async ({ page }) => {
await page.route("**/api/prices", async route => {
await route.fulfill({ json: { plan: "Pro", price: 49 } });
});
await page.goto("https://example.com/pricing", { waitUntil: "networkidle" });
await page.getByRole("heading", { name: "Pricing" }).waitFor();
await expect(page).toHaveScreenshot("pricing.png", {
fullPage: true,
mask: [page.getByTestId("live-chat-launcher")]
});
});CI artifact handoff
npx playwright test --project=desktop-chromium
# Upload test-results/ and playwright-report/ even when the job fails.
# Send the public page to RenderLog when review must continue outside the repository.Documentación oficial para la implementación
Playwright sigue cambiando su sintaxis y capacidades. Verifica los detalles en las fuentes oficiales. La API de RenderLog solo interviene en la revisión separada de la página publicada.
Continúa el proceso
Guía completa de regresión visual
Define referencias, umbrales, responsables y reglas de aprobación.
Comparar herramientas de regresión visual
Separa los bloqueos de código de la revisión de páginas publicadas.
Ejecuciones mediante la API de RenderLog
Inicia un control guardado después del despliegue y recupera resultados.
Reglas para resultados fallidos
Distingue un fallo de renderizado de un cambio real en la página.
Añade una captura posterior al despliegue a tu prueba actual
Mantén la comprobación del componente en Playwright. Después del despliegue, ejecuta en RenderLog un control guardado de la página pública y permite que producto revise el cambio con todo el historial disponible.
Crear un control en RenderLog