Test Visuel et Docker : Sans Environnement Reproductible, Vos Screenshots Ne Valent Rien
Environnement reproductible : configuration logicielle identique à chaque exécution — même système d'exploitation, mêmes bibliothèques, mêmes polices, même moteur de rendu — garantissant que les résultats d'un test ne varient pas en fonction de la machine sur laquelle il s'exécute. — Principe fondamental de l'ingénierie de test automatisé.
Vous avez mis en place du test visuel. Vous comparez des screenshots. Vos tests passent en local. Et quand ils tournent sur la CI, vous obtenez 47 différences signalées — dont aucune ne correspond à un vrai bug.
Ce scénario, la grande majorité des équipes qui font du test visuel l'ont vécu. Et la grande majorité de ces équipes en tirent la mauvaise conclusion : « Le test visuel, c'est trop de bruit, ça ne marche pas. »
Le test visuel fonctionne très bien. Ce qui ne fonctionne pas, c'est votre environnement.
Un screenshot pris sur macOS avec les polices Apple ne sera jamais identique au pixel près à un screenshot pris sur Ubuntu avec les polices FreeType. Un navigateur qui tourne en 1920x1080 avec un scaling de 100 % ne produit pas le même rendu qu'un navigateur en 1920x1080 avec un scaling de 125 %. L'anti-aliasing, le hinting des polices, le lissage des sous-pixels — tout diffère.
Docker résout ce problème. Et si vous faites du test visuel sans Docker, vous perdez votre temps.
Pourquoi les screenshots diffèrent d'une machine à l'autre
Pour comprendre pourquoi Docker est indispensable, il faut comprendre ce qui fait qu'un screenshot diffère entre deux machines — même quand le code est strictement identique.
Le rendu des polices : le coupable numéro un
Le rendu des polices est de loin la première source de différences entre screenshots. Chaque système d'exploitation utilise son propre moteur de rendu typographique. macOS utilise Core Text, qui privilégie la fidélité au design de la police. Windows utilise DirectWrite, qui privilégie l'alignement sur la grille de pixels. Linux utilise FreeType, dont le comportement varie selon la configuration de fontconfig.
Le résultat : le même texte, avec la même police, à la même taille, sur la même page, ne produit pas les mêmes pixels selon le système d'exploitation. Les différences sont parfois invisibles à l'œil nu — un pixel de décalage, un lissage légèrement différent. Mais un outil de comparaison pixel-à-pixel les détecte et les signale comme des régressions.
Et ce n'est pas tout. Les polices disponibles varient d'un système à l'autre. Si votre CSS spécifie une police qui n'est pas installée sur la machine de CI, le navigateur utilise une police de substitution. Cette substitution peut modifier l'espacement, la hauteur de ligne, la largeur des caractères — et donc la mise en page entière.
Le moteur de rendu du navigateur
Même en utilisant le même navigateur (Chrome, par exemple), la version exacte du moteur de rendu influence le résultat. Chrome 120 ne produit pas exactement le même rendu que Chrome 122 pour certaines propriétés CSS. Les différences sont marginales, mais dans le contexte d'une comparaison pixel-à-pixel, elles suffisent à générer des faux positifs.
Sur votre poste de développement, vous avez Chrome 124. Sur la CI, le runner utilise Chrome 118. Les screenshots ne correspondent pas. Ce n'est pas un bug dans votre application — c'est une incohérence d'environnement.
La résolution et le scaling
Le DPI (dots per inch) de votre écran influence le rendu. Un écran Retina (2x) produit des screenshots à une résolution différente d'un écran standard (1x). Le viewport peut être le même — 1280x720 — mais les pixels physiques sont différents, et le rendu des éléments CSS (bordures, ombres, arrondis) varie en conséquence.
Les serveurs de CI n'ont généralement pas d'écran physique. Ils utilisent un framebuffer virtuel (Xvfb sous Linux) dont la configuration de DPI peut différer de celle de votre poste de développement. Si cette configuration n'est pas explicitement contrôlée, vous obtenez des différences subtiles mais persistantes.
Docker : l'environnement identique, à chaque fois
Docker résout ces problèmes en encapsulant l'intégralité de l'environnement de test dans un conteneur. Le même système d'exploitation, les mêmes polices, le même navigateur, la même version, la même configuration de rendu — que le conteneur tourne sur votre poste macOS, sur un runner GitHub Actions Linux, ou sur une instance EC2.
Ce que le conteneur doit contenir
Un conteneur Docker pour le test visuel doit inclure plusieurs composants que les images Docker standard ne fournissent pas.
Premièrement, les polices. Toutes les polices que votre application utilise doivent être installées dans le conteneur. Pas seulement les polices Google Fonts que votre CSS importe via un lien — ces polices sont téléchargées à la volée et peuvent varier en version. Installez-les localement dans le conteneur pour garantir que la même version est utilisée à chaque exécution.
Deuxièmement, un navigateur en version fixe. N'utilisez pas « la dernière version de Chrome ». Fixez une version précise. Quand vous décidez de mettre à jour, vous mettez à jour votre image Docker, vous regénérez vos baselines, et vous repartez d'un état propre. C'est une décision explicite, pas un effet de bord.
Troisièmement, la configuration de rendu. La configuration fontconfig de Linux, le DPI du framebuffer virtuel, les paramètres d'anti-aliasing — tout doit être explicitement défini dans le Dockerfile. Ne laissez rien aux valeurs par défaut, parce que les valeurs par défaut changent entre les distributions Linux et entre les versions de ces distributions.
Quatrièmement, les dépendances système. Les bibliothèques partagées nécessaires au fonctionnement du navigateur en mode headless (libgbm, libnss3, libatk, etc.) doivent être présentes et en versions compatibles. Une bibliothèque manquante ou en mauvaise version peut modifier le rendu de manière imperceptible mais détectable par comparaison.
L'image de base : ne réinventez pas la roue
Plusieurs images Docker maintenues par la communauté sont spécialement conçues pour l'exécution de navigateurs headless. Les images officielles de Playwright incluent les navigateurs et leurs dépendances en versions verrouillées. Les images de BrowserStack et d'autres fournisseurs offrent des configurations pré-testées.
L'erreur courante est de partir d'une image Ubuntu minimale et d'installer Chrome manuellement. Vous vous retrouvez à résoudre des problèmes de dépendances, de sandbox, de permissions — des problèmes déjà résolus par les images spécialisées.
Partez d'une image qui fonctionne. Ajoutez vos polices et votre configuration spécifique. Ne construisez pas depuis zéro sauf si vous avez une raison impérieuse de le faire.
Le Dockerfile comme documentation vivante
L'un des bénéfices sous-estimés de Docker pour le test visuel est la documentation. Votre Dockerfile est une description exhaustive et exécutable de votre environnement de test. Quand un nouveau membre rejoint l'équipe, il n'a pas besoin de deviner quelles polices installer, quelle version de Chrome utiliser, ou comment configurer fontconfig. Il lance le conteneur et obtient le même environnement que tout le monde.
C'est aussi une assurance contre les régressions d'environnement. Si un screenshot change, vous savez que le changement vient de l'application ou du contenu — pas de l'environnement. Parce que l'environnement est versionné, tagué, et immuable.
Dockeriser votre setup de test visuel : les étapes clés
La mise en place d'un environnement Docker pour le test visuel suit une progression logique. Chaque étape renforce la fiabilité et la reproductibilité de vos tests.
Étape 1 : Fixer les versions
Avant de toucher à Docker, listez tout ce qui participe au rendu de vos pages. Le navigateur et sa version exacte. Les polices utilisées par votre application. Les dépendances système du navigateur. La résolution et le DPI cibles.
Cette liste est votre spécification d'environnement. Chaque élément doit être fixé à une version précise. Pas de « latest », pas de range sémantique, pas de « peu importe ». En test visuel, « peu importe » est synonyme de « faux positifs ».
Étape 2 : Construire l'image
Votre Dockerfile part d'une image de base qui inclut déjà le navigateur en version fixe. Vous y ajoutez vos polices, votre configuration fontconfig, et les outils nécessaires à l'exécution de vos tests.
Le point clé est l'ordre des instructions dans le Dockerfile. Les couches qui changent le moins souvent (le système d'exploitation, le navigateur, les polices) doivent être en haut. Les couches qui changent fréquemment (votre code applicatif, vos fichiers de test) doivent être en bas. Cela optimise le cache de build et accélère vos pipelines.
Étape 3 : Valider la reproductibilité
Construisez l'image. Lancez vos tests visuels depuis le conteneur. Construisez l'image à nouveau. Relancez les tests. Les résultats doivent être identiques. Si ce n'est pas le cas, quelque chose dans votre image n'est pas déterministe — probablement une dépendance installée via un gestionnaire de paquets qui a récupéré une version plus récente.
Vérifiez en construisant l'image sur deux machines différentes (votre poste et la CI, par exemple) et en comparant les résultats. C'est le test ultime de reproductibilité.
Étape 4 : Intégrer dans le pipeline CI/CD
Une fois l'image validée, intégrez-la dans votre pipeline CI/CD. Vos tests visuels s'exécutent dans le conteneur Docker sur la CI, et les baselines sont générées dans le même conteneur. Plus jamais de « ça passe chez moi mais pas sur la CI ».
Poussez votre image Docker dans un registre (Docker Hub, GitHub Container Registry, GitLab Container Registry) et référencez-la dans votre configuration CI. Quand vous mettez à jour l'image, mettez à jour le tag et régénérez vos baselines. C'est un processus contrôlé et traçable.
Étape 5 : Gérer les mises à jour
Les navigateurs publient des mises à jour de sécurité régulièrement. Vous ne pouvez pas rester indéfiniment sur la même version. Établissez un rythme de mise à jour — mensuel, par exemple — et traitez chaque mise à jour comme un événement planifié.
La procédure est simple : mettez à jour la version du navigateur dans le Dockerfile, reconstruisez l'image, relancez les tests visuels, examinez les différences, mettez à jour les baselines pour les différences attendues (changements de rendu liés à la nouvelle version du navigateur), et investiguez les différences inattendues.
Les bénéfices au-delà de la reproductibilité
Docker apporte d'autres avantages au test visuel qui méritent d'être mentionnés.
La parallélisation
Un conteneur Docker démarre en quelques secondes. Vous pouvez lancer 10, 20, 50 conteneurs en parallèle pour tester autant de pages simultanément. Vos tests visuels qui prenaient 30 minutes en séquentiel prennent 3 minutes en parallèle. Et chaque conteneur est isolé, donc les tests ne s'interfèrent pas.
L'isolation des tests
Chaque conteneur part d'un état propre. Pas de cache navigateur persistant, pas de cookies résiduels, pas de profil utilisateur qui accumule des données entre les exécutions. Chaque test démarre dans un environnement vierge, ce qui élimine une catégorie entière de faux positifs liés à l'état du navigateur.
Où Delta-QA s'inscrit dans cette approche
Delta-QA simplifie considérablement l'équation Docker pour le test visuel.
L'analyse structurelle de Delta-QA est intrinsèquement moins sensible aux variations de rendu entre environnements. Là où un outil de comparaison pixel-à-pixel signale chaque différence de sous-pixel due au rendu des polices, Delta-QA analyse les propriétés CSS calculées — marges, paddings, dimensions, positionnement — qui sont les mêmes quel que soit l'environnement de rendu.
Cela ne signifie pas que Docker est inutile avec Delta-QA. Un environnement reproductible reste une bonne pratique. Mais cela signifie que la tolérance aux variations d'environnement est incomparablement plus élevée. Un anti-aliasing différent ne génère pas de faux positif dans Delta-QA, parce que Delta-QA ne regarde pas les pixels — il regarde la structure.
Pour les équipes qui ne peuvent pas (ou ne veulent pas) investir dans la construction et la maintenance d'une image Docker dédiée au test visuel, c'est un avantage décisif. Delta-QA vous donne des résultats fiables même dans des environnements imparfaits. Et si vous ajoutez Docker par-dessus, vous obtenez le meilleur des deux mondes : la précision structurelle de Delta-QA dans un environnement parfaitement reproductible.
Les erreurs fréquentes à éviter avec Docker et le test visuel
Utiliser « latest » comme tag d'image
C'est la première cause de tests instables dans un contexte Docker. Le tag « latest » pointe vers une image différente chaque semaine. Si votre Dockerfile commence par une image en « latest », votre environnement n'est pas reproductible. Fixez une version précise et mettez-la à jour de manière contrôlée.
Oublier les polices
Votre application utilise Inter, Roboto et une police personnalisée. Votre image Docker n'inclut aucune de ces polices. Le navigateur les télécharge via Google Fonts — quand le réseau le permet. Sur un runner de CI sans accès Internet, ou avec un réseau lent, les polices ne se chargent pas et le navigateur utilise les polices système par défaut. Vos screenshots sont inutilisables.
Ignorer la taille du viewport
Le fait que votre Dockerfile définisse un écran virtuel de 1920x1080 ne signifie pas que le navigateur utilise un viewport de 1920x1080. Les barres de défilement, les barres d'adresse, les bordures de fenêtre — autant d'éléments qui réduisent le viewport effectif. Configurez le viewport explicitement dans votre outil de test visuel, pas dans la résolution de l'écran virtuel.
Ne pas versionner l'image
Votre Dockerfile est dans le dépôt Git. Bien. Mais l'image construite à partir de ce Dockerfile à un instant T n'est pas reconstituable si les paquets installés ont été mis à jour entre-temps. Poussez vos images dans un registre, taggez-les avec un hash ou une date, et référencez le tag exact dans votre pipeline CI.
FAQ
Docker est-il obligatoire pour faire du test visuel ?
Non, mais sans Docker (ou un mécanisme d'environnement reproductible équivalent), vous passerez un temps considérable à gérer des faux positifs liés aux différences de rendu entre machines. Docker n'est pas obligatoire — il est pratiquement indispensable si vous voulez des résultats fiables en comparaison pixel-à-pixel.
Quelle image Docker de base recommandez-vous pour le test visuel ?
Les images officielles de Playwright (mcr.microsoft.com/playwright) sont un excellent point de départ. Elles incluent les navigateurs en versions fixées, les dépendances système, et sont maintenues par l'équipe Microsoft. Ajoutez-y vos polices et votre configuration spécifique.
Docker ralentit-il les tests visuels ?
Le démarrage d'un conteneur Docker ajoute quelques secondes au temps total d'exécution. En contrepartie, Docker permet la parallélisation massive : vous pouvez lancer des dizaines de conteneurs simultanément, ce qui réduit le temps total de votre suite de tests. Le bilan est presque toujours positif.
Comment gérer les polices Google Fonts dans un conteneur Docker ?
Téléchargez les fichiers de polices et installez-les localement dans le conteneur via votre Dockerfile. Ne comptez pas sur le téléchargement à la volée depuis les serveurs Google — le réseau peut être lent, indisponible, ou renvoyer une version différente de la police. L'installation locale garantit la cohérence.
Peut-on utiliser Docker Desktop pour le test visuel en local ?
Oui, et c'est même recommandé pendant la phase de développement. Docker Desktop vous permet de lancer le même conteneur que la CI sur votre poste de développement. Si vos tests passent dans le conteneur en local, ils passeront sur la CI. C'est le principe fondamental de la reproductibilité.
Delta-QA nécessite-t-il Docker pour fonctionner ?
Non. Delta-QA fonctionne sans Docker grâce à son approche d'analyse structurelle, qui est intrinsèquement moins sensible aux variations de rendu entre environnements. Docker reste une bonne pratique pour maximiser la reproductibilité, mais il n'est pas un prérequis pour obtenir des résultats fiables avec Delta-QA.
Un screenshot qui change d'une machine à l'autre n'est pas un test. C'est du bruit. Docker transforme vos captures en preuves fiables et reproductibles.