Visual Testing dans GitLab CI : Intégrer le Test Visuel à vos Pipelines
Le test visuel (visual testing) est une méthode de vérification automatisée qui compare des captures d'écran d'une interface web entre deux versions pour détecter les régressions graphiques — un élément déplacé, une couleur modifiée, un composant qui déborde de son conteneur.
Nous utilisons GitLab au quotidien chez Delta-QA. Nos repos, nos pipelines, nos merge requests, notre CI/CD — tout tourne sur GitLab. Ce n'est pas un choix par défaut : c'est un choix délibéré pour une plateforme qui offre un pipeline intégré nativement, un registre de conteneurs, et une philosophie DevOps cohérente de bout en bout.
Quand nous parlons de test visuel dans GitLab CI, nous ne recrachons pas une documentation que nous aurions lue la veille. Nous partageons ce que nous avons appris en l'utilisant réellement. Cet article couvre les approches disponibles, les spécificités de GitLab CI qui affectent le test visuel, et comment obtenir un pipeline de régression visuelle fiable.
Pourquoi GitLab CI Se Prête Bien au Test Visuel
GitLab CI a des caractéristiques qui le rendent particulièrement adapté au test visuel — des caractéristiques que les utilisateurs de GitHub Actions ou Jenkins n'ont pas par défaut.
Les artefacts natifs
GitLab CI gère nativement les artefacts de pipeline. Quand un test visuel produit des rapports HTML, des images de diff, ou des captures d'écran, vous les déclarez comme artefacts et ils sont accessibles directement depuis l'interface de la merge request. Pas besoin d'un service externe pour stocker et consulter les résultats.
C'est un avantage sous-estimé. Avec GitHub Actions, vous devez configurer un upload d'artefact séparé ou utiliser un service tiers pour rendre les résultats accessibles. Avec GitLab, c'est natif.
Les environnements de review
GitLab propose les Review Apps : des environnements éphémères déployés automatiquement pour chaque merge request. Votre application tourne dans un environnement dédié, accessible via une URL temporaire. C'est l'environnement idéal pour le test visuel : stable, isolé, et représentatif de la production.
Les runners auto-gérés
GitLab permet d'utiliser des runners hébergés sur votre propre infrastructure. Pour le test visuel, c'est crucial : vous contrôlez l'environnement de rendu (OS, polices, GPU), ce qui réduit les faux positifs liés aux différences d'environnement. Nous utilisons des runners dédiés avec une configuration figée pour garantir la reproductibilité des captures.
Le registre de conteneurs intégré
Chaque projet GitLab a un registre de conteneurs. Vous pouvez y stocker une image Docker préconfigurée pour le test visuel — avec les bonnes polices, le bon navigateur, les bonnes dépendances — et l'utiliser comme base de vos jobs de test. Cela élimine une source majeure d'instabilité.
Les Approches pour le Test Visuel dans GitLab CI
Playwright dans un Job GitLab CI
Playwright est l'outil open source le plus robuste pour le test visuel en CI. Sa méthode native toHaveScreenshot() gère la capture, la comparaison, et les retries automatiques.
L'intégration avec GitLab CI. Vous créez un job dans votre .gitlab-ci.yml qui utilise l'image Docker officielle de Playwright, exécute vos tests, et publie les résultats comme artefacts. Les rapports HTML de Playwright sont consultables directement dans GitLab.
Pour la structure exacte du fichier YAML, demandez à votre copilote IA — il est incollable sur la syntaxe GitLab CI, c'est à peu près la seule chose sur laquelle il ne hallucine pas (encore). Plus sérieusement, la documentation officielle de Playwright pour les environnements CI est votre meilleure référence.
Ce qui fonctionne bien. L'image Docker officielle de Playwright inclut tous les navigateurs et les dépendances système nécessaires. Combinée au registre de conteneurs GitLab, vous pouvez créer une image dérivée avec vos polices et vos configurations spécifiques. Les artefacts GitLab rendent les rapports de test accessibles sans configuration supplémentaire.
Les limites dans le contexte GitLab. Les baselines doivent être générées dans l'environnement CI, pas en local. C'est une règle universelle du test visuel, mais GitLab facilite les choses : vous pouvez déclencher un pipeline manuellement pour régénérer les baselines. La gestion des baselines dans Git reste un défi (fichiers binaires, conflits de merge), mais GitLab LFS est intégré nativement.
Percy avec GitLab CI
Percy (BrowserStack) propose une intégration officielle avec GitLab CI. Le SDK Percy capture les snapshots pendant votre pipeline et les envoie au cloud Percy pour comparaison et review.
Ce qui fonctionne. Percy détecte automatiquement la branche et la merge request GitLab. Les résultats apparaissent comme un statut externe sur votre MR. Le cross-browser est géré côté cloud.
Les limites. La tarification au snapshot reste un sujet. Et vous ajoutez une dépendance externe à votre pipeline — si Percy est indisponible, votre check reste en attente. Pour une équipe qui a choisi GitLab justement pour maîtriser son infrastructure, cette dépendance externe peut être contradictoire avec la philosophie.
BackstopJS dans GitLab CI
BackstopJS fonctionne dans GitLab CI via son image Docker officielle. Les rapports HTML sont parfaitement adaptés au système d'artefacts GitLab.
Ce qui fonctionne. Le rapport HTML de BackstopJS est l'un des plus visuels et lisibles de l'écosystème. Publié comme artefact GitLab, il est consultable directement dans le navigateur depuis l'interface de la MR. La configuration par scénarios JSON est explicite et versionnable.
Les limites. Le projet a traversé des périodes de maintenance intermittente — vérifiez l'activité récente avant de vous engager. La configuration peut devenir verbeuse pour des applications complexes, et vous devez gérer manuellement l'itération sur vos pages ou composants.
Delta-QA : Intégration Native avec GitLab CI
Nous avons construit Delta-QA en utilisant GitLab CI au quotidien. L'intégration n'est pas un afterthought — c'est un cas d'usage de première classe.
Comment ça fonctionne. Delta-QA s'intègre dans votre pipeline GitLab CI comme un job dédié. Il capture vos pages, compare avec les références, et reporte les résultats. Les différences détectées sont visibles dans une interface de review dédiée, avec un lien direct depuis votre merge request.
Ce qui est différent. Pas de scripts de test à écrire ni à maintenir. Pas de baselines à stocker dans votre repo. Pas de faux positifs liés aux différences d'environnement entre votre machine et le runner CI. L'outil gère la stabilité du rendu en interne.
L'avantage GitLab. Delta-QA exploite les spécificités de GitLab CI : les Review Apps comme cible de capture, les artefacts pour les rapports détaillés, et les webhooks GitLab pour déclencher les tests au bon moment du pipeline.
Les Spécificités GitLab CI à Connaître pour le Test Visuel
Le cache vs les artefacts
C'est une distinction que beaucoup confondent. Le cache GitLab CI est partagé entre les pipelines d'un même projet — il sert à accélérer les jobs (dépendances npm, navigateurs Playwright). Les artefacts sont les outputs d'un job spécifique — les rapports de test, les screenshots, les diffs.
Pour le test visuel, utilisez le cache pour les navigateurs et les dépendances, et les artefacts pour les résultats de test. Ne cachez jamais les baselines — elles doivent vivre dans le repo pour être versionnées avec le code.
Les stages et les dépendances entre jobs
GitLab CI organise les jobs en stages séquentiels. Le test visuel doit être dans un stage qui s'exécute après le déploiement de votre Review App. Un pattern courant :
- build — compilation de l'application
- deploy-review — déploiement de la Review App
- test-visual — test visuel sur la Review App
- cleanup — suppression de l'environnement
La directive needs de GitLab CI permet de créer des dépendances explicites entre jobs sans passer par les stages séquentiels, ce qui peut accélérer votre pipeline.
Les variables d'environnement protégées
Les tokens d'API pour les services cloud (Percy, Chromatic) doivent être stockés comme variables CI/CD dans GitLab. Attention : les variables protégées ne sont disponibles que sur les branches protégées. Si vos feature branches ne sont pas protégées, le test visuel avec un service cloud échouera silencieusement — un piège classique.
Les limites de temps et de mémoire
Le test visuel est gourmand en ressources. Le rendu de pages dans un navigateur headless consomme de la mémoire, et la comparaison d'images prend du temps. Les runners partagés de GitLab.com ont des limites de temps (généralement une heure par job) et de mémoire. Pour des suites de test visuel conséquentes, les runners auto-gérés avec des ressources dédiées sont recommandés.
Construire un Pipeline de Test Visuel Robuste
Voici l'approche que nous recommandons, basée sur notre propre expérience.
Commencez petit et ciblé
Ne testez pas visuellement toutes vos pages dès le premier jour. Identifiez les cinq à dix pages les plus critiques — celles que vos utilisateurs voient en premier, celles où une régression visuelle a le plus d'impact business. Élargissez ensuite progressivement.
Utilisez des Review Apps comme cible
Plutôt que de lancer un serveur local dans votre job CI, déployez une Review App et testez-la. L'avantage : l'environnement est stable, accessible, et représentatif. L'inconvénient : vous ajoutez la durée du déploiement au pipeline. Le compromis en vaut la peine.
Stabilisez votre environnement de rendu
Créez une image Docker dédiée au test visuel, stockée dans votre registre GitLab. Incluez les polices utilisées par votre application, la version exacte du navigateur, et toutes les dépendances système. Versionnez cette image. Quand votre environnement de rendu est figé, les faux positifs chutent drastiquement.
Commencez en mode non-bloquant
Configurez votre job de test visuel avec allow_failure: true pendant les premières semaines. Cela permet à votre équipe de se familiariser avec les résultats sans que le test visuel bloque les merge requests. Une fois la confiance établie et les faux positifs maîtrisés, passez en mode bloquant.
Notifiez intelligemment
GitLab CI peut envoyer des notifications sur différents canaux (Slack, email, webhook). Configurez les notifications de test visuel pour qu'elles n'alertent que sur les échecs — pas sur les succès. L'objectif est d'attirer l'attention quand c'est nécessaire, pas de noyer votre équipe sous les messages.
FAQ
GitLab CI est-il aussi bien que GitHub Actions pour le test visuel ?
Pour le test visuel spécifiquement, GitLab CI a des avantages natifs : les artefacts intégrés, les Review Apps, le registre de conteneurs, et les runners auto-gérés. Ces fonctionnalités facilitent la mise en place d'un environnement de test visuel stable et reproductible. GitHub Actions a sa propre marketplace riche, mais certaines de ces fonctionnalités nécessitent des configurations supplémentaires.
Faut-il des runners auto-gérés pour le test visuel dans GitLab CI ?
Ce n'est pas obligatoire, mais c'est fortement recommandé. Les runners partagés de GitLab.com fonctionnent, mais leur configuration matérielle variable peut introduire des différences de rendu. Un runner auto-géré avec une configuration figée (polices, navigateur, résolution) élimine cette source de faux positifs et offre généralement de meilleures performances.
Comment gérer les baselines de test visuel dans un repo GitLab ?
Si vous utilisez Playwright ou BackstopJS, les baselines (fichiers PNG) vivent dans votre repo. Activez GitLab LFS pour éviter que les fichiers binaires gonflent votre historique Git. Pour les conflits de merge sur les baselines, la stratégie la plus simple est d'accepter les nouvelles baselines de la branche source et de régénérer si nécessaire. Avec Delta-QA, les baselines sont gérées par l'outil et ne polluent pas votre repo.
Peut-on utiliser les Review Apps de GitLab comme environnement de test visuel ?
Oui, et c'est même l'approche que nous recommandons. La Review App fournit un environnement stable et isolé pour chaque merge request. Votre job de test visuel attend que la Review App soit déployée, capture les screenshots sur l'URL temporaire, et compare avec les références. C'est plus fiable qu'un serveur lancé à la volée dans le job CI.
Le test visuel dans GitLab CI fonctionne-t-il avec les monorepos ?
Oui. GitLab CI supporte les règles conditionnelles qui permettent de ne déclencher le test visuel que si les fichiers front-end ont été modifiés. Combiné avec la directive only:changes, vous évitez d'exécuter des tests visuels inutiles quand seul le backend a changé. C'est essentiel pour maintenir un pipeline rapide dans un monorepo.
Quelle est la meilleure image Docker pour le test visuel dans GitLab CI ?
L'image officielle de Playwright (mcr.microsoft.com/playwright) est un excellent point de départ. Elle inclut les navigateurs et les dépendances système. Pour un environnement encore plus stable, créez une image dérivée qui ajoute vos polices d'application et fixe les versions exactes. Stockez-la dans le registre de conteneurs de votre projet GitLab pour un accès rapide.
Conclusion
GitLab CI est une plateforme naturellement adaptée au test visuel. Ses fonctionnalités natives — artefacts, Review Apps, registre de conteneurs, runners auto-gérés — résolvent des problèmes que d'autres plateformes de CI demandent de traiter manuellement.
Mais la plateforme ne fait pas tout. Le test visuel en CI reste un défi d'ingénierie : stabiliser le rendu, gérer les baselines, traiter les faux positifs, et construire un workflow de review qui fonctionne pour toute l'équipe.
Si vous êtes sur GitLab et que vous voulez ajouter le test visuel à votre pipeline sans la complexité des scripts de test et de la gestion manuelle des baselines, Delta-QA est conçu pour s'intégrer nativement dans votre workflow GitLab CI.