Puntos clave
- El Shadow DOM encapsula estilos y DOM, haciendo que los enfoques clásicos de prueba visual sean parcialmente ciegos
- Las herramientas que inspeccionan el DOM «normal» no pueden ver los elementos dentro del Shadow DOM sin una adaptación específica
- El enfoque estructural, basado en propiedades CSS calculadas, funciona a través del Shadow DOM porque lee el resultado final del navegador
- Los slots, las CSS custom properties y la herencia de estilos crean interacciones complejas que solo el análisis del renderizado real puede verificar
MDN define los Web Components como «un conjunto de tecnologías que permiten la creación de elementos HTML personalizados reutilizables, cuya funcionalidad está encapsulada y aislada del resto del código» (MDN Web Docs, Web Components).
Esta definición oculta una revolución silenciosa. Los Web Components ya no son una curiosidad experimental. En 2026, todos los navegadores principales los soportan de forma nativa. Frameworks como Lit, Stencil y FAST los utilizan como cimientos. Empresas como Adobe (Spectrum Web Components), SAP (UI5 Web Components) e ING Bank (Lion Web Components) construyen design systems completos sobre esta tecnología.
Y sin embargo, la prueba visual de Web Components sigue siendo un punto ciego para la mayoría de los equipos. La razón se resume en dos palabras: Shadow DOM.
Lo esencial en una página — definición, automatización sin código, cómo elegir una herramienta: Pruebas de regresión automatizadas, sin código.
El Shadow DOM ya no tiene por qué ser un punto ciego de tu QA. Compara el renderizado visual real de tus Web Components en no-code, con el plan gratuito y sin tarjeta de crédito. Probar Delta-QA gratis →
Qué cambia el Shadow DOM para la prueba visual
Normalmente, todo el DOM de tu página es un único árbol. Los selectores CSS se aplican a todos los elementos. Las herramientas de prueba pueden recorrer la estructura completa.
El Shadow DOM rompe esta suposición. Crea un subárbol DOM aislado, adjunto a un elemento host, con sus propios estilos. Los selectores CSS externos no pueden alcanzar los elementos internos. Los scripts que recorren el DOM con querySelector no ven lo que hay dentro del shadow.
Y ese es exactamente el propósito del Shadow DOM: la encapsulación. Tus estilos no se filtran hacia afuera, los estilos externos no contaminan el interior. Es una funcionalidad, no un error.
Pero para la prueba visual, esta encapsulación es un muro. Y la mayoría de las herramientas de prueba no saben cómo atravesarlo.
Tres mecanismos que lo complican todo
Encapsulación de estilos
Dentro de un Shadow DOM, los estilos son locales. Un selector .button en tu Shadow DOM solo afecta a los elementos .button de ese Shadow DOM en particular. Y viceversa: tus estilos globales no se aplican dentro del Shadow DOM.
Para la prueba visual, esto significa que no puedes deducir el estilo de un componente observando únicamente las hojas de estilo globales. Cada componente es un mundo propio con sus propias reglas.
Slotting y proyección de contenido
Los slots permiten a los usuarios del componente inyectar contenido dentro del Shadow DOM. El componente define los slots (<slot>), y el contenido del padre se «proyecta» en ellos.
Para la prueba visual: el contenido slotteado pertenece al light DOM pero se muestra dentro del contexto del Shadow DOM. Hereda algunos estilos del Shadow DOM, pero sigue perteneciendo técnicamente al light DOM. Esta dualidad crea situaciones donde la herramienta de prueba ve el elemento en el light DOM pero no comprende su contexto visual real.
CSS custom properties
Las CSS custom properties (variables CSS) son el único mecanismo CSS estándar que atraviesa la frontera del Shadow DOM. Si defines --primary-color: blue en el elemento host, esta variable es accesible dentro del Shadow DOM.
Este es el mecanismo principal de theming para Web Components. El problema para la prueba visual: el valor efectivo de una custom property depende de la cascada CSS completa. La única entidad que resuelve esto correctamente es el propio navegador.
El Shadow DOM no debería dejar ciega tu prueba visual. Comprueba cómo Delta-QA detecta las regresiones con un enfoque no-code, gratuito. Probar Delta-QA gratis →
Por qué los enfoques clásicos fallan
Herramientas basadas en el DOM
Muchas herramientas de prueba inspeccionan el DOM para comprender la estructura de la página. Cuando se enfrentan a un Shadow DOM, tropiezan con un muro: los elementos internos no son visibles a través de las APIs DOM estándar. La mayoría de las herramientas no fueron construidas para esto — se crearon cuando el DOM era un único árbol plano.
Comparación píxel a píxel
El enfoque de screenshot funciona… en la superficie. Captura lo que el navegador muestra, Shadow DOM o no. Pero no comprende la estructura. Si un Web Component cambia de renderizado debido a una modificación de custom property heredada, la comparación de píxeles detecta el cambio pero no puede identificar la causa.
Selectores CSS en los tests
Si escribes tests que verifican estilos mediante selectores CSS, tus selectores no atraviesan el Shadow DOM. Puedes solucionarlo encadenando accesos a shadowRoot, pero eso hace los tests frágiles y dependientes de la estructura interna del componente — exactamente lo que la encapsulación del Shadow DOM pretende evitar.
Comparar el renderizado real: por qué este enfoque atraviesa el Shadow DOM
Comparar el resultado visual que produce el navegador esquiva con elegancia el problema del Shadow DOM. La razón es sencilla: en lugar de leer el DOM para adivinar qué se muestra, el enfoque estructural observa el renderizado final — lo que el navegador pinta realmente en pantalla una vez aplicados todos los estilos.
Cuando el navegador renderiza un elemento, ya esté en el light DOM, en el Shadow DOM o proyectado a través de un slot, resuelve la cascada CSS completa y produce valores calculados concretos. El color de fondo ya no es «var(--surface-color)» sino «rgb(30, 30, 30)». El tamaño de fuente ya no es «1.2em» sino «19.2px».
Apoyándose en este renderizado, el motor de comparación visual determinista obtiene la verdad del navegador. No necesita entender la encapsulación del Shadow DOM, la resolución de las custom properties ni las reglas de slotting: el navegador ya ha hecho ese trabajo. La herramienta solo tiene que comparar el resultado visual tal y como se muestra.
Es una distinción de fondo. En lugar de intentar reproducir la lógica del navegador (y fallar frente al Shadow DOM), el motor confía en el navegador y verifica lo que este muestra realmente.
Los casos concretos donde esto marca la diferencia
Para ilustrar la ventaja de este enfoque, veamos situaciones reales que se encuentran los equipos que trabajan con Web Components.
El theming roto
Tu design system expone una custom property --button-bg para personalizar el color de los botones. Un equipo actualiza el tema principal y renombra la variable a --btn-background. Todos los botones del Shadow DOM pierden su color personalizado y caen de vuelta al valor por defecto.
Un test estructural detecta de inmediato que el color calculado del botón ha cambiado. Un test de píxeles también lo detecta, pero solo señala un cambio sin explicar la causa. Un test basado en el DOM no detecta nada, porque el componente sigue siendo estructuralmente idéntico.
Los slots mal estilados
Un componente de tarjeta usa un slot para el título. El título lo proporciona el padre en un <h3>. Alguien modifica los estilos globales de los <h3> sin darse cuenta de que también afectan a los títulos slotteados dentro de las tarjetas — porque los elementos slotteados heredan los estilos del light DOM para las propiedades no definidas en el Shadow DOM.
El motor compara el resultado visual del <h3> en su contexto real de visualización (dentro del slot) y detecta el cambio de tamaño o de peso de la fuente.
Los componentes anidados
Un componente de diálogo contiene un componente de formulario, que a su vez contiene componentes de input. Tres niveles de Shadow DOM anidados. Un cambio de custom property a nivel del diálogo debe propagarse a través de los tres niveles.
El motor compara el resultado visual en cada nivel sin importar la profundidad del anidamiento. El navegador ya resolvió la cascada. La herramienta compara lo que se muestra.
Web Components y design systems: el reto estratégico
Los Web Components no se usan de forma aislada. Son la tecnología elegida para los design systems modernos, y por una buena razón: un Web Component funciona con React, Angular, Vue o sin ningún framework. Es la interoperabilidad definitiva.
Pero esa interoperabilidad crea un reto de prueba visual de primer orden. Tu design system en Web Components lo usan varios equipos, en varias aplicaciones, con contextos CSS distintos. Un bug visual en un componente base se propaga a todas partes.
La prueba visual de un design system basado en Web Components no es opcional: es un seguro de calidad para todos los equipos que dependen de él. Y ese seguro tiene que funcionar a través del Shadow DOM, con los slots y con las custom properties.
El enfoque estructural es, a día de hoy, el único que cumple todos estos requisitos sin necesitar contorsiones técnicas.
Cómo Delta-QA gestiona los Web Components
El motor de comparación visual determinista de Delta-QA renderiza la página en un navegador real y compara el resultado visual de cada elemento mostrado, ya esté en el light DOM, en el Shadow DOM o proyectado a través de un slot. No hace falta ninguna configuración especial para los Web Components: la herramienta los trata como cualquier otro elemento del renderizado.
En la práctica, Delta-QA verifica el contraste de los textos dentro del Shadow DOM, detecta las inconsistencias de espaciado entre componentes e identifica las regresiones de theming cuando una custom property cambia de valor. Todo ello sin escribir ningún test, sin selectores CSS específicos, sin acceso explícito al shadowRoot.
Esto es la prueba visual no-code aplicada a los Web Components. Apuntas la herramienta a tu página y ella analiza el renderizado tal y como lo produce el navegador.
Consejos prácticos para probar tus Web Components visualmente
Si usas Web Components — o si te planteas adoptarlos —, así es como abordar la prueba visual de forma pragmática.
Prueba los componentes aisladamente primero
Antes de probar tus páginas completas, prueba cada componente en un entorno aislado (Storybook o página de demo). Verifica los estados (por defecto, hover, focus, disabled, error) y las variantes (tamaños, colores, modos claro/oscuro).
Verifica los puntos de integración
Los bugs visuales más traicioneros aparecen en los puntos de integración: donde el light DOM se encuentra con el Shadow DOM, donde un componente está anidado dentro de otro, donde las custom properties cruzan las fronteras.
Vigila las custom properties
Mantén un inventario de tus custom properties de theming. El motor de comparación visual determinista detecta automáticamente cualquier cambio de renderizado visible, sea cual sea su causa.
Integra la prueba visual en tu pipeline de publicación
Cada nueva versión de un Web Component debería pasar por una prueba visual automatizada antes de publicarse. Una regresión en un componente base tiene un efecto multiplicador devastador.
¿Listo para probar tus Web Components sin pelearte con el Shadow DOM? Apunta Delta-QA a tu página y lanza tu primera comparación visual, gratis y sin tarjeta de crédito. Probar Delta-QA gratis →
FAQ
¿El Shadow DOM impide la prueba visual automatizada?
No, pero impide ciertos enfoques de prueba visual. Las herramientas que inspeccionan el DOM no pueden ver los elementos del Shadow DOM sin una adaptación específica. Sin embargo, las herramientas que leen propiedades CSS calculadas (enfoque estructural) atraviesan el Shadow DOM sin esfuerzo, ya que leen los valores finales calculados por el navegador.
¿Cómo afectan los slots a la prueba visual de Web Components?
Los slots crean una dualidad: el contenido slotteado pertenece al light DOM pero se muestra en el contexto visual del Shadow DOM. Los estilos heredados provienen de ambos lados. Una herramienta de prueba visual efectiva debe verificar la apariencia real de un elemento en su contexto de visualización final, no su posición en el árbol DOM. El enfoque estructural gestiona esto de forma natural.
¿Se necesitan pruebas visuales específicas para Web Components?
No si tu herramienta utiliza el enfoque estructural. Las reglas de calidad visual (contraste, espaciado, alineación, consistencia) se aplican por igual a todos los elementos independientemente de su posición en el DOM. No necesitas «pruebas especiales para Web Components» — necesitas una herramienta que funcione en todas partes.
¿Delta-QA requiere una configuración especial para Web Components?
No. Delta-QA compara el resultado final renderizado por el navegador para todos los elementos visibles independientemente de su posición en el DOM. Los elementos del Shadow DOM se tratan exactamente igual que los demás. Sin selectores especiales, sin configuración de shadowRoot, sin scripts de acceso.
¿Los Web Components crean más regresiones visuales que los componentes tradicionales?
No intrínsecamente, pero las regresiones son más difíciles de detectar con herramientas clásicas. La encapsulación del Shadow DOM oculta los cambios de las herramientas no preparadas. Además, las interacciones entre custom properties, herencia CSS y slotting crean cadenas de dependencia sutiles que la prueba visual automatizada está mejor posicionada para monitorizar que un ser humano.
¿Qué frameworks de Web Components son compatibles con la prueba visual estructural?
El enfoque estructural es agnóstico al framework. Ya sea que utilices Lit, Stencil, FAST o Web Components vanilla, el navegador produce las mismas propiedades CSS calculadas. Delta-QA funciona con todos los frameworks de Web Components sin distinción, ya que compara el resultado final renderizado por el navegador, no el código fuente del componente.