Points clés
- Le Shadow DOM encapsule les styles et le DOM, rendant les approches classiques de test visuel partiellement aveugles
- Les outils qui inspectent le DOM « normal » ne voient pas les éléments à l'intérieur du Shadow DOM sans adaptation spécifique
- L'approche structurelle, basée sur les propriétés CSS calculées, fonctionne à travers le Shadow DOM parce qu'elle lit le résultat final du navigateur
- Les slots, les CSS custom properties et l'héritage de styles créent des interactions complexes que seule une analyse du rendu réel peut vérifier
Les Web Components sont définis par le MDN comme « un ensemble de technologies qui permettent de créer des éléments HTML personnalisés réutilisables, dont la fonctionnalité est encapsulée et isolée du reste du code » (MDN Web Docs, Web Components).
Cette définition cache une révolution silencieuse. Les Web Components ne sont plus une curiosité expérimentale. En 2026, tous les navigateurs majeurs les supportent nativement. Des frameworks comme Lit, Stencil et FAST les utilisent comme fondation. Des entreprises comme Adobe (Spectrum Web Components), SAP (UI5 Web Components), et ING Bank (Lion Web Components) construisent leurs design systems entiers sur cette technologie.
Et pourtant, le test visuel des Web Components reste un angle mort pour la plupart des équipes. La raison tient en deux mots : Shadow DOM.
Qu'est-ce que le Shadow DOM change pour le test visuel
Pour comprendre le problème, il faut comprendre ce que le Shadow DOM fait réellement. En temps normal, tout le DOM de votre page est un arbre unique. Les sélecteurs CSS s'appliquent à tous les éléments. Les outils de test peuvent parcourir l'intégralité de la structure.
Le Shadow DOM casse cette hypothèse. Il crée un sous-arbre DOM isolé, attaché à un élément hôte, avec ses propres styles. Les sélecteurs CSS externes ne peuvent pas atteindre les éléments internes. Les scripts qui parcourent le DOM avec querySelector ne voient pas ce qui se trouve dans l'ombre.
C'est exactement l'objectif du Shadow DOM : l'encapsulation. Vos styles ne fuient pas vers l'extérieur, les styles extérieurs ne contaminent pas l'intérieur. C'est une fonctionnalité, pas un bug.
Mais pour le test visuel, cette encapsulation est un mur. Et la plupart des outils de test ne savent pas le franchir.
Les trois mécanismes qui compliquent tout
Le Shadow DOM n'est que la partie visible du problème. Les Web Components reposent sur trois mécanismes qui, ensemble, créent un niveau de complexité que le test visuel classique gère mal.
L'encapsulation des styles
À l'intérieur d'un Shadow DOM, les styles sont locaux. Un sélecteur .button dans votre Shadow DOM ne cible que les éléments .button de ce Shadow DOM particulier. Pas ceux du document principal, pas ceux des autres composants.
L'inverse est aussi vrai : vos styles globaux — votre framework CSS, votre reset, vos classes utilitaires — ne s'appliquent pas à l'intérieur du Shadow DOM. Si votre composant Web repose sur des styles qui viennent « de l'extérieur », ils ne seront tout simplement pas là.
Pour le test visuel, cela signifie que vous ne pouvez pas raisonner sur le style d'un composant en regardant uniquement les feuilles de style globales. Chaque composant est un monde à part, avec ses propres règles.
Le slotting et la projection de contenu
Les slots permettent aux utilisateurs d'un composant d'injecter du contenu à l'intérieur du Shadow DOM. Le composant définit des emplacements (<slot>), et le contenu fourni par le parent est « projeté » dans ces emplacements.
Voici ce que cela implique pour le test visuel : le contenu visible dans un slot appartient au DOM principal (le « light DOM »), mais il est affiché à l'intérieur du Shadow DOM. Il hérite de certains styles du Shadow DOM mais reste techniquement dans le light DOM. Cette dualité crée des situations où un outil de test voit l'élément dans le light DOM mais ne comprend pas son contexte visuel réel.
Un texte slotté peut hériter de la couleur de texte du Shadow DOM via l'héritage CSS, mais garder sa propre taille de police définie dans le light DOM. Le résultat visuel est un mélange des deux contextes — et seul le navigateur sait exactement ce qui est affiché.
Les CSS Custom Properties (variables CSS)
Les CSS custom properties (les « variables CSS ») sont le seul mécanisme CSS standard qui traverse la frontière du Shadow DOM. Si vous définissez --primary-color: blue sur l'élément hôte, cette variable est accessible à l'intérieur du Shadow DOM.
C'est le mécanisme principal de theming des Web Components. Les design systems basés sur Web Components exposent des dizaines, parfois des centaines de custom properties pour permettre la personnalisation.
Le problème pour le test visuel : la valeur effective d'une custom property dépend de la cascade CSS complète — les valeurs définies dans le document, celles héritées, celles redéfinies localement. Pour vérifier qu'un composant s'affiche correctement, il faut résoudre cette cascade. Et la seule entité qui le fait correctement, c'est le navigateur lui-même.
Pourquoi les approches classiques échouent
Examinons concrètement pourquoi les outils de test visuel courants peinent avec les Web Components.
Les outils basés sur le DOM
De nombreux outils de test inspectent le DOM pour comprendre la structure de la page. Ils parcourent les éléments, lisent les classes CSS, et en déduisent l'apparence attendue. Face à un Shadow DOM, ces outils se heurtent à un mur : les éléments internes ne sont pas visibles via les API DOM standard.
Certes, il existe shadowRoot pour accéder au contenu d'un Shadow DOM ouvert. Mais un outil de test doit activement traverser chaque Shadow DOM, gérer les Shadow DOM imbriqués (un composant Web à l'intérieur d'un autre composant Web), et comprendre l'interaction entre le light DOM et le Shadow DOM.
La plupart des outils n'ont pas été conçus pour cela. Ils ont été construits à une époque où le DOM était un arbre unique et plat.
La comparaison pixel-à-pixel
L'approche screenshot fonctionne… en surface. Elle capture ce que le navigateur affiche, Shadow DOM ou pas. Mais elle ne comprend pas la structure. Si un composant Web change de rendu à cause d'une modification de custom property héritée, la comparaison pixel détecte un changement mais ne peut pas identifier la cause.
Plus problématique : la comparaison pixel ne peut pas vérifier des propriétés structurelles. Le contraste d'un texte à l'intérieur d'un Shadow DOM respecte-t-il les WCAG ? L'espacement entre les éléments slottés est-il cohérent ? Ces questions nécessitent une compréhension structurelle, pas une comparaison d'images.
Les sélecteurs CSS dans les tests
Si vous écrivez des tests qui vérifient des styles via des sélecteurs CSS (par exemple, « le bouton primaire doit avoir un background-color de #0066FF »), vous avez un problème. Vos sélecteurs CSS ne traversent pas le Shadow DOM. Le bouton que vous cherchez est invisible pour votre sélecteur.
Vous pouvez contourner le problème en chaînant l'accès au shadowRoot, mais cela rend vos tests fragiles et dépendants de la structure interne du composant — exactement ce que l'encapsulation du Shadow DOM est censée prévenir.
L'approche structurelle : pourquoi elle traverse le Shadow DOM
L'approche structurelle du test visuel contourne élégamment le problème du Shadow DOM. Et voici pourquoi : elle ne lit pas le DOM pour deviner ce qui est affiché. Elle lit les propriétés CSS calculées — les valeurs finales que le navigateur a effectivement calculées et appliquées.
Quand le navigateur rend un élément, qu'il soit dans le light DOM, le Shadow DOM, ou projeté via un slot, il résout la cascade CSS complète et produit des valeurs calculées concrètes. La couleur de fond n'est plus « var(--surface-color) » mais « rgb(30, 30, 30) ». La taille de police n'est plus « 1.2em » mais « 19.2px ».
En lisant ces valeurs calculées, l'approche structurelle obtient la vérité du navigateur. Elle n'a pas besoin de comprendre l'encapsulation du Shadow DOM, la résolution des custom properties, ou les règles de slotting. Le navigateur a déjà fait tout ce travail. L'outil n'a qu'à lire le résultat.
C'est une distinction fondamentale. Au lieu d'essayer de reproduire la logique du navigateur (et d'échouer face au Shadow DOM), l'approche structurelle fait confiance au navigateur et vérifie son output.
Les cas concrets où cela fait la différence
Pour illustrer l'avantage de cette approche, considérons des situations réelles que rencontrent les équipes utilisant des Web Components.
Le theming cassé
Votre design system expose une custom property --button-bg pour personnaliser la couleur des boutons. Une équipe met à jour le thème principal et renomme la variable en --btn-background. Tous les boutons du Shadow DOM perdent leur couleur personnalisée et retombent sur la valeur par défaut.
Un test structurel détecte immédiatement que la couleur calculée du bouton a changé. Un test pixel le détecte aussi, mais signale un changement sans expliquer la cause. Un test DOM ne détecte rien parce que le composant est structurellement identique.
Les slots mal stylés
Un composant de carte utilise un slot pour le titre. Le titre est fourni par le parent en <h3>. Quelqu'un modifie les styles globaux des <h3> sans réaliser que ces styles s'appliquent aussi aux titres slottés dans les cartes — parce que les éléments slottés héritent des styles du light DOM pour les propriétés non définies dans le Shadow DOM.
L'approche structurelle vérifie les propriétés calculées du <h3> dans son contexte réel d'affichage (à l'intérieur du slot) et détecte le changement de taille ou de graisse.
Les composants imbriqués
Un composant de dialogue contient un composant de formulaire, qui contient des composants d'input. Trois niveaux de Shadow DOM imbriqués. Une modification de custom property au niveau du dialogue doit se propager à travers les trois niveaux.
L'approche structurelle vérifie les valeurs calculées à chaque niveau sans se soucier de la profondeur d'imbrication. Le navigateur a résolu la cascade. L'outil lit le résultat.
Web Components et design systems : l'enjeu stratégique
Les Web Components ne sont pas utilisés de manière isolée. Ils sont la technologie de choix pour les design systems modernes, et ce pour une bonne raison : un composant Web fonctionne avec React, Angular, Vue, ou sans framework. C'est l'interopérabilité ultime.
Mais cette interopérabilité crée un enjeu de test visuel majeur. Votre design system en Web Components est utilisé par plusieurs équipes, dans plusieurs applications, avec des contextes CSS différents. Un bug visuel dans un composant de base se propage partout.
Le test visuel d'un design system basé sur Web Components n'est pas optionnel. C'est une assurance qualité pour toutes les équipes qui en dépendent. Et cet assurance doit fonctionner à travers le Shadow DOM, avec les slots, avec les custom properties.
L'approche structurelle est, à ce jour, la seule qui coche toutes ces cases sans nécessiter de contorsions techniques.
Comment Delta-QA gère les Web Components
Delta-QA utilise l'approche structurelle. L'outil lit les propriétés CSS calculées de chaque élément visible, qu'il soit dans le light DOM, le Shadow DOM, ou projeté via un slot. Aucune configuration spéciale n'est nécessaire pour les Web Components — l'outil les traite comme n'importe quel autre élément du rendu.
Concrètement, Delta-QA vérifie le contraste des textes à l'intérieur des Shadow DOM, détecte les incohérences d'espacement entre composants, et identifie les régressions de theming quand une custom property change de valeur. Tout cela sans écrire de test, sans sélecteur CSS spécifique, sans accès explicite au shadowRoot.
C'est le test visuel no-code appliqué aux Web Components. Vous pointez l'outil vers votre page, et il analyse le rendu tel que le navigateur le produit.
Conseils pratiques pour tester vos Web Components visuellement
Si vous utilisez des Web Components — ou si vous envisagez de les adopter —, voici comment aborder le test visuel de manière pragmatique.
Testez les composants isolément d'abord
Avant de tester vos pages complètes, testez chaque composant dans un environnement isolé (Storybook ou page de démo). Vérifiez les états (défaut, hover, focus, disabled, erreur) et les variantes (tailles, couleurs, modes clair/sombre).
Vérifiez les points d'intégration
Les bugs visuels les plus vicieux apparaissent aux points d'intégration : là où le light DOM rencontre le Shadow DOM, là où un composant est imbriqué dans un autre, là où les custom properties traversent les frontières.
Surveillez les custom properties
Tenez un inventaire de vos custom properties de theming. L'approche structurelle détecte automatiquement les changements de valeurs calculées quelle qu'en soit la cause.
Intégrez le test visuel dans votre pipeline de publication
Chaque nouvelle version d'un composant Web devrait passer par un test visuel automatisé avant d'être publiée. Une régression dans un composant de base a un effet multiplicateur dévastateur.
FAQ
Le Shadow DOM empêche-t-il le test visuel automatisé ?
Non, mais il empêche certaines approches de test visuel. Les outils qui inspectent le DOM directement ne voient pas les éléments à l'intérieur du Shadow DOM sans adaptation spécifique. En revanche, les outils qui lisent les propriétés CSS calculées (approche structurelle) traversent le Shadow DOM sans difficulté, car ils lisent les valeurs finales calculées par le navigateur.
Comment les slots affectent-ils le test visuel des Web Components ?
Les slots créent une dualité : le contenu slotté appartient au light DOM mais est affiché dans le contexte visuel du Shadow DOM. Les styles hérités viennent des deux côtés. Un outil de test visuel efficace doit vérifier l'apparence réelle de l'élément dans son contexte d'affichage final, pas sa position dans l'arbre DOM. L'approche structurelle gère ce cas naturellement.
Faut-il des tests visuels spécifiques pour les Web Components ?
Pas si votre outil utilise l'approche structurelle. Les règles de qualité visuelle (contraste, espacement, alignement, cohérence) s'appliquent de la même manière à tous les éléments, qu'ils soient dans le light DOM ou le Shadow DOM. Vous n'avez pas besoin de tests « spécial Web Components » — vous avez besoin d'un outil qui fonctionne partout.
Delta-QA nécessite-t-il une configuration spéciale pour les Web Components ?
Non. Delta-QA analyse les propriétés CSS calculées de tous les éléments visibles, indépendamment de leur position dans le DOM. Les éléments à l'intérieur du Shadow DOM sont traités exactement comme les autres. Aucun sélecteur spécial, aucune configuration de shadowRoot, aucun script d'accès.
Les Web Components créent-ils plus de régressions visuelles que les composants classiques ?
Pas intrinsèquement, mais les régressions sont plus difficiles à détecter avec les outils classiques. L'encapsulation du Shadow DOM masque les changements aux outils qui n'y sont pas préparés. De plus, les interactions entre custom properties, héritage CSS et slotting créent des chaînes de dépendance subtiles qu'un test visuel automatisé est mieux placé pour surveiller qu'un humain.
Quels frameworks de Web Components sont compatibles avec le test visuel structurel ?
L'approche structurelle est agnostique du framework. Que vous utilisiez Lit, Stencil, FAST, ou des Web Components vanilla, le navigateur produit les mêmes propriétés CSS calculées. Delta-QA fonctionne avec tous les frameworks de Web Components sans distinction, car il analyse le résultat du rendu, pas le code source du composant.