Test Visual con Playwright: El Tutorial Completo
Playwright de Microsoft incluye desde la versión 1.22 una funcionalidad nativa de test visual: el método toHaveScreenshot(). Permite capturar screenshots y compararlos automáticamente con imágenes de referencia, sin plugin externo.
Es una de las opciones más sólidas para equipos de desarrollo que quieren añadir tests visuales a su stack existente. Este tutorial cubre la instalación, configuración, buenas prácticas e integración CI/CD.
Instalación y primer test
La puesta en marcha es rápida si ya tiene un proyecto Node.js:
npm install -D @playwright/test
npx playwright install
Cree su primer test visual en tests/visual.spec.ts:
import { test, expect } from '@playwright/test';
test('homepage visual test', async ({ page }) => {
await page.goto('https://su-sitio.com');
await expect(page).toHaveScreenshot('homepage.png');
});
La primera ejecución genera la baseline (la imagen de referencia). Las siguientes comparan el screenshot actual con esta baseline y señalan las diferencias.
# Primera vez: generar las baselines
npx playwright test --update-snapshots
# Después: comparar
npx playwright test
Así de simple para empezar. La complejidad llega con los casos reales.
Configurar la tolerancia
Por defecto, Playwright señala la mínima diferencia de un píxel. En la práctica, hay que configurar umbrales de tolerancia para evitar falsos positivos.
En playwright.config.ts:
import { defineConfig } from '@playwright/test';
export default defineConfig({
expect: {
toHaveScreenshot: {
maxDiffPixelRatio: 0.01, // 1% de píxeles diferentes tolerados
animations: 'disabled', // Desactiva las animaciones CSS
scale: 'device', // Maneja pantallas Retina
},
},
});
También puede ajustar por test:
// Página estática: umbral estricto
await expect(page).toHaveScreenshot('landing.png', {
maxDiffPixelRatio: 0.001
});
// Dashboard con gráficos: umbral flexible
await expect(page).toHaveScreenshot('dashboard.png', {
maxDiffPixelRatio: 0.05,
mask: [page.locator('.chart')]
});
Gestionar el contenido dinámico
El contenido dinámico (fechas, publicidad, avatares, contadores) es la pesadilla de los tests visuales. Playwright propone tres soluciones:
Enmascarar zonas dinámicas — la más común:
await expect(page).toHaveScreenshot({
mask: [
page.locator('.ad-banner'),
page.locator('.timestamp'),
page.locator('.user-avatar')
]
});
Reemplazar el contenido — para fijar valores:
await page.evaluate(() => {
document.querySelector('.date').textContent = '01/01/2026';
});
await expect(page).toHaveScreenshot();
Ocultar vía CSS — para elementos que no quiere ver en absoluto:
await page.addStyleTag({
content: '.dynamic-element { visibility: hidden !important; }'
});
await expect(page).toHaveScreenshot();
Estabilizar los tests
Un test visual que pasa un día y falla al siguiente sin razón es inutilizable. Así se garantiza la estabilidad:
test('stable visual test', async ({ page }) => {
await page.goto('https://su-sitio.com');
// Esperar que la red esté en calma
await page.waitForLoadState('networkidle');
// Esperar la carga de 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 manualmente las animaciones cuando la opción global no es suficiente:
await page.addStyleTag({
content: `
*, *::before, *::after {
animation-duration: 0s !important;
transition-duration: 0s !important;
}
`
});
Probar múltiples resoluciones
Playwright facilita el test multi-resolución vía proyectos:
// playwright.config.ts
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. Un test se ejecuta tres veces, en tres resoluciones, con tres juegos de screenshots.
Integración CI/CD
La integración en GitHub Actions es directa:
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 un test falla, Playwright genera tres imágenes: la baseline (esperada), el screenshot actual, y un diff con las diferencias en rojo. El reporte HTML (npx playwright show-report) las muestra lado a lado.
Los límites del enfoque Playwright
Playwright es excelente para equipos de desarrollo, pero tiene límites:
Competencias obligatorias: hay que dominar TypeScript/JavaScript, los selectores y la configuración del proyecto. No es accesible para QA no-desarrolladores.
Sin dashboard: no hay interfaz de revisión integrada. La gestión de baselines se hace vía terminal y sistema de archivos.
Falsos positivos: la comparación de píxeles es básica. Las diferencias de anti-aliasing entre navegadores, las variaciones de renderizado de fuentes entre OS — todo genera ruido.
Mantenimiento: cada cambio de UI intencional requiere regenerar las baselines (--update-snapshots). En un proyecto con 200 tests visuales y 3 navegadores, son 600 baselines que gestionar.
Para equipos que quieren test visual sin estas restricciones técnicas, las soluciones no-code como Delta-QA ofrecen una alternativa: mismo resultado sin escribir código, sin gestionar baselines manualmente, y con cero falsos positivos gracias a un algoritmo de comparación estructural en 5 pasadas.
FAQ
¿Playwright es gratuito para tests visuales?
Sí, completamente. toHaveScreenshot() está integrado nativamente en Playwright, que es open source y mantenido por Microsoft.
¿Cuánto tiempo para implementar tests visuales con Playwright?
Si ya domina Playwright, cuente unas horas. Si parte de cero, cuente 2 a 3 días.
¿Playwright o Cypress para tests visuales?
Playwright integra el test visual nativamente (toHaveScreenshot()), mientras Cypress necesita un plugin externo. Playwright soporta tres motores de navegador (Chromium, Firefox, WebKit) contra uno para Cypress. Para test visual específicamente, Playwright es la mejor opción open source.
¿Se puede usar Playwright y Delta-QA juntos?
Sí. El enfoque recomendado es usar Playwright para tests visuales complejos y Delta-QA para verificaciones visuales de rutina mantenidas por el equipo QA. Cada herramienta cubre una necesidad diferente.
Playwright ofrece una base sólida para tests visuales automatizados. Para equipos de desarrollo que dominan TypeScript, es probablemente la mejor opción open source disponible en 2026.
Artículo anterior: Del Test Manual al Test Automatizado: Guía para QA No-Desarrolladores