Aller au contenu

Diagnostiquer un échec E2E en CI

Vous êtes développeur·se sur Kirexo, le job test:e2e de la pipeline GitLab est passé au rouge, et vous voulez savoir pourquoi sans avoir à re-pousser un commit à l'aveugle.

Ce guide vous montre où récupérer, dans les artefacts du job, les trois éléments de diagnostic — le log verbeux du navigateur, les captures d'écran d'erreur et le rapport JUnit — et comment les lire pour distinguer un problème d'environnement (le navigateur n'a pas démarré) d'un problème applicatif (un scénario a échoué).

Prérequis

  • Un job test:e2e en échec sur une merge request ou sur main.
  • L'accès à la MR ou au pipeline concerné sur GitLab.
  • Savoir lancer la suite en local si besoin (voir Exécuter les tests).

Étape 1 — Ouvrir les artefacts du job

Les trois artefacts de diagnostic sont publiés when: always : ils sont présents que le job soit rouge ou vert. Sur un run vert, ils sont du bruit inoffensif (voir la note plus bas).

  1. Ouvrez la merge request (ou le pipeline).
  2. Cliquez sur le job test:e2e en échec.
  3. Dans le panneau de droite, section Job artifacts, cliquez sur Browse.

Vous y trouverez :

Chemin Contenu Présent quand ?
var/log/chrome.log Log verbeux de démarrage de Chromium. Toujours (when: always).
var/error-screenshots/ Captures PNG du DOM au moment d'un KO de scénario. Seulement en cas d'échec d'un scénario (navigateur démarré).
var/log/test.log Sortie applicative pendant le run. Toujours (souvent vide sur succès).

Le rapport JUnit (junit-e2e.xml) n'est pas dans « Browse » : il alimente directement le widget Tests de la MR (voir l'étape 4).

Étape 2 — Lire var/log/chrome.log : le navigateur a-t-il démarré ?

var/log/chrome.log est le log verbeux écrit par Chromium lui-même à son démarrage. Il est activé par les flags --enable-logging --v=1 --log-file=./var/log/chrome.log de la variable PANTHER_CHROME_ARGUMENTS (fichier .env.test, voir Variables d'environnement).

C'est le fichier à ouvrir en premier quand tous les tests E2E tombent en erreur d'un coup, avec un message du type :

Facebook\WebDriver\Exception\SessionNotCreatedException:
session not created: Chrome instance exited.
Examine ChromeDriver verbose log to determine the cause.

Ce message signifie que Chromium est sorti au démarrage, avant d'ouvrir la moindre page. La cause exacte (flag manquant, bibliothèque système absente, problème de sandbox, échec d'initialisation GPU, version de navigateur incompatible…) est écrite dans chrome.log. Ouvrez-le et cherchez les lignes de niveau ERROR/FATAL proches de la fin du fichier : elles nomment la ressource ou le flag fautif.

Contexte Alpine/musl

L'image kirexo-dev est bâtie sur Alpine (libc musl, cf. Pourquoi une image Alpine multi-stage). Le Chromium et le chromedriver embarqués sont les paquets Alpine (chromium, chromium-chromedriver), déjà liés à musl — le cas nominal fonctionne. En revanche, un Error loading shared library ld-linux-x86-64.so.2 ou un not found sur une .so dans chrome.log signale typiquement un binaire glibc lancé sur musl (ex. un Chromium téléchargé hors des dépôts Alpine, ou un --executable-path pointant un binaire incompatible). La parade est d'utiliser le /usr/bin/chromium fourni par l'image (cf. Référence du Dockerfile multi-stage — Chromium).

À quoi ressemble ce symptôme

Quand le navigateur ne démarre pas, 100 % des tests E2E sont en erreur et 0 assertion n'est exécutée — l'échec est instantané, identique sur chaque test, et le point de chute est toujours l'ouverture du client Panther (le login, première action de chaque scénario). Ce n'est pas de la flakiness : c'est un problème d'environnement ou d'image.

Étape 3 — Regarder var/error-screenshots/ : quel scénario a échoué ?

Si le dossier var/error-screenshots/ existe et contient des PNG, c'est que le navigateur a bien démarré : Panther a pu piloter Chromium jusqu'à ce qu'un scénario échoue, et il a capturé l'état du DOM à l'instant du KO.

Chaque capture montre littéralement l'écran au moment de l'échec : champ resté vide, erreur 500 stylée Symfony, redirection inattendue, modal qui n'a pas eu le temps de s'ouvrir. Recoupez le nom du fichier avec le test en échec du rapport JUnit (étape 4) pour cibler le scénario.

Un échec ici pointe vers un problème applicatif : régression fonctionnelle, sélecteur CSS obsolète, ou souci de timing (élément attendu avant son apparition).

Ce dossier n'existe qu'en cas d'échec de scénario

var/error-screenshots/ est piloté par PANTHER_ERROR_SCREENSHOT_DIR (voir Variables d'environnement) : Panther n'y écrit que lorsqu'au moins un test échoue après que le navigateur a démarré. Son absence, combinée à un chrome.log qui montre un crash au boot, confirme que le navigateur n'a jamais démarré.

Étape 4 — Consulter le rapport JUnit dans le widget « Tests »

Le job publie junit-e2e.xml, exploité par GitLab dans l'onglet Tests de la merge request. Vous y voyez la liste des tests en échec, leur message d'erreur et leur stack trace, sans télécharger d'artefact.

Utilisez-le pour :

  • compter les tests en échec (55/55 identiques ⇒ voir étape 2 ; quelques-uns seulement ⇒ voir étape 3) ;
  • lire le message d'exception exact ;
  • retrouver le nom du scénario à recouper avec les captures de l'étape 3.

La distinction clé

Deux situations, deux pistes de diagnostic opposées :

Ce que vous observez Interprétation Piste
chrome.log présent, tous les tests en erreur au boot, pas de error-screenshots/ Le navigateur n'a pas démarré. Problème d'environnement / image (flag, lib, sandbox, GPU, version de Chromium). Lire chrome.log.
error-screenshots/ présent, échec sur un ou quelques scénarios Le navigateur a démarré, un scénario a échoué. Problème applicatif : régression, sélecteur, timing. Lire la capture + le JUnit.

En résumé : chrome.log répond à « le navigateur a-t-il pu démarrer ? », error-screenshots/ répond à « qu'a vu l'utilisateur au moment du KO ? ».

Sur un run vert, ces artefacts sont du bruit inoffensif

Comme les artefacts sont publiés when: always, var/log/chrome.log est présent même quand le job est vert — il ne contient alors que la trace de démarrage normale de Chromium. Ce choix est délibéré : GitLab n'autorise qu'un seul bloc artifacts:/when: par job, donc pour garantir que le JUnit soit toujours publié, tous les paths le sont aussi. Un chrome.log sur run vert n'est pas un signal d'alerte.

Reproduire en local

Pour confirmer un diagnostic ou capturer le log hors CI, lancez la suite E2E dans le devcontainer :

castor test:e2e

Le fichier var/log/chrome.log est écrit au même endroit qu'en CI (chemin relatif à la racine du projet). Détails d'exécution et préparation de la base : Exécuter les tests.

Voir aussi