Web组件技术通过Shadow DOM实现样式与结构的封装，但这也给端到端测试工具带来了麻烦。Cypress在较早版本中并不会自动进入影子树查找元素，导致很多封装在自定义元素内部的按钮、输入框即便存在于页面上，用普通选择器也拿不到。理解Shadow DOM的开放与关闭模式，以及Cypress提供的穿透能力，是写稳这类测试的前提。
Shadow DOM基础与测试难点
Shadow DOM是Web Components规范的一部分，它允许将一个独立的DOM树附加到某个宿主元素上，内部节点对外不可见，外部CSS也无法穿透。这种封装对前端工程化非常友好，但也意味着传统基于全局document的查询方式失效。例如一个<my-button>内部藏着一个真实按钮，页面上虽然能看到，但document.querySelector无法直接命中。
在Cypress里，如果元素位于open模式的影子树中，可以通过开启特定配置进入；如果是closed模式，则连JS都拿不到shadowRoot，测试难度更高。很多团队在引入组件库后才发现旧用例大面积报错，本质就是没处理影子边界。下面用一个最简单的自定义元素说明结构。
<!-- 宿主元素 -->
<my-input></my-input>
<script>
class MyInput extends HTMLElement {
constructor() {
super();
const shadow = this.attachShadow({ mode: 'open' });
shadow.innerHTML = '<input class="real-input" placeholder="请输入">';
}
}
customElements.define('my-input', MyInput);
</script>
使用includeShadowDom全局穿透
Cypress从较新版本开始支持includeShadowDom配置，开启后cy.get会自动遍历影子树。这是最省事的方案，适合项目里大量使用Web组件的情况。在cypress.config.js里加上这一行即可，不需要改测试代码。
不过全局开启会带来轻微性能损耗，因为每次查询都要递归影子节点。若仅个别用例需要，也可以用cy.get(selector, { includeShadowDom: true })做局部开启。下面展示配置与用例写法。
// cypress.config.js
const { defineConfig } = require('cypress');
module.exports = defineConfig({
e2e: {
includeShadowDom: true,
setupNodeEvents() {}
}
});
// 测试用例
describe('shadow dom test', () => {
it('能定位到内部输入框', () => {
cy.visit('/demo');
cy.get('my-input').find('.real-input').should('be.visible');
});
});
这种写法的优势是语义清晰，find会顺着影子边界进入。但如果组件嵌套多层影子树，建议确认每一层都是open模式，否则仍会中断。相比手动调用shadowRoot，配置化方案更不易在重构时遗漏。
自定义命令封装穿透逻辑
当项目里存在closed模式或需要更细控制时，可以写Cypress自定义命令，用.shadowRoot手动穿透。虽然closed模式在标准上不暴露根节点，但不少框架在测试环境会降级为open，此时封装命令能提高复用度。
下面的命令接收宿主选择器和内部选择器，先拿到宿主再进影子树查询，并加了重试等待，避免元素未挂载就报错。它比纯配置更灵活，也能在命令里加日志方便调试。
Cypress.Commands.add('getInShadow', (hostSel, innerSel) => {
return cy.get(hostSel).then((host) => {
const el = host[0].shadowRoot.querySelector(innerSel);
return cy.wrap(el);
});
});
// 使用
cy.getInShadow('my-input', '.real-input').type('hello');
要注意的是，then里直接操作DOM拿到的是原生元素，用cy.wrap包回Cypress对象才能继续链式调用如type。这种命令在微前端子应用使用不同影子策略时尤其有用，可针对宿主类型切换穿透方式。
常见误区与稳定性建议
一个典型误区是以为开启includeShadowDom就能搞定一切，结果遇到closed模式还是失败。另一个误区是在then里同步查询却不等待渲染，导致拿到null。Cypress的自动重试只覆盖cy.get层，手动进影子树的部分需自己保证时机。
建议在CI中给Web组件用例单独分组，并配合cy.contains在影子内做文本断言，减少依赖易变类名。若组件来自第三方库且为closed模式，可考虑让开发在测试构建里改mode，或借助cy.document遍历customElements做钩子。下表列出两种方案对比。
| 方案 | 适用场景 | 维护成本 |
|---|---|---|
| 全局includeShadowDom | 项目普遍用open影子组件 | 低 |
| 自定义穿透命令 | 混合模式或需日志调试 | 中 |
合理组合两者，既能让隐藏元素被稳定定位，也不至于让测试套件变得脆弱。写Web组件测试时，先确认封装模式再选策略，比盲目加等待更有效。
CypressShadow_DOMWeb_Components修改时间：2026-07-31 21:48:29