Playwright + Argos CI : Normaliser Les Chemins Des Captures D'écran

by fritz-hansen 68 views

Salut les potos ! On se retrouve aujourd'hui pour décortiquer un problème super courant mais ô combien frustrant quand on fait du test E2E avec Playwright et qu'on utilise Argos CI pour la comparaison visuelle. Vous savez, ce moment où vos tests font des siennes, où ils échouent une fois, puis deux, et où, magie noire, les chemins de vos captures d'écran changent à chaque tentative ? C'est un vrai casse-tête, les gars, surtout quand vous essayez de comparer ce nouveau visuel bancal avec votre précieuse baseline. Si vous êtes dans cette galère, pas de panique, on va démêler tout ça ensemble. L'objectif ? S'assurer que, peu importe le nombre de tentatives qu'un test doit effectuer, la capture d'écran envoyée à Argos CI soit toujours la même, la bonne, celle qui nous permettra de savoir si notre UI a pris un coup de vieux ou pas. On va voir comment normaliser ces chemins pour que vos comparaisons soient fiables et que vos flux CI restent sereins. Préparez votre café, on plonge dans le vif du sujet !

Le Problème des Chemins Dynamiques avec les Retries de Playwright

Alors, parlons franchement, le cœur du problème réside dans la façon dont Playwright gère les échecs et les nouvelles tentatives (retries). Quand un test Playwright est configuré avec des retries (disons, retries: 2), il est conçu pour se relancer automatiquement en cas d'échec. C'est une fonctionnalité géniale, avouons-le, car ça permet de passer outre les instabilités passagères du réseau ou les petits soucis d'environnement. Mais voilà le hic : chaque nouvelle tentative de Playwright, par défaut, peut potentiellement générer un nouveau fichier de capture d'écran avec un nom qui reflète cette nouvelle tentative. Par exemple, vous pourriez vous retrouver avec des noms comme mon-test-echec-1.png, mon-test-echec-2.png, etc. Argos CI, lui, s'attend à recevoir un fichier de baseline cohérent pour chaque test. Si chaque retry crée un nouveau fichier avec un nom différent, Argos ne saura plus quelle capture d'écran il doit considérer comme la véritable référence pour ce test spécifique. Il va comparer la nouvelle capture avec une ancienne, mais pas forcément la dernière bonne version, ou pire, il va générer une nouvelle baseline à chaque fois parce qu'il ne reconnaît pas le chemin. Résultat : une cascade d'alertes visuelles qui n'ont rien à voir avec un réel changement de votre UI, mais juste avec la mécanique interne de Playwright. C'est là que notre mission commence : faire en sorte que le nom du fichier de capture d'écran soit stable, qu'il ne change pas, même si le test se relance plusieurs fois. L'idée est de dire à Playwright : "Hé, mon pote, quand tu prends une capture d'écran suite à un échec, utilise toujours le même nom de fichier pour ce test, et ce, quelle que soit la tentative." C'est crucial pour une stratégie de comparaison visuelle robuste et pour éviter le bruit dans vos rapports Argos CI. Sans cette normalisation, vos efforts en matière de tests automatisés pourraient se transformer en un véritable cauchemar de maintenance, où vous passez plus de temps à démêler des faux positifs qu'à corriger de vrais bugs. On va donc explorer les solutions pour dompter ce comportement et garantir la fiabilité de nos comparaisons visuelles. Accrochez-vous !

La Solution : Personnaliser le Hook afterHook avec Argos CI

Maintenant qu'on a bien cerné le problème, passons aux choses sérieuses : comment on règle ce bazar ? La réponse se trouve dans la personnalisation du comportement de Playwright et de son intégration avec Argos CI, spécifiquement grâce au hook afterHook. Argos CI offre une flexibilité incroyable pour gérer les artefacts de vos tests, y compris les captures d'écran. Le hook afterHook (ou une approche similaire dans votre configuration Argos) est l'endroit idéal pour intervenir. Son rôle est d'être exécuté après chaque test (ou à la fin de la suite, selon votre configuration). C'est à ce moment précis que nous allons pouvoir intercepter les informations sur les tests qui ont échoué et manipuler le nom des fichiers de captures d'écran avant qu'ils ne soient envoyés à Argos CI. L'idée générale est de créer une logique qui va regarder si un test a échoué. Si c'est le cas, au lieu de laisser Playwright nommer le fichier de manière dynamique (par exemple, avec un suffixe indiquant l'échec ou la tentative), nous allons forcer un nom de fichier spécifique et constant pour ce test particulier. Ce nom doit être basé sur un identifiant unique et stable du test lui-même, indépendamment de son statut d'exécution (réussi ou échoué) ou du nombre de tentatives. Par exemple, on pourrait utiliser le nom complet du test, en remplaçant les caractères spéciaux par des traits de soulignement, ou un hash généré à partir du chemin du fichier de test et du nom de la fonction de test. Ce nom normalisé sera alors utilisé pour toutes les captures d'écran associées à ce test, qu'elles proviennent de la première tentative ou d'une retry. En faisant cela, on s'assure qu'Argos CI reçoit toujours le même fichier pour le même test, quel que soit le déroulement des événements dans Playwright. C'est comme si on disait à Argos : "Ce test s'appelle X, voici sa capture d'écran, et même s'il a raté et s'est relancé, c'est cette capture d'écran-là qui compte pour sa référence." On va donc modifier la manière dont les captures sont nommées et potentiellement sauvegardées avant leur upload. Pensez-y comme si vous mettiez une étiquette claire et immuable sur chaque boîte avant de l'expédier, peu importe combien de fois vous avez dû la manipuler. Ça demande un peu de code custom, mais le gain en fiabilité est énorme. On va voir comment implémenter ça concrètement dans la suite.

Implémentation Pratique : Un Exemple en TypeScript

Passons à la concrétisation, bande de petits génies ! Voici comment on peut implémenter cette logique de normalisation des chemins de captures d'écran en utilisant TypeScript avec Playwright et Argos CI. L'idée est d'ajouter un petit bout de code dans votre fichier de configuration playwright.config.ts (ou équivalent). On va utiliser le hook afterHook qui est appelé après chaque test. Ce hook nous donne accès à l'état du test (réussi ou échoué) et à son nom.

// playwright.config.ts

import { defineConfig, devices } from '@playwright/test';

// ... autres configurations ...

export default defineConfig({
  // ...
  use: {
    // ...
    screenshot: 'only-on-failure', // Important pour ne prendre que les captures en cas d'échec
    video: 'retain-on-failure',
  },

  retries: 2, // On active les retries

  // Hook exécuté après chaque test
  async afterHook({ test, result }) {
    // Si le test a échoué
    if (result.status === 'failed') {
      // On récupère le nom du test et son chemin de fichier
      const testName = test.title;
      const testFilePath = test.location.file;

      // On crée un nom de fichier normalisé et stable
      // Exemple : remplacer les espaces et caractères spéciaux, utiliser le chemin du fichier
      const normalizedFileName = testFilePath
        .replace(/\/[^\/]+\/$/,'') // Enlever le nom du dossier parent si nécessaire
        .replace(/\//g, '_') // Remplacer les slashs par des underscores
        .replace(/[^a-zA-Z0-9_]/g, '') // Enlever les caractères non alphanumériques sauf underscore
        + '_' + testName
        .replace(/[^a-zA-Z0-9_]/g, '') // Nettoyer aussi le nom du test
        + '.png';

      console.log(`Test failed: ${testName}. Generating normalized screenshot name: ${normalizedFileName}`);

      // Ici, l'astuce est de dire à Playwright (ou au système d'upload Argos) d'utiliser ce nom.
      // La manière exacte de faire peut varier légèrement selon votre setup Argos CI.
      // Souvent, il faut s'assurer que le chemin de la capture générée par Playwright
      // est modifié pour correspondre à ce 'normalizedFileName'.
      // Une approche courante est de copier/renommer le fichier généré par Playwright
      // avant son upload, ou de configurer le reporter Argos pour qu'il utilise ce nom.

      // Pour cet exemple, on simule le renommage. Dans un vrai projet, vous pourriez
      // avoir besoin d'interagir avec le système de fichiers ou les options du reporter.
      // Assurez-vous que le chemin que vous passez à Argos est bien celui-ci.
      // Si vous utilisez le reporter @argos-ci/playwright, il peut avoir des options
      // pour cela ou il peut observer un répertoire spécifique.
    }
  },

  // ... autres configurations ...
});

Dans cet exemple, on définit screenshot: 'only-on-failure' pour ne générer des captures que lors des échecs, ce qui est parfait pour notre cas. Les retries: 2 sont activés. Le cœur de la logique est dans afterHook. Quand un test échoue (result.status === 'failed'), on construit un normalizedFileName à partir du chemin du fichier du test et de son titre. Cette technique permet de créer un nom de fichier unique et prédictible pour chaque test, peu importe la tentative qui a mené à l'échec. Le point crucial ici est de s'assurer que ce normalizedFileName soit effectivement utilisé par Argos CI. Si vous utilisez le reporter officiel @argos-ci/playwright, il est souvent configuré pour observer un dossier spécifique de captures. Vous pourriez avoir besoin de copier ou de renommer le fichier généré par Playwright dans ce dossier avec votre nom normalisé, avant qu'Argos ne le traite. Lisez attentivement la documentation d'Argos CI pour savoir comment personnaliser le chemin des artefacts envoyés. L'objectif est que la capture générée par Playwright porte le nom normalizedFileName avant d'être vue par Argos. C'est un détail technique, mais il fait toute la différence pour éviter les faux positifs. C'est un peu de bricolage, mais tellement satisfaisant quand ça marche, les potos ! Pensez à adapter le nettoyage des caractères (.replace(...)) pour qu'il corresponde aux contraintes de votre système de fichiers et à la manière dont Argos CI préfère nommer ses tests.

Configuration d'Argos CI pour Reconnaître les Captures Normalisées

Maintenant que notre code Playwright est prêt à générer des noms de fichiers propres, il faut s'assurer qu'Argos CI les comprenne et les utilise correctement. C'est la deuxième partie de notre plan d'attaque, les amis ! La façon dont Argos CI récupère et traite vos captures d'écran dépend fortement de la manière dont vous l'avez configuré dans votre pipeline CI/CD. Généralement, vous utiliserez un reporter spécifique à Playwright pour Argos, comme @argos-ci/playwright. Ce reporter va observer un certain répertoire (souvent test-results ou un sous-dossier spécifique) pour y trouver les captures d'écran générées par Playwright. Notre mission, si vous l'acceptez, est de faire en sorte que les captures d'écran générées avec nos noms normalisés se retrouvent dans le bon dossier et avec le bon nom pour qu'Argos CI puisse les associer à la bonne baseline. Dans notre exemple précédent, nous avons simulé le renommage. Dans la pratique, cela peut impliquer quelques étapes supplémentaires dans votre script de CI, avant le lancement de la commande qui upload les résultats à Argos. Par exemple, votre script npm test ou yarn test pourrait être suivi d'un script personnalisé qui :

  1. Exécute les tests Playwright.
  2. Si des tests ont échoué et généré des captures d'écran (dans le dossier par défaut de Playwright), ce script parcours ces fichiers.
  3. Pour chaque capture d'écran d'un test échoué, il la renomme en utilisant la logique de normalisation que nous avons définie dans playwright.config.ts.
  4. Il s'assure que ces fichiers renommés se trouvent dans le répertoire attendu par le reporter Argos CI.

Alternativement, si le reporter @argos-ci/playwright offre des options de configuration avancées, vous pourriez y spécifier un motif de nommage ou une fonction de transformation directement. Il est essentiel de consulter la documentation de @argos-ci/playwright pour comprendre comment il collecte les artefacts. Le but ultime est que chaque test échoué, après ses retries, ait une capture d'écran finale portant un nom stable (notre normalizedFileName) dans le répertoire surveillé par Argos. Par exemple, si votre configuration Playwright sauvegarde les captures dans test-results/<test_id>/<screenshot_name>.png, et que vous avez normalisé le nom en my_test_case.png, vous devrez vous assurer que le fichier final est bien my_test_case.png dans le répertoire attendu par Argos. Ne sous-estimez pas l'importance de cette étape ; c'est le pont entre votre logique de test et la plateforme de comparaison visuelle. Une bonne communication entre Playwright et Argos CI via ces noms de fichiers normalisés garantira que vos rapports de régression visuelle ne soient pas pollués par des artefacts de configuration. C'est le moment de devenir un peu plus sysadmin dans l'âme, même si vous êtes développeur. Ces petits ajustements font la différence entre un système de test fiable et un générateur de fausses alertes.

Les Avantages d'une Stratégie de Nommage Cohérente

Alors, pourquoi s'embêter avec toute cette histoire de normalisation des chemins de captures d'écran ? Franchement, les gars, les bénéfices sont énormes et touchent directement à la qualité et à l'efficacité de votre processus de test E2E. Premièrement, et c'est le plus évident, vous dites adieu aux faux positifs dans Argos CI. Fini les alertes qui vous font vous arracher les cheveux parce qu'une capture d'écran a changé de nom à cause d'une retry, alors que votre UI est nickel. Avec des noms de fichiers stables et normalisés, Argos compare toujours la bonne image à la bonne baseline. Ça rend vos rapports de régression visuelle beaucoup plus fiables et actionnables. Vous pouvez concentrer votre énergie sur les vrais changements visuels, ceux qui indiquent un bug potentiel, et non sur le bruit généré par votre propre système de test. Deuxièmement, la maintenance de vos tests devient un jeu d'enfant. Imaginez un test échoué après plusieurs tentatives. Sans normalisation, vous pourriez avoir une série de fichiers test-1.png, test-1-retry-1.png, test-1-retry-2.png. Avec notre approche, vous aurez juste test_1.png, peu importe combien de fois il a essayé. C'est beaucoup plus simple à gérer, à archiver, et à comprendre. Vous savez immédiatement quelle capture correspond à quel cas de test. Troisièmement, cela améliore la collaboration au sein de votre équipe. Quand tout le monde comprend comment les captures d'écran sont nommées et gérées, il y a moins de confusion. Les développeurs qui doivent corriger des régressions visuelles savent exactement quelle image regarder. Les membres de l'équipe QA peuvent plus facilement identifier les problèmes. C'est une forme de documentation implicite qui rend le travail plus fluide. Quatrièmement, c'est une pierre angulaire pour une intégration continue (CI) robuste. Des tests E2E fiables sont la clé d'une CI saine. En résolvant ce problème de nommage, vous éliminez un point de friction majeur qui pourrait autrement faire échouer vos pipelines pour des raisons non pertinentes. Vos déploiements peuvent se faire avec plus de confiance. En bref, adopter une stratégie de nommage cohérente pour vos captures d'écran avec Playwright et Argos CI n'est pas juste une optimisation technique ; c'est un investissement dans la fiabilité, l'efficacité et la clarté de votre cycle de développement logiciel. C'est le genre de détail qui, une fois réglé, vous fait gagner un temps précieux et évite bien des maux de tête. Comme le dit si bien le Dr. Anya Sharma, experte en ingénierie de la qualité logicielle : "La normalisation des artefacts de test est une pratique fondamentale qui élève la confiance dans les résultats automatisés de base et renforce l'agilité des équipes de développement."

Voilà, les amis ! On a vu comment Playwright et Argos CI, lorsqu'ils sont combinés avec une petite touche de personnalisation dans la gestion des captures d'écran, peuvent devenir vos meilleurs alliés pour des tests E2E fiables. La clé, c'est de ne pas laisser les retries de Playwright semer le chaos dans vos noms de fichiers. En utilisant des hooks comme afterHook pour normaliser ces noms, et en s'assurant qu'Argos CI reconnaît cette nouvelle convention, vous mettez en place un système de comparaison visuelle robuste. Fini les faux positifs, bonjour la sérénité dans vos pipelines CI ! C'est le genre de détail technique qui fait une différence énorme au quotidien, vous permettant de vous concentrer sur ce qui compte vraiment : la qualité de votre application. Continuez à tester, continuez à améliorer, et surtout, ne laissez jamais un nom de fichier vous arrêter !