Playwright Trace Viewer: Déboguez les Tests Échoués Comme un Pro

Le Trace Viewer de Playwright enregistre chaque action, chaque requête réseau et chaque snapshot du DOM pendant un test. Vous pouvez ensuite les rejouer pas à pas dans une interface navigateur après coup.

Ce qu'est réellement le Trace Viewer

Le Trace Viewer est une application web locale qui enregistre tout ce qui s'est passé pendant un test : chaque action, chaque requête réseau, chaque snapshot DOM à chaque étape. On l'ouvre après l'exécution, on parcourt une timeline, et on voit exactement ce que le navigateur affichait quand le test a échoué.

C'est la différence entre lire une stack trace et regarder un replay.

Activer les traces

Par défaut, les traces sont désactivées. Pour les activer dans playwright.config.ts :

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

Les quatre options disponibles :

| Valeur | Quand l'utiliser |

|---|---|

| 'off' | Par défaut, aucune trace générée |

| 'on' | Chaque exécution, chaque test. Utile en local, trop lent pour de grandes suites CI |

| 'on-first-retry' | Uniquement quand un test est retenté. Idéal pour la CI : surcharge minimale, capture les échecs |

| 'retain-on-failure' | Conserve les traces uniquement pour les tests échoués. Bon compromis pour le débogage local |

Pour la CI, 'on-first-retry' est le choix standard. Pour déboguer un test spécifique en local, passez temporairement à 'on'.

Ouvrir une trace

Après un échec, Playwright crée des fichiers zip dans test-results/. Pour en ouvrir un :

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

Si vous avez utilisé le reporter HTML, ouvrez playwright-report/index.html et cliquez sur l'icône de trace à côté d'un test échoué. La trace s'ouvre automatiquement.

Lire la timeline

L'interface du Trace Viewer comporte trois panneaux.

Timeline (haut) : une barre horizontale montrant la durée totale du test. Chaque action est représentée par un segment. Cliquer sur un segment saute à ce moment précis. Liste des actions (gauche) : chaque étape dans l'ordre, soit page.goto, locator.click, expect et les appels réseau. Chacune a une durée. Les actions lentes ressortent immédiatement. Snapshots (droite) : l'état du DOM à l'action sélectionnée. Deux onglets apparaissent, Before (ce que la page affichait quand Playwright a démarré l'action) et After (ce qu'elle affichait quand l'action s'est terminée).

Sous les snapshots : l'onglet Network (toutes les requêtes HTTP à ce moment), l'onglet Console (toute sortie console.log), l'onglet Source (quelle ligne du test a déclenché cette action).

La méthode pour déboguer un échec

1. Trouvez l'action en échec dans la liste des actions ; elle est marquée en rouge.

2. Cliquez dessus. Regardez le snapshot Before.

3. Demandez-vous : l'élément est-il visible ? Est-il désactivé ? Un overlay le bloque-t-il ?

4. Si l'élément semble correct mais que l'action a échoué, vérifiez Network : y avait-il un appel API lent encore en cours ?

5. Vérifiez Console : des erreurs JavaScript expliquent-elles l'état ?

La plupart des échecs deviennent évidents en 30 secondes après l'ouverture de la trace. Le snapshot DOM montre ce que Playwright voyait réellement, ce qui est presque toujours différent de ce qu'on supposait.

Patterns d'échec courants et leur aspect dans les traces

Problèmes de timing : la liste des actions montre un page.waitForURL ou locator.waitFor qui a expiré. Le snapshot Before montre que l'élément n'existe pas encore. Ajouter une attente explicite sur l'élément qui signale la disponibilité, pas un simple timeout. Violations du mode strict : vous avez utilisé un locator qui correspond à plusieurs éléments. Le snapshot Before le confirme. Survolez les éléments surlignés pour les compter. État venant du test précédent : le snapshot Before de votre première action montre que vous êtes déjà connecté, ou qu'une notification toast recouvre un bouton. Le test supposait un état propre. Ajouter une isolation correcte des tests. Animation ou transition bloquant le clic : le snapshot Before montre l'élément, le snapshot After ne montre aucun changement. Une transition CSS était en cours quand Playwright a cliqué. Attendre animation: none ou utiliser locator.click({ force: true }) comme débogage temporaire (jamais dans les tests finaux). Mauvais élément sélectionné : le snapshot Before montre que Playwright a surligné un élément complètement différent de celui attendu. Le sélecteur correspond à autre chose sur la page. Corrigez le locator.

Traces en CI

Dans GitHub Actions, ajoutez une étape pour uploader l'artefact de traces :

- name: Exécuter les tests
  run: npx playwright test

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

Téléchargez l'artefact après un échec, dézippez-le, et ouvrez-le avec npx playwright show-trace. Vous voyez le même replay qu'en local : l'état du navigateur dans l'environnement CI au moment de l'échec.

Combiner traces, screenshots et vidéo

Playwright peut aussi capturer des screenshots en cas d'échec et des enregistrements vidéo complets :

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

Pour déboguer des échecs difficiles, les trois ensemble sont utiles. Un screenshot donne une image statique ; la vidéo donne l'exécution complète ; la trace donne l'exécution complète plus chaque état DOM plus les appels réseau. Ils se complètent : un screenshot manque ce qui s'est passé cinq secondes avant l'échec ; la trace a tout.

Pour la CI de routine, la trace seule suffit. La vidéo ajoute une surcharge significative et ne vaut généralement le coup que pour les échecs intermittents impossibles à reproduire en local.

Quand les traces ne suffisent pas

Le Trace Viewer montre l'état du navigateur. Pas l'état du serveur. Si le test échoue parce que l'API a renvoyé des données inattendues, la trace montre la mauvaise réponse dans l'onglet Network, mais n'explique pas pourquoi le backend l'a renvoyée.

Pour ces échecs, combinez les données de trace (pour voir quelle était la réponse) avec les logs backend (pour comprendre pourquoi). La trace vous amène à la bonne question ; les logs y répondent.