Pruebas de regresión visual de Playwright

Este capítulo presenta la función de pruebas de regresión visual de Playwright, que detecta cambios inesperados en la interfaz de usuario mediante la comparación de capturas de pantalla.

Qué es la prueba de regresión visual

La prueba de regresión visual (Visual Regression Testing) compara la captura de pantalla actual conla captura de pantalla de referencia (Golden File)las diferencias de píxeles entre ellas, para detectar cambios en la interfaz de usuario de la página.

Cuando un cambio de CSS afecta inesperadamente al diseño de otras páginas, la prueba de regresión visual puede capturar directamente este problema.

expect(page).toHaveScreenshot() Comparación de capturas de pantalla de página

Ejemplo

test('Regresión visual de la página de inicio de EJEMPLO', async ({ page }) => {
  await page.goto('https://www.example.com/');

  // Primera ejecución: guardar la captura de referencia
  // Ejecuciones posteriores: comparar con la captura de referencia
  await expect(page).toHaveScreenshot('ejemplo-homepage.png');
});

En la primera ejecución, Playwright mostrará un error y generará la captura de referencia:

Error: A snapshot doesn't exist at ejemplo-homepage-chromium-darwin.png,
writing actual.

En la segunda ejecución, se comparará automáticamente con la captura de referencia.

Opciones completas de toHaveScreenshot

Ejemplo

await expect(page).toHaveScreenshot('homepage.png', {
  fullPage: true,                // Captura de pantalla de página completa
  maxDiffPixelRatio: 0.01,       // Permite un 1% de diferencia de píxeles
  maxDiffPixels: 100,            // Permite hasta 100 píxeles de diferencia
  threshold: 0.2,                // Umbral de diferencia de píxeles (0~1)
  animations: 'disabled',        // Deshabilitar animaciones (recomendado)
  mask: [                        // Ignorar áreas específicas
    page.getByText('Hora actual'),
  ],
});

expect(locator).toHaveScreenshot() Comparación de capturas de pantalla de elementos

Ejemplo

test('Regresión visual de la barra de navegación', async ({ page }) => {
  await page.goto('https://www.example.com/');

  // Comparar solo la captura de pantalla de la barra de navegación
  const navbar = page.getByRole('navigation');
  await expect(navbar).toHaveScreenshot('navbar.png');
});

Gestión de Golden File

Generar Golden File

Al ejecutar la aserción de captura de pantalla por primera vez, Playwright generará automáticamente un Golden File y lo guardará junto al archivo de prueba en el-snapshotsdirectorio:

tests/
├── example.spec.ts
└── example.spec.ts-snapshots/
    └── ejemplo-homepage-chromium-darwin.png

El nombre del archivo incluye el nombre del navegador y el sistema operativo, lo que garantiza que las referencias de diferentes plataformas se gestionen de forma independiente.

Actualizar Golden File

Cuando la interfaz de usuario sufre cambios de diseño esperados, es necesario actualizar la captura de referencia:

# 更新所有截图基准
npx playwright test --update-snapshots

# 只更新特定文件
npx playwright test tests/example.spec.ts --update-snapshots

Explicación detallada de las opciones de comparación visual

OpciónTipoDescripción
maxDiffPixelRationumberProporción de diferencia de píxeles permitida (0~1), por defecto 0
maxDiffPixelsnumberNúmero de diferencias de píxeles permitidas, por defecto 0
thresholdnumberTolerancia de diferencia por píxel (0~1), por defecto 0.2
animationsstringIndica si se deshabilitan las animaciones:'disabled' | 'allow'
maskLocator[]Áreas ignoradas (no se tienen en cuenta en la comparación de diferencias)

Consideraciones para el entorno de CI

Los resultados de renderizado del navegador se ven afectados por factores como el sistema operativo, la versión del navegador, el hardware, el estado de la alimentación y el modo headless. Para garantizar la consistencia, genere el Golden File y ejecute las pruebas en el mismo entorno. Se recomienda utilizar contenedores Docker o la misma plataforma de CI para eliminar diferencias.

Uso de pruebas visuales en Docker

# 使用 Playwright Docker 镜像确保渲染一致性
docker run --rm -v $(pwd):/work -w /work \
  mcr.microsoft.com/playwright:v1.52.0-jammy \
  npx playwright test --update-snapshots

Mejores prácticas para pruebas visuales

  • Generar el Golden File y ejecutar la comparación en la misma plataforma
  • Usaranimations: 'disabled'Eliminar la incertidumbre de las animaciones
  • UsarmaskIgnorar contenido dinámico (como marcas de tiempo, espacios publicitarios)
  • Priorizar la regresión visual en páginas críticas (página principal, inicio de sesión, pago)
  • Confirmar el Golden File en el sistema de control de versiones
  • Usar versiones fijas de navegador y sistema operativo en CI
Otras extensiones