Playwright Trace Viewer: Depura Tests Fallidos Como un Pro

Un test que falla en CI pero no se reproduce en local es difícil de depurar con solo un stack trace. Trace Viewer graba cada acción, petición de red y snapshot del DOM durante el test, y te permite abrir una reproducción en el navegador después. El snapshot Before en la acción fallida muestra lo que Playwright realmente vio: qué elemento estaba resaltado, si había una capa encima cubriéndolo, si la respuesta de la API todavía estaba en vuelo cuando se ejecutó el clic.

Qué es el Trace Viewer

Trace Viewer es una aplicación web local que registra todo lo que ocurrió durante una ejecución de tests: cada acción, cada petición de red, cada snapshot del DOM en cada paso. Lo abres después de la ejecución, recorres una línea de tiempo y ves exactamente qué estaba mostrando el navegador cuando el test falló.

Es la diferencia entre leer un stack trace y ver una reproducción.

Activar las trazas

Por defecto, las trazas están desactivadas. Las activas en playwright.config.ts:

use: {
  trace: 'on-first-retry',
},

| Valor | Cuándo usarlo |

|---|---|

| 'off' | Por defecto, no genera trazas |

| 'on' | En cada ejecución, cada test. Útil en local, demasiado lento para suites grandes en CI |

| 'on-first-retry' | Solo cuando un test hace retry. La mejor opción para CI: mínimo overhead, captura los fallos |

| 'retain-on-failure' | Guarda trazas solo para los tests fallidos. Buen balance para depuración local |

Para CI, 'on-first-retry' es la elección estándar. Para depurar un test específico en local, cámbialo a 'on' temporalmente.

Abrir una traza

Después de una ejecución fallida, Playwright crea archivos zip dentro de test-results/. Para abrir uno:

npx playwright show-trace test-results/my-test-chromium/trace.zip

Si ejecutaste los tests con el reporter HTML, abre playwright-report/index.html y haz clic en el ícono de traza junto a un test fallido. La traza se abre automáticamente.

Leer la línea de tiempo

La interfaz del Trace Viewer tiene tres paneles:

Debajo de los snapshots: la pestaña Network (todas las peticiones HTTP en ese momento), la pestaña Console (cualquier salida de console.log) y la pestaña Source (qué línea de tu test generó esa acción).

El flujo para depurar un fallo

1. Encuentra la acción fallida en la lista de acciones; aparece en rojo.

2. Haz clic. Mira el snapshot Before.

3. Pregúntate: ¿el elemento es visible? ¿Está deshabilitado? ¿Hay algo tapándolo?

4. Si el elemento parece correcto pero la acción falló, revisa Network: ¿había una llamada API lenta todavía en vuelo?

5. Revisa Console: ¿algún error de JavaScript que explique el estado?

La mayoría de los fallos quedan claros en 30 segundos de abrir la traza. El snapshot del DOM te muestra lo que Playwright veía en realidad, que casi siempre es diferente de lo que tú asumías que veía.

Patrones de fallo comunes en las trazas

Problemas de tiempo

La lista de acciones muestra un page.waitForURL o locator.waitFor que expiró. El snapshot Before muestra que el elemento todavía no existe. Solución: agrega una espera explícita por el elemento que indica que la página está lista, no un timeout genérico.

Violaciones de modo estricto

Usaste un locator que coincide con múltiples elementos. El snapshot Before te lo muestra: pasa el cursor sobre los elementos resaltados para contarlos.

Estado del test anterior

El snapshot Before de tu primera acción muestra que el usuario ya está logueado, o hay una notificación toast tapando un botón. Tu test asumió un estado limpio. Solución: agrega aislamiento de test correcto.

Animación o transición bloqueando el clic

El snapshot Before muestra el elemento, el After no muestra que pasó nada. Una transición CSS estaba en curso cuando Playwright hizo clic. Solución: espera que animation: none esté activo, o usa locator.click({ force: true }) como depuración temporal (nunca en tests finales).

Elemento incorrecto seleccionado

El snapshot Before muestra que Playwright resaltó un elemento completamente diferente al esperado. Tu selector está coincidiendo con otra cosa en la página. Corrige el locator.

Trazas en CI

Al ejecutar en GitHub Actions, agrega un paso para subir el artefacto con las trazas:

- name: Ejecutar tests
  run: npx playwright test

- name: Subir trazas
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: playwright-traces
    path: test-results/
    retention-days: 7

Descarga el artefacto después de una ejecución fallida, descomprímelo y ábrelo con npx playwright show-trace. Ves la misma reproducción que verías en local: el estado del navegador en el entorno de CI en el momento del fallo.

Combinar trazas con capturas de pantalla y video

Playwright también puede capturar capturas de pantalla ante fallos y grabaciones de video completas:

use: {
  screenshot: 'only-on-failure',
  video: 'retain-on-failure',
  trace: 'on-first-retry',
},

Usa los tres para depurar fallos complicados. Las capturas te dan una imagen estática; el video te muestra la ejecución completa; la traza te muestra la ejecución completa más cada estado del DOM más las llamadas de red. Se complementan: una captura de pantalla no tiene lo que pasó cinco segundos antes del fallo; la traza sí.

Para CI de rutina, la traza sola es suficiente. El video agrega un overhead significativo y generalmente vale la pena solo para fallos intermitentes que no puedes reproducir en local.

Cuando las trazas no son suficientes

Trace Viewer muestra el estado del navegador. No muestra el estado del servidor. Si tu test falla porque la API devolvió datos inesperados, la traza te mostrará la respuesta incorrecta en la pestaña Network, pero no te dirá por qué el backend la devolvió así.

Para esos fallos, combina los datos de la traza (para ver cuál fue la respuesta) con los logs del backend (para entender por qué). La traza te lleva a la pregunta correcta; los logs la responden.