Le test visuel dans GitLab CI/CD est l'intégration d'une étape automatisée de capture et de comparaison de screenshots au sein d'un pipeline défini dans .gitlab-ci.yml, exploitant les artifacts pour stocker les captures et les environments pour contextualiser les résultats, afin de détecter toute régression visuelle avant qu'un merge request ne soit accepté.
GitLab CI/CD est le concurrent direct de GitHub Actions. Si vous avez choisi GitLab pour votre stack — et des millions d'équipes l'ont fait — vous disposez d'un système CI/CD natif puissant, profondément intégré à votre gestionnaire de code. Et ce système possède des fonctionnalités qui le rendent particulièrement adapté au test visuel.
Pourtant, combien de fichiers .gitlab-ci.yml incluent une étape de vérification visuelle ? Très peu. La majorité se contentent de builder, tester le code fonctionnellement, et déployer. L'apparence de l'application — ce que l'utilisateur voit réellement — n'est vérifiée que manuellement, quand elle l'est.
Notre position : GitLab CI est parfait pour le test visuel, grâce à ses artifacts et ses environments. Ces deux fonctionnalités, souvent sous-exploitées, offrent une infrastructure idéale pour stocker les screenshots, comparer les résultats entre branches, et contextualiser les régressions. Si vous utilisez GitLab et que vous ne faites pas de test visuel, vous laissez dormir le potentiel de votre pipeline.
Ce que GitLab CI Offre de Spécifique pour le Test Visuel
GitLab CI possède des fonctionnalités que ses concurrents n'offrent pas — ou pas aussi bien. Pour le test visuel, trois d'entre elles sont particulièrement précieuses.
Les artifacts : votre bibliothèque de screenshots
Les artifacts dans GitLab CI permettent de sauvegarder des fichiers produits par un job et de les rendre accessibles après l'exécution du pipeline. Pour le test visuel, c'est exactement ce qu'il vous faut.
Chaque exécution du pipeline produit des captures d'écran. Ces captures doivent être conservées pour deux raisons. D'abord, pour que l'équipe puisse les consulter quand un test échoue. Ensuite, pour servir de références pour les futures comparaisons.
Les artifacts GitLab offrent une gestion fine de la rétention. Vous pouvez conserver les screenshots des sept derniers jours, ou des trente derniers jours pour la branche principale. Vous pouvez les télécharger directement depuis l'interface GitLab, ou les parcourir via le browser d'artifacts intégré.
Les environments : contextualiser vos captures
Les environments GitLab permettent d'associer un déploiement à un contexte nommé (staging, production, review/feature-xyz). Pour le test visuel, cela signifie que chaque capture est rattachée à un environnement spécifique.
Quand vous déployez une branche feature dans un environment de review, les screenshots capturés sont liés à cet environment. Vous pouvez comparer les captures de l'environment de review à celles de l'environment de staging ou de production. C'est un niveau de traçabilité que peu de systèmes CI/CD offrent nativement.
Le browser d'artifacts intégré
GitLab propose un navigateur de fichiers directement dans l'interface web pour explorer les artifacts. Pour le test visuel, cela signifie que votre équipe peut consulter les screenshots, les diffs visuels, et les rapports de comparaison sans quitter GitLab. Pas d'outil tiers à ouvrir. Pas de lien externe à suivre. Tout est dans le même écosystème.
Le Problème des Pipelines Visuellement Aveugles
Reprenons les faits. Un pipeline GitLab CI typique exécute les étapes suivantes : lint, test unitaire, test d'intégration, build, deploy. Cinq étapes. Zéro vérification visuelle.
Ce pipeline est capable de vous dire si une fonction retourne le mauvais résultat. Il est incapable de vous dire si la moitié de votre page d'accueil est masquée par un composant mal positionné.
Voici ce qui arrive dans la vraie vie. Un développeur modifie un fichier CSS partagé. Le changement est minime : un ajustement de marge sur un composant. Le pipeline passe. La merge request est approuvée par un reviewer qui a lu le diff sans visualiser le rendu. Le merge est effectué.
Trois jours plus tard, un client signale que la page de tarification est illisible sur mobile. La marge modifiée a propagé un effet en cascade sur un layout flexbox utilisé par six autres pages. Personne ne l'a vu parce que personne n'a regardé — ni l'humain, ni le pipeline.
Le test visuel automatisé est la solution systémique à ce problème. Pas une code review plus attentive. Pas un QA manuel plus rigoureux. Un test automatisé, dans le pipeline, qui compare les images avant/après et signale toute différence.
Configurer le Test Visuel dans .gitlab-ci.yml
La configuration d'un pipeline de test visuel dans GitLab CI suit une logique en étapes bien définie. Voici la structure conceptuelle de votre fichier .gitlab-ci.yml.
La structure du pipeline
Votre pipeline doit inclure les stages suivants, dans cet ordre.
Le stage de build. Il compile votre application et la rend prête à être servie. C'est probablement déjà dans votre pipeline.
Le stage de test visuel. C'est le nouveau stage. Il lance un serveur local, capture les screenshots, les compare aux références, et produit un rapport. Ce stage doit s'exécuter après le build, et ses résultats doivent être stockés comme artifacts.
Le stage de deploy. Il ne s'exécute que si tous les tests — y compris le test visuel — ont réussi.
Les dépendances du job de test visuel
Le job de test visuel nécessite un navigateur headless pour capturer les screenshots. Dans GitLab CI, vous avez deux options. Utiliser une image Docker qui inclut déjà Chromium (comme les images Playwright officielles), ou installer Chromium dans le job via les commandes before_script.
L'image Docker est préférable. Elle est reproductible, rapide (pas d'installation à chaque run), et garantit une version fixe du navigateur.
Le stockage des résultats
Le job de test visuel doit produire plusieurs types de fichiers en tant qu'artifacts. Les screenshots capturés pendant ce run. Les diffs visuels qui montrent les différences détectées. Un rapport HTML ou JSON résumant les résultats.
Configurez une politique de rétention adaptée. Les screenshots de la branche principale doivent être conservés plus longtemps (ils servent de référence). Les screenshots des branches feature peuvent être conservés quelques jours seulement.
La condition de blocage
Le job de test visuel doit être configuré comme un job bloquant. Si des différences non approuvées sont détectées, le pipeline doit échouer. Pas d'avertissement. Pas de "continue on failure". Un échec franc qui empêche le merge.
Exploiter les Artifacts pour les Screenshots
Les artifacts GitLab CI sont le pilier de votre stratégie de test visuel. Voici comment les exploiter au maximum.
Structurer les artifacts de manière lisible
Organisez vos screenshots dans une arborescence claire au sein des artifacts. Créez un dossier par page testée, avec à l'intérieur le screenshot de référence, le screenshot actuel, et le diff. Un rapport HTML à la racine permet de naviguer entre les résultats.
Cette structure facilite la consultation par les reviewers. Quand un test échoue, le reviewer ouvre le browser d'artifacts, navigue vers la page concernée, et voit immédiatement la différence.
Utiliser les artifacts comme références
Les artifacts de la branche principale peuvent servir de référence pour les comparaisons des branches feature. GitLab CI permet de télécharger les artifacts d'un job spécifique sur une branche spécifique via l'API.
Concrètement, le job de test visuel de votre branche feature commence par télécharger les screenshots de référence depuis les artifacts du dernier pipeline réussi sur la branche principale. Il capture ensuite les screenshots de la branche feature. Il compare les deux jeux de captures. Il stocke les résultats comme artifacts du pipeline courant.
Gérer la rétention intelligemment
Les artifacts GitLab ont une durée de rétention configurable. Pour le test visuel, une politique en deux niveaux fonctionne bien. Les artifacts de la branche principale sont conservés 30 jours (ou plus). Ils servent de référence stable. Les artifacts des branches feature sont conservés 7 jours, le temps que la merge request soit traitée.
Les Environments comme Contexte de Comparaison
Les environments GitLab ajoutent une dimension supplémentaire à votre test visuel. Ils permettent de rattacher chaque jeu de screenshots à un contexte de déploiement.
Les review apps comme terrain de test
Si vous utilisez les review apps de GitLab (un déploiement temporaire pour chaque branche feature), vous disposez d'une URL unique par branche. Le test visuel peut capturer les screenshots directement sur cette URL, ce qui offre un rendu plus fidèle qu'un serveur local dans le CI.
L'avantage est double. Le rendu est celui d'un environnement réel (pas un serveur de développement). Et l'URL de la review app est accessible à toute l'équipe, ce qui facilite la vérification manuelle en complément du test automatisé.
Comparer entre environments
Les environments permettent de comparer les screenshots entre contextes. Vous pouvez comparer la review app d'une branche feature avec l'environment de staging. Ou comparer le staging avec la production pour détecter les dérives visuelles.
Cette capacité de comparaison inter-environments est un atout majeur de GitLab CI pour le test visuel. Elle permet de détecter non seulement les régressions introduites par une branche, mais aussi les dérives accumulées entre les environnements.
L'Intégration avec les Merge Requests
Le test visuel n'a de valeur que si ses résultats sont visibles et actionnables. Pour comprendre comment fonctionne la comparaison sous-jacente, consultez notre article sur la comparaison DOM versus visuelle. L'intégration avec les merge requests de GitLab est le vecteur idéal.
Les widgets de merge request
GitLab affiche les résultats des pipelines directement sur la merge request. Le statut du job de test visuel apparaît dans la liste des checks. Un clic mène aux logs du job et aux artifacts.
Les commentaires automatiques
Configurez votre pipeline pour poster un commentaire automatique sur la merge request quand des différences visuelles sont détectées. Ce commentaire doit inclure un résumé (nombre de pages affectées, sévérité des changements) et un lien vers le rapport complet dans les artifacts.
L'approbation des changements attendus
Quand un changement visuel est intentionnel (un redesign, un changement de couleur), il faut un mécanisme pour approuver le changement et mettre à jour les références. Dans GitLab, cela peut se faire via un job manuel déclenché par un bouton dans le pipeline. Le développeur ou le QA consulte les diffs, confirme qu'ils sont attendus, et déclenche la mise à jour des références.
Approche No-Code : Simplifier Radicalement la Configuration
Tout ce qui précède fonctionne, mais demande un investissement significatif en configuration et en maintenance. L'approche no-code réduit drastiquement cette complexité.
Avec un outil comme Delta-QA, l'intégration dans GitLab CI se résume à ajouter un job qui appelle l'outil avec les paramètres de votre projet. L'outil gère le navigateur headless, la capture, la comparaison, la gestion des références, et le reporting.
Vous n'avez pas à gérer les images Docker avec Chromium. Vous n'avez pas à écrire de scripts de capture. Vous n'avez pas à implémenter un système de comparaison. Vous n'avez pas à construire un rapport HTML.
L'avantage principal n'est pas la simplicité initiale — c'est la maintenance à long terme. Un pipeline de test visuel artisanal nécessite une maintenance constante : mise à jour des navigateurs, ajustement des seuils, correction des scripts de capture quand l'UI change. Un outil no-code absorbe cette complexité.
Votre fichier .gitlab-ci.yml reste propre. Votre pipeline reste rapide. Et votre équipe peut se concentrer sur ce qui compte : analyser les résultats et décider si les changements sont attendus ou pas.
Pièges Fréquents et Solutions
Le piège des images Docker volumineuses
Les images Docker contenant un navigateur headless sont lourdes (souvent plus d'un gigaoctet). Si vous les téléchargez à chaque run, vous ajoutez plusieurs minutes à votre pipeline. Utilisez un registry Docker privé avec mise en cache, ou les images pré-installées sur vos runners partagés.
Le piège de la résolution d'écran
Les runners GitLab CI n'ont pas d'écran physique. Le navigateur headless utilise un framebuffer virtuel. La résolution de ce framebuffer doit correspondre à vos viewports de test. Si vous capturez en 1920x1080 mais que le framebuffer est configuré en 1024x768, vous obtiendrez des screenshots tronqués ou redimensionnés.
Le piège du contenu asynchrone
Les applications modernes chargent du contenu de manière asynchrone. Une API qui met 200 millisecondes à répondre en développement peut en mettre 2000 dans le CI (réseau différent, ressources partagées). Attendez que tous les appels réseau soient terminés et que le contenu soit rendu avant de capturer.
Le piège de la gestion des références sur les branches longues
Si une branche feature dure plusieurs semaines, les références de la branche principale ont pu évoluer entre-temps. Quand vous comparez, vous détectez des différences qui viennent de l'évolution de main, pas de votre branche. La solution est de rebaser régulièrement votre branche sur main, ou de télécharger les références les plus récentes à chaque run.
Foire Aux Questions
Quelle image Docker utiliser pour le test visuel dans GitLab CI ?
Les images officielles Playwright (mcr.microsoft.com/playwright) sont un excellent choix. Elles incluent Chromium, Firefox et WebKit, avec toutes les dépendances système nécessaires. Si vous n'utilisez que Chromium, des images plus légères basées sur Alpine avec Puppeteer sont disponibles. Pour un outil no-code comme Delta-QA, l'image Docker est fournie et optimisée pour cet usage.
Combien de temps les artifacts de screenshots doivent-ils être conservés ?
Pour la branche principale, conservez les artifacts au minimum 30 jours. Ils servent de référence pour toutes les comparaisons. Pour les branches feature, 7 jours suffisent généralement — le temps que la merge request soit traitée et mergée. Ajustez en fonction de votre rythme de développement. Une équipe avec des cycles longs aura besoin d'une rétention plus étendue.
Le test visuel fonctionne-t-il avec les runners partagés de GitLab.com ?
Oui, les runners partagés de GitLab.com (SaaS) supportent le test visuel. Ils utilisent des machines virtuelles avec Docker, capables d'exécuter un navigateur headless. Cependant, la performance peut varier selon la charge des runners partagés. Si la stabilité et la vitesse sont critiques, des runners dédiés ou auto-hébergés offrent un meilleur contrôle.
Comment gérer les différences de rendu entre GitLab CI et mon poste de développement ?
Les différences de rendu entre votre machine locale et les runners CI sont inévitables. Les polices installées, la version du navigateur, et la résolution du framebuffer diffèrent. La règle est simple : ne comparez jamais un screenshot local à un screenshot CI. Les références doivent toujours être générées dans le même environnement que les captures de test. Si vos références sont dans le CI, vos comparaisons se font dans le CI.
Peut-on paralléliser les captures de screenshots dans GitLab CI ?
Absolument, et c'est recommandé pour les projets avec beaucoup de pages à tester. GitLab CI supporte la parallélisation via le mot-clé parallel dans votre configuration. Vous pouvez répartir les pages entre plusieurs jobs qui s'exécutent simultanément. Chaque job capture un sous-ensemble de pages et stocke ses screenshots en artifacts. Un job final agrège les résultats. Cette approche divise le temps de capture par le nombre de jobs parallèles.
Est-ce que le test visuel dans GitLab CI fonctionne avec les monorepos ?
Oui, mais cela demande une configuration spécifique. Dans un monorepo, vous avez probablement plusieurs applications frontend. Utilisez les rules de GitLab CI pour déclencher le test visuel uniquement quand les fichiers de l'application concernée sont modifiés. Chaque application peut avoir son propre jeu de références et son propre job de test visuel. Les artifacts doivent être organisés par application pour éviter les conflits.
Conclusion
GitLab CI/CD possède des fonctionnalités natives — artifacts, environments, review apps, browser d'artifacts — qui en font une plateforme remarquablement adaptée au test visuel. Ce n'est pas un hasard de calendrier. C'est une convergence architecturale : le test visuel a besoin de stocker des fichiers, de comparer des contextes, et de rendre les résultats accessibles. GitLab fait tout cela nativement.
Si vous utilisez GitLab et que votre pipeline ne vérifie pas l'apparence de votre application, vous sous-utilisez votre outil. Vous avez l'infrastructure. Il ne vous manque que l'étape.
L'ajout du test visuel à votre pipeline GitLab CI n'est pas un projet de transformation digitale. C'est une étape dans un fichier .gitlab-ci.yml, un jeu de références initiales, et un processus d'approbation des changements. Avec un outil no-code comme Delta-QA, c'est encore plus simple : une intégration en quelques minutes, et chaque merge request est automatiquement protégée contre les régressions visuelles.
Vos utilisateurs voient votre application. Votre pipeline devrait la voir aussi.
Essayer Delta-QA Gratuitement →