Viernes por la noche, haces merge de un rediseño del header. El lunes por la mañana, un compañero te avisa de que el botón de inicio de sesión se ha desplazado unos píxeles en la página de precios: una página que ni siquiera habías tocado. Ninguna prueba hizo saltar la alarma, porque ninguna prueba miraba el aspecto. Es exactamente el hueco que cubren las pruebas visuales.
Playwright, de Microsoft, incluye desde la versión 1.22 una función nativa de pruebas visuales: el método toHaveScreenshot(). Permite capturar pantallas y compararlas automáticamente con imágenes de referencia, sin plugin externo. Es una solución totalmente gratuita: para otras herramientas gratuitas de pruebas visuales, consulta nuestra comparativa.
Es una de las opciones más sólidas para los equipos que quieren añadir pruebas visuales a su suite existente. Para entender las bases de la regresión visual, consulta nuestra guía completa. Esta guía cubre la instalación, la configuración, las buenas prácticas y la integración CI/CD, y después lo que el SDK Vision de Delta-QA cambia en esas mismas pruebas.
Lo esencial en una página: qué automatiza realmente una herramienta sin código y cómo se compara: Automatización de pruebas sin código.
¿toHaveScreenshot() sigue obligándote a escribir y mantener código? Delta-QA captura y compara tus páginas sin escribir una línea de código, sin tarjeta bancaria. Probar Delta-QA gratis →
Instalación y primera prueba
La puesta en marcha es rápida si ya tienes un proyecto Node.js:
npm install -D @playwright/test
npx playwright install
Crea después tu primera prueba visual en tests/visual.spec.ts:
import { test, expect } from '@playwright/test';
test('homepage visual test', async ({ page }) => {
await page.goto('https://your-site.com');
await expect(page).toHaveScreenshot('homepage.png');
});
El primer lanzamiento genera la baseline (la imagen de referencia). Los siguientes comparan la captura del momento con esa baseline y señalan las diferencias.
# Primera vez: generar las baselines
npx playwright test --update-snapshots
# Después: comparar
npx playwright test
Empezar es así de sencillo. La complejidad llega con los casos reales.
Configurar la tolerancia
Por defecto, Playwright señala la menor diferencia de un píxel. En la práctica, hay que configurar umbrales de tolerancia para evitar los falsos positivos.
En playwright.config.ts:
import { defineConfig } from '@playwright/test';
export default defineConfig({
expect: {
toHaveScreenshot: {
maxDiffPixelRatio: 0.01, // se tolera un 1 % de píxeles distintos
animations: 'disabled', // desactiva las animaciones CSS
scale: 'device', // tiene en cuenta las pantallas Retina
},
},
});
También puedes ajustarlo prueba a prueba:
// Página estática: umbral estricto
await expect(page).toHaveScreenshot('landing.png', {
maxDiffPixelRatio: 0.001
});
// Panel de control con gráficos: umbral más flexible
await expect(page).toHaveScreenshot('dashboard.png', {
maxDiffPixelRatio: 0.05,
mask: [page.locator('.chart')]
});
El umbral es un compromiso: demasiado bajo, y la menor diferencia de renderizado hace fallar la prueba; demasiado alto, y un margen que pasa de 16px a 12px se cuela bajo el listón sin ser visto.
Gestionar el contenido dinámico
El contenido dinámico (fechas, anuncios, avatares, contadores) es la pesadilla de las pruebas visuales. Playwright propone tres soluciones:
Enmascarar las zonas dinámicas, el método más habitual:
await expect(page).toHaveScreenshot({
mask: [
page.locator('.ad-banner'),
page.locator('.timestamp'),
page.locator('.user-avatar')
]
});
Sustituir el contenido para fijar los valores:
await page.evaluate(() => {
document.querySelector('.date').textContent = '01/01/2026';
});
await expect(page).toHaveScreenshot();
Ocultar mediante CSS los elementos que no deben aparecer en absoluto:
await page.addStyleTag({
content: '.dynamic-element { visibility: hidden !important; }'
});
await expect(page).toHaveScreenshot();
Cada una de estas soluciones se mantiene a mano: un bloque dinámico nuevo en la página es un selector más que añadir.
Estabilizar las pruebas
Una prueba visual que pasa un día y falla al siguiente sin motivo es inutilizable. Así se garantiza la estabilidad:
test('stable visual test', async ({ page }) => {
await page.goto('https://your-site.com');
// Esperar a que la red se calme
await page.waitForLoadState('networkidle');
// Esperar a que se carguen las fuentes
await page.evaluate(() => document.fonts.ready);
// Esperar un elemento crítico
await page.waitForSelector('.hero-image', { state: 'visible' });
await expect(page).toHaveScreenshot();
});
Y para desactivar las animaciones a mano cuando la opción global no basta:
await page.addStyleTag({
content: `
*, *::before, *::after {
animation-duration: 0s !important;
transition-duration: 0s !important;
}
`
});
Probar varias resoluciones
Playwright facilita las pruebas multirresolución mediante los proyectos:
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
projects: [
{
name: 'Desktop',
use: { viewport: { width: 1920, height: 1080 } },
},
{
name: 'Tablet',
use: { viewport: { width: 768, height: 1024 } },
},
{
name: 'Mobile',
use: { ...devices['iPhone 13'] },
},
],
});
Cada proyecto genera sus propias baselines. Una prueba se ejecuta así tres veces, en tres resoluciones, con tres juegos de capturas que mantener al día.
Integración CI/CD
La integración en GitHub Actions es directa. Para una configuración completa, consulta nuestra guía de las pruebas de regresión en GitHub Actions o, en el lado de GitLab, la de las pruebas visuales en GitLab CI.
name: Visual Tests
on: [push, pull_request]
jobs:
visual-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test
- uses: actions/upload-artifact@v4
if: failure()
with:
name: playwright-report
path: playwright-report/
Cuando una prueba falla, Playwright produce tres imágenes: la baseline (esperada), la captura del momento y un diff con las diferencias en rojo. El informe HTML (npx playwright show-report) las muestra una junto a otra.
Punto de atención: el renderizado de las fuentes varía de un sistema a otro. Unas baselines generadas en un Mac no coincidirán con las capturas tomadas en el runner Linux de la CI. Genéralas en la CI, o en la imagen Docker oficial de Playwright.
¿toHaveScreenshot() sigue pidiéndote escribir código? Delta-QA captura y compara tus páginas sin código, sin tarjeta bancaria. Probar Delta-QA gratis →
Los límites del enfoque Playwright
Playwright es excelente para los equipos que escriben sus pruebas, pero toHaveScreenshot() tiene límites que conviene conocer:
Competencias obligatorias: hay que dominar TypeScript/JavaScript, los selectores y la configuración de proyecto. Las personas de QA que no escriben código no pueden ni crear ni mantener estas pruebas.
Sin interfaz de revisión: no hay un espacio compartido para juzgar las diferencias. La gestión de las baselines se hace por terminal y por el sistema de archivos. En equipo, se complica rápido.
Una comparación de píxeles: el diff muestra una zona roja, no lo que ha cambiado. Las diferencias de anti-aliasing entre navegadores, las variaciones de renderizado de las fuentes entre sistemas operativos: todo eso genera ruido que hay que gestionar a mano con máscaras y umbrales.
Mantenimiento: cada cambio de interfaz deseado obliga a regenerar las baselines (--update-snapshots). En un proyecto con 200 pruebas visuales y 3 navegadores, son 600 baselines que gestionar, versionadas en el repositorio. Nuestra guía sobre la gestión de baselines detalla las estrategias para mantenerlas.
Quedarse con Playwright, cambiar la comparación: el SDK Vision
Si tus pruebas Playwright ya existen, no tienes que abandonarlas para levantar parte de estos límites. El SDK Vision de Delta-QA (@delta-qa/vision) añade una verificación de Delta-QA donde la prueba debe mirar la página:
import { test } from "@delta-qa/vision/fixture";
test("Checkout", async ({ page, vision }) => {
const checkout = await vision.open(page, { id: "checkout", name: "Checkout" });
await page.goto("https://shop.example.com/checkout");
await checkout.check("Payment");
}); // cerrado por la fixture: una diferencia sin juzgar hace fallar la prueba
El SDK lee la clave de API en la variable DELTAQA_API_KEY. Sin la fixture, open(page, { … }) de @delta-qa/vision abre la misma prueba, y close() la cierra en un afterEach.
Lo que cambia respecto a toHaveScreenshot():
- El informe nombra el elemento que ha cambiado. Nada de una zona roja que interpretar: el informe dice qué elemento ha cambiado, por ejemplo el botón «Pagar», que ha pasado del azul al verde.
- Las referencias ya no viven en el repositorio. En el primer lanzamiento, cada check pasa a ser la referencia. Después, una diferencia sin juzgar hace fallar la prueba, y el log de la CI da el enlace del informe. Ahí juzgas cada diferencia: «Intencionado» o «Error».
- Una referencia por rama. La prueba indica su rama y su rama base (
branch,baseBranch): una rama nueva se compara con su rama base desde su primer lanzamiento, y «Intencionado» solo se aplica a las ramas que marques. - El resto de la prueba no cambia. Los proyectos de
playwright.config.tssiguen aplicándose: cada tamaño de pantalla tiene su propia referencia. Una sola condición: una densidad de pantalla de 1 (deviceScaleFactor: 1).
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.
Y para quienes no escriben pruebas
Las pruebas Playwright siguen siendo código. Para que las personas de QA, los product owners o los diseñadores también verifiquen el aspecto de la aplicación, las soluciones sin código como Delta-QA ofrecen otra vía: se graba un recorrido en el navegador, Delta-QA lo reproduce en cada versión y compara cada paso con su referencia. Estos escenarios y los checks del SDK Vision se juzgan en el mismo espacio de Delta-QA, con el mismo informe.
¿Quieres probar sin una línea de TypeScript ni una sola baseline que regenerar? Compara tus páginas con Delta-QA ahora mismo, gratis y sin tarjeta bancaria. Probar Delta-QA gratis →
FAQ
¿Es Playwright gratuito para las pruebas visuales?
Sí, totalmente. toHaveScreenshot() está integrado de forma nativa en Playwright, que es open source y está mantenido por Microsoft. Sin licencia, sin límite de capturas.
¿Cuánto se tarda en implantar las pruebas visuales con Playwright?
Si ya dominas Playwright, cuenta unas horas para configurar y escribir tus primeras pruebas. Si partes de cero (instalación, aprendizaje de TypeScript, configuración de la CI), cuenta de 2 a 3 días.
¿Playwright o Cypress para las pruebas visuales?
Playwright tiene la ventaja de integrar las pruebas visuales de forma nativa (toHaveScreenshot()), mientras que Cypress necesita un plugin externo. Playwright también soporta tres motores de navegador (Chromium, Firefox, WebKit), mientras que Cypress admite los navegadores Chromium y Firefox, y WebKit sigue siendo experimental. Para el detalle, consulta nuestra comparativa Playwright vs Cypress, o Playwright vs Selenium si dudas entre esos dos frameworks.
¿Se pueden usar Playwright y Delta-QA juntos?
Sí, y en la misma prueba. Con el SDK Vision, añades vision.check() en los pasos donde hay que verificar la página: Playwright maneja el navegador y tus aserciones funcionales, Delta-QA compara la página con su referencia. Los recorridos grabados sin código por el equipo de QA se juzgan en el mismo espacio.
¿Hay que quitar mis toHaveScreenshot() para usar el SDK Vision?
No. Ambos pueden convivir en una misma suite: puedes añadir vision.check() en algunas páginas, comparar los resultados y decidir luego página por página qué conservas.
Playwright ofrece una base sólida para las pruebas visuales automatizadas. Para los equipos que escriben sus pruebas en TypeScript, toHaveScreenshot() es probablemente la mejor opción open source disponible en 2026, a condición de ajustar bien los umbrales y estabilizar las pruebas desde el principio. Cuando el diff de píxeles y las baselines del repositorio pasan a ser la carga principal, el SDK Vision conserva tus pruebas y cambia la comparación. Para situar Playwright frente a otras herramientas, consulta nuestra comparativa de herramientas de pruebas de regresión.
