关键要点
- Shadow DOM 封装了样式与 DOM，使经典的视觉测试方法部分失明
- 检查「普通」DOM 的工具无法看到 Shadow DOM 内部的元素，除非进行特定适配
- 基于计算 CSS 属性的结构化方法能穿透 Shadow DOM，因为它读取的是浏览器的最终输出
- Slots、CSS custom properties 与样式继承制造了复杂的交互，只有真实渲染分析才能验证
Web Components 被 MDN 定义为*「一组允许创建可重用的自定义 HTML 元素的技术，其功能被封装并与代码的其他部分隔离」*（MDN Web Docs, Web Components）。
这一定义掩盖了一场静悄悄的革命。Web Components 不再是实验性的好奇心。在 2026 年，所有主流浏览器都原生支持它们。Lit、Stencil、FAST 等框架将其作为基础。Adobe（Spectrum Web Components）、SAP（UI5 Web Components）和 ING Bank（Lion Web Components）等公司在这项技术上构建了完整的设计系统。
然而，Web Components 的视觉测试对大多数团队来说仍是一个盲点。原因可以归结为两个词：Shadow DOM。
Shadow DOM 对视觉测试意味着什么
通常，您页面上的所有 DOM 都是一棵单一的树。CSS 选择器适用于所有元素。测试工具可以遍历整个结构。
Shadow DOM 打破了这一假设。它创建了一棵独立的 DOM 子树，附着在宿主元素上，拥有自己的样式。外部 CSS 选择器无法触及内部元素。用 querySelector 遍历 DOM 的脚本看不到 shadow 中的内容。
这正是 Shadow DOM 存在的目的：封装。您的样式不向外渗漏，外部样式不会污染内部。这是特性，不是 bug。
但对于视觉测试，这种封装是一堵墙。而大多数测试工具不知道如何越过它。
让一切复杂化的三种机制
样式封装
在 Shadow DOM 内部，样式是局部的。您 Shadow DOM 中的 .button 选择器只匹配那个特定 Shadow DOM 中的 .button 元素。反向也成立：您的全局样式不会应用到 Shadow DOM 内部。
对视觉测试而言，这意味着您不能仅通过查看全局样式表来推断一个组件的样式。每个组件都是有自己规则的独立世界。
Slotting 与内容投影
Slot 允许组件使用者把内容注入到 Shadow DOM 内部。组件定义 slot（<slot>），父级的内容被「投影」到其中。
对视觉测试而言：被 slot 的内容属于 light DOM，但显示在 Shadow DOM 的上下文中。它继承了 Shadow DOM 的部分样式，但在技术上仍处于 light DOM。这种二元性产生了一些情况：测试工具能在 light DOM 中看到元素，却不理解其真实的视觉上下文。
CSS Custom Properties
CSS custom properties（CSS 变量）是唯一一种能跨越 Shadow DOM 边界的标准 CSS 机制。如果您在宿主元素上定义 --primary-color: blue，这个变量在 Shadow DOM 内部就是可访问的。
这是 Web Components 主要的主题化机制。视觉测试的麻烦在于：custom property 的有效值取决于完整的 CSS 级联。唯一能正确解析它的实体是浏览器本身。
为什么经典方法会失败
基于 DOM 的工具
许多测试工具通过检查 DOM 来理解页面结构。面对 Shadow DOM 时，它们撞墙：内部元素无法通过标准 DOM API 看到。大多数工具不是为这种情况构建的——它们诞生于 DOM 还是单一扁平树的年代。
像素对像素的比较
截图方法在表面上是有效的。它捕获浏览器所显示的内容，无论有没有 Shadow DOM。但它不理解结构。如果某个 Web Component 因为继承的 custom property 被修改而改变了渲染，像素比较能检测到变化，但无法识别原因。
测试中的 CSS 选择器
如果您写测试用 CSS 选择器来验证样式，您的选择器无法穿透 Shadow DOM。您可以通过链式访问 shadowRoot 来变通，但这会让测试变得脆弱并依赖组件内部结构——而这恰恰是 Shadow DOM 封装本应防止的。
结构化方法：为什么它能穿透 Shadow DOM
结构化视觉测试方法优雅地绕过了 Shadow DOM 问题。它不读 DOM 来猜测显示的内容。它读取计算后的 CSS 属性——浏览器实际计算并应用的最终值。
当浏览器渲染一个元素时——无论它在 light DOM、Shadow DOM 中，或是通过 slot 投影——它都会解析完整的 CSS 级联并产生具体的计算值。背景色不再是「var(--surface-color)」，而是「rgb(30, 30, 30)」。字号不再是「1.2em」，而是「19.2px」。
通过读取这些计算值，结构化方法获得的是浏览器的真相。它不需要理解 Shadow DOM 封装、custom property 解析或 slotting 规则。浏览器已经完成了所有这些工作。工具只读结果。
这是一个根本性的区别。结构化方法不是试图复现浏览器的逻辑（并在 Shadow DOM 面前失败），而是信任浏览器并验证其输出。
让差异显现的具体场景
主题化被破坏
您的设计系统暴露 --button-bg 来定制按钮颜色。某个团队更新了主主题并把变量重命名为 --btn-background。所有 Shadow DOM 中的按钮失去自定义颜色，回退到默认值。
结构化测试立即检测到按钮的计算颜色变了。像素测试也能检测到，但报告变化时无法解释原因。基于 DOM 的测试什么都检测不到，因为组件在结构上完全相同。
样式不当的 Slots
一个 card 组件用一个 slot 来承载标题。标题由父级以 <h3> 形式提供。某人修改了全局 <h3> 样式，没意识到它们也会作用于 card 中被 slot 的标题——因为被 slot 的元素对未在 Shadow DOM 中定义的属性会从 light DOM 继承样式。
结构化方法在 <h3> 实际显示上下文（slot 内部）中检查它的计算属性，并检测到尺寸或字重的变化。
嵌套组件
一个 dialog 组件包含一个 form 组件，后者又包含一些 input 组件。三层嵌套的 Shadow DOM。在 dialog 层级的某个 custom property 修改必须穿过全部三层。
结构化方法在每一层验证计算值，不在意嵌套深度。浏览器已经解析了级联。工具只读结果。
Web Components 与设计系统：战略上的必然
Web Components 是现代设计系统的首选技术——同一个 Web Component 可以在 React、Angular、Vue 中使用，或者不依赖任何框架。这是终极的互操作性。
但这种互操作性带来了一个重大的视觉测试挑战。您基于 Web Components 的设计系统被多个团队、多个应用、多种 CSS 上下文使用。一个基础组件中的视觉 bug 会传播到所有地方。
对一个基于 Web Components 的设计系统进行视觉测试不是可选项。它是对所有依赖团队的质量保障。而这种保障必须能够穿透 Shadow DOM、能够处理 slot、能够理解 custom property。
到目前为止，结构化方法是唯一在不需要技术折中的前提下满足所有这些要求的方案。
Delta-QA 如何处理 Web Components
Delta-QA 使用结构化方法。它读取每个可见元素的计算 CSS 属性，无论它在 light DOM、Shadow DOM，还是通过 slot 投影。Web Components 不需要特殊配置——工具把它们当作其他任何已渲染的元素来处理。
具体而言，Delta-QA 验证 Shadow DOM 内部的文本对比度、检测组件之间的间距不一致、识别 custom property 改变取值时的主题化回归。所有这些都不需要写测试、不需要特定的 CSS 选择器、不需要显式访问 shadowRoot。
视觉化测试您的 Web Components 的实用建议
先在隔离环境中测试组件
在测试完整页面之前，在隔离环境（Storybook 或 demo 页面）中测试每个组件。验证状态（默认、hover、focus、disabled、error）和变体（尺寸、颜色、亮/暗模式）。
验证集成点
最隐蔽的视觉 bug 出现在集成点：light DOM 与 Shadow DOM 相遇之处、一个组件嵌套在另一个组件中之处、custom property 跨越边界之处。
监控 Custom Properties
为您的主题化 custom properties 建立一份清单。结构化方法会自动检测计算值的变化，无论原因为何。
把视觉测试集成到您的发布流水线
每一个新版本的 Web Component 在发布前都应通过自动化视觉测试。基础组件中的回归会有毁灭性的乘数效应。
常见问题
Shadow DOM 会阻止自动化视觉测试吗？
不会，但它会阻止某些方法的视觉测试。检查 DOM 的工具如果不进行特定适配，看不到 Shadow DOM 中的元素。然而，读取计算 CSS 属性的工具（结构化方法）可以毫无困难地穿透 Shadow DOM，因为它们读取的是浏览器最终计算出的值。
Slot 如何影响 Web Components 的视觉测试？
Slot 创造了一种二元性：被 slot 的内容属于 light DOM，却显示在 Shadow DOM 的视觉上下文中。继承的样式来自两边。一款有效的视觉测试工具必须在元素的最终显示上下文中验证它的实际外观，而不是验证其在 DOM 树中的位置。结构化方法天然地处理这一点。
Web Components 需要特定的视觉测试吗？
如果您的工具使用结构化方法，则不需要。视觉质量规则（对比度、间距、对齐、一致性）平等地适用于所有元素，无关其 DOM 位置。您不需要「特殊的 Web Components 测试」——您需要的是一款在任何地方都有效的工具。
Delta-QA 对 Web Components 需要特殊配置吗？
不需要。Delta-QA 分析所有可见元素的计算 CSS 属性，无论其在 DOM 中的位置。Shadow DOM 元素被当作其他元素一视同仁。无需特殊选择器、无需配置 shadowRoot、无需访问脚本。
Web Components 比传统组件产生更多的视觉回归吗？
本质上不是，但用经典工具更难检测到这些回归。Shadow DOM 封装会对未做准备的工具掩盖变化。此外，custom properties、CSS 继承与 slotting 之间的互动会形成微妙的依赖链——自动化视觉测试比人工监控更适合追踪这种链条。
哪些 Web Components 框架兼容结构化视觉测试？
结构化方法是 framework-agnostic 的。无论您使用 Lit、Stencil、FAST，还是原生 Web Components，浏览器都会产生相同的计算 CSS 属性。Delta-QA 与所有 Web Components 框架兼容，不加区分，因为它分析的是渲染结果，而不是组件的源代码。