# Pruebas de regresión visual para detectar cambios de interfaz

**Categoría:** Testing y QA · **Nivel:** Intermedio · **Lectura:** 10 min
**Publicada:** 2026-07-28 · **Actualizada:** 2026-07-28 · **Autoría:** Underc0de
**Versión HTML (canónica):** https://underc0de.org/guias/testing/pruebas-de-regresion-visual/

## Respuesta rápida

Las **pruebas de regresión visual** detectan cambios inesperados en el aspecto de una interfaz comparando **capturas de pantalla**: se guarda una imagen de referencia —la **línea base**— de cómo se ve una pantalla, y en cada ejecución se toma una captura nueva y se compara píxel a píxel. Si difieren más de un umbral, la prueba falla y muestra las tres imágenes: la vieja, la nueva y las diferencias resaltadas. En Playwright esto viene incorporado con la aserción `toHaveScreenshot()`. Llena un hueco que las pruebas funcionales no cubren: una prueba funcional confirma que el botón *funciona*, no que se *vea bien*; un cambio de CSS puede romper el diseño de otra pantalla sin que ninguna prueba funcional se entere. El desafío no es la comparación en sí, sino los **falsos positivos** —fuentes, animaciones, datos cambiantes— y aprobar los cambios que sí son intencionales actualizando la línea base.

## Qué es y qué hueco llena

Las pruebas funcionales comprueban *comportamiento*: que al hacer clic pase lo que debe pasar. Pero no dicen nada del *aspecto*: un botón puede funcionar perfecto y estar descolocado, tapado o invisible. Ese hueco es el que llenan las **pruebas de regresión visual**.

> **El problema que resuelven**
>
> El escenario clásico: alguien ajusta una regla de CSS para arreglar una pantalla y, sin querer, descoloca otra que compartía ese estilo. Todas las pruebas funcionales pasan —los botones siguen funcionando—, pero el diseño se rompió. Nadie se entera hasta que un usuario lo ve. La regresión visual atrapa exactamente ese tipo de cambio no deseado, comparando cómo se ve la interfaz con cómo se veía antes.

«Regresión» significa que algo que estaba bien empeoró. La prueba no juzga si el diseño es lindo: juzga si *cambió respecto de antes*, y deja que una persona decida si el cambio era intencional o un accidente.

## Cómo funciona

El mecanismo tiene tres momentos, y en Playwright viene incorporado:

```javascript
// Una prueba de regresión visual en Playwright.
import { test, expect } from '@playwright/test';

test('la página de inicio se ve como debe', async ({ page }) => {
  await page.goto('/');

  // Primera vez: guarda la línea base. Después: compara contra ella.
  await expect(page).toHaveScreenshot('inicio.png');
});
```

La **primera ejecución** no tiene con qué comparar, así que toma la captura y la guarda como línea base, versionada junto al código. En **cada ejecución posterior**, toma una captura nueva y la compara con esa línea base usando una biblioteca de comparación de píxeles. Si coinciden dentro de la tolerancia, pasa; si no, falla y genera tres imágenes: la anterior, la nueva y una de **diferencias** con los píxeles cambiados resaltados.

## Los falsos positivos: el verdadero desafío

La comparación de píxeles es implacable, y ese es el problema. Dos capturas de la *misma* pantalla casi nunca son idénticas al píxel, y si no se controla eso, la prueba falla todo el tiempo por cosas que no importan. Las causas habituales de falsos positivos:

- **Renderizado de fuentes.** El mismo texto se dibuja con mínimas diferencias entre sistemas operativos. Correr siempre en el mismo entorno —o en un contenedor— es clave.
- **Datos cambiantes.** Una fecha «hoy», un nombre de usuario, un contador: cambian en cada corrida y disparan diferencias. Hay que fijarlos con datos de prueba estables.
- **Animaciones y contenido dinámico.** Un carrusel, una animación a medio camino: se congelan o se desactivan antes de la captura.
- **Antialiasing.** Diferencias mínimas en los bordes. Para esto está el **umbral de tolerancia**: cuántos píxeles o qué porcentaje de diferencia se acepta antes de fallar.

> **Atención**
>
> Playwright permite ajustar la tolerancia (por ejemplo, cuántos píxeles pueden diferir). Demasiado estricto y la prueba falla por antialiasing; demasiado flojo y deja pasar cambios reales. El equilibrio se encuentra con la práctica, y la mayor parte de la estabilidad viene antes: **controlar el entorno y los datos**, no aflojar el umbral. Una prueba visual que da falsos positivos seguido termina ignorada, igual que cualquier [prueba inestable](../como-detectar-y-solucionar-flaky-tests/index.md).

## Aprobar cambios intencionales

No todo cambio visual es un error: muchos son intencionales —un rediseño, un color nuevo, un texto actualizado—. Cuando la prueba falla por un cambio querido, la línea base quedó vieja y hay que **actualizarla** para que la nueva imagen pase a ser la referencia.

```bash
# Tras verificar que el cambio visual es intencional y correcto,
# se regeneran las líneas base:
npx playwright test --update-snapshots
```

> **El paso humano que no se puede automatizar**
>
> Actualizar la línea base es una **decisión**, no un trámite. Antes de regenerarla, una persona tiene que *mirar* la imagen de diferencias y confirmar que el cambio es el que se quería. Actualizar a ciegas —«falló, actualizo y listo»— vacía de sentido la prueba: si aprobás cualquier cambio sin mirarlo, nunca vas a atrapar el accidental. La nueva línea base se revisa y se versiona junto al código, como parte del cambio.

## En el pipeline

La regresión visual rinde de verdad corriendo en el pipeline con cada cambio, pero tiene una exigencia propia: el **entorno debe ser idéntico** al que generó las líneas base, porque si las fuentes o el navegador difieren, todo falla por falsos positivos. Por eso las líneas base se generan y comparan en el *mismo* entorno —normalmente un contenedor—, y a menudo se guardan las que produce el propio pipeline, no las de la máquina de cada persona.

Con eso resuelto, la prueba visual se suma a las demás en [el pipeline de GitHub Actions](../pruebas-automaticas-con-github-actions/index.md): cada cambio compara la interfaz contra la referencia, y cuando falla, las imágenes de diferencias quedan como evidencia para decidir si aprobar o corregir.

## Errores frecuentes

- **Generar líneas base en un entorno y comparar en otro.** Diferencias de fuentes disparan falsos positivos masivos.
- **No fijar los datos cambiantes.** Una fecha o un nombre variable rompe la comparación en cada corrida.
- **No congelar animaciones.** Una captura a medio movimiento nunca coincide con la siguiente.
- **Actualizar la línea base a ciegas.** Aprobar sin mirar las diferencias vacía de sentido la prueba.
- **Aflojar el umbral en vez de controlar el entorno.** La estabilidad viene de fijar entorno y datos, no de tolerar más.
- **Capturar páginas enteras muy largas.** Cuanto más grande la imagen, más frágil; conviene capturar componentes o zonas.
- **Confundir regresión visual con prueba funcional.** Una ve el aspecto, la otra el comportamiento; se complementan.

## Preguntas frecuentes

**¿Qué diferencia hay entre una prueba visual y una funcional?**
Comprueban cosas distintas y complementarias. Una prueba funcional verifica el comportamiento: que al hacer clic en un botón ocurra lo que debe ocurrir, que un formulario se envíe, que una cuenta dé el resultado correcto. No dice nada sobre cómo se ve la pantalla. Una prueba de regresión visual verifica justamente eso: el aspecto. Compara cómo se ve la interfaz ahora con cómo se veía antes y avisa si algo cambió. El caso donde se nota la diferencia es un ajuste de estilo que descoloca un elemento sin romper su función: todas las pruebas funcionales pasan porque el botón sigue funcionando, pero el diseño se rompió, y solo la prueba visual lo detecta. Un proyecto completo usa ambas.

**¿Qué es una línea base?**
Es la imagen de referencia con la que se comparan las capturas futuras: la foto de cómo se ve una pantalla cuando está correcta. La primera vez que corre la prueba no existe con qué comparar, así que la herramienta toma una captura y la guarda como línea base, versionada junto al código. A partir de ahí, cada ejecución toma una captura nueva de la misma pantalla y la compara contra esa línea base. Si coinciden dentro de la tolerancia, la prueba pasa; si difieren, falla y muestra las diferencias. Cuando un cambio visual es intencional, la línea base queda desactualizada y hay que regenerarla para que la nueva imagen pase a ser la referencia, siempre después de que una persona confirme que el cambio es el que se buscaba.

**¿Por qué mis pruebas visuales fallan sin que yo haya cambiado nada?**
Casi siempre por falsos positivos, que son el desafío central de la regresión visual. Las causas más comunes son las diferencias de renderizado de fuentes entre distintos sistemas operativos, que hacen que el mismo texto se dibuje con variaciones mínimas; los datos que cambian en cada ejecución, como una fecha, un nombre de usuario o un contador; las animaciones o el contenido dinámico capturados a mitad de movimiento; y las diferencias mínimas en los bordes por el suavizado. La solución no es aflojar la tolerancia hasta que deje de fallar, porque eso también dejaría pasar cambios reales, sino controlar el entorno para que sea siempre el mismo, fijar los datos con valores estables, congelar las animaciones antes de capturar, y ajustar el umbral solo lo justo para el suavizado.

**¿Cómo apruebo un cambio visual que sí quería hacer?**
Regenerando la línea base para que la nueva imagen pase a ser la referencia, pero solo después de verificar que el cambio es correcto. El flujo es: la prueba falla porque la interfaz cambió, mirás la imagen de diferencias que genera la herramienta, confirmás que ese cambio es el que buscabas y no un accidente, y recién entonces ejecutás el comando que actualiza las capturas de referencia. La nueva línea base se revisa y se versiona junto con el cambio de código que la motivó, para que quede claro por qué cambió. Lo que hay que evitar es actualizar a ciegas cada vez que algo falla, porque si aprobás cualquier diferencia sin mirarla, la prueba deja de servir para lo único que importa: atrapar el cambio que no querías.

**¿Necesito una herramienta especial o alcanza con Playwright?**
Para empezar, Playwright alcanza y sobra: trae la comparación visual incorporada con una sola aserción que gestiona las líneas base, la comparación píxel a píxel y la generación de imágenes de diferencias, sin necesidad de instalar nada más. Es el camino recomendado si ya usás Playwright para tus pruebas. Existen además servicios y herramientas dedicados a la regresión visual que agregan capacidades como comparación en la nube contra muchos navegadores y dispositivos, flujos de aprobación en equipo y detección más inteligente de cambios, que tienen sentido en proyectos grandes con equipos de diseño. Pero para la enorme mayoría de los casos, y desde luego para aprender, la funcionalidad nativa de Playwright cubre por completo lo que hace falta.

**¿Por qué es importante correr las pruebas visuales en el mismo entorno?**
Porque el aspecto exacto de una pantalla depende del entorno donde se renderiza: el sistema operativo, la versión del navegador y las fuentes instaladas influyen en cómo se dibujan el texto y los elementos. Si generás la línea base en tu computadora y la comparación corre en un entorno distinto, con otras fuentes u otro navegador, las dos capturas van a diferir por esas razones ajenas al código, y la prueba fallará con falsos positivos masivos que no señalan ningún problema real. Por eso las pruebas visuales se generan y comparan siempre en el mismo entorno, que en la práctica suele ser un contenedor idéntico tanto en tu máquina como en el pipeline, y muchas veces las líneas base que valen son las que produce el propio pipeline, no las de cada persona.

## Fuentes

Documentación oficial y material de la comunidad consultados para esta guía. Fecha de consulta: 28 de julio de 2026.

### Aportes de la comunidad Underc0de

1. **Underc0de, foro.** [Sección QA (Quality Assurance)](https://underc0de.org/foro/qa-testing/). Consultas sobre pruebas de interfaz y automatización.
2. **Underc0de, foro.** [Sección Desarrollo web](https://underc0de.org/foro/desarrollo-web/). Frontend y comportamiento visual de las páginas.

### Documentación oficial

1. **Playwright.** [Visual comparisons](https://playwright.dev/docs/test-snapshots). La comparación de capturas con toHaveScreenshot y la actualización de líneas base, citadas en la guía.
2. **Playwright.** [Page assertions](https://playwright.dev/docs/api/class-pageassertions). La referencia de la aserción y sus opciones de tolerancia.
3. **Mapbox.** [pixelmatch](https://github.com/mapbox/pixelmatch). La biblioteca de comparación de imágenes que Playwright usa por debajo.
4. **Playwright.** [Test configuration](https://playwright.dev/docs/test-configuration). Cómo configurar la tolerancia de forma global.

## Guías relacionadas

- [Playwright: cómo se usa](../como-instalar-y-usar-playwright/index.md)
- [Accesibilidad con axe](../testing-de-accesibilidad-con-axe-y-playwright/index.md)
- [Detectar y solucionar flaky tests](../como-detectar-y-solucionar-flaky-tests/index.md)
- [Pruebas en GitHub Actions](../pruebas-automaticas-con-github-actions/index.md)
- [Índice de Testing y QA](../index.md)