Cypress与Shadow DOM：如何正确选取隐藏在阴影DOM中的元素-html教程-PHP中文网

Cypress与Shadow DOM：如何正确选取隐藏在阴影DOM中的元素

心靈之曲

发布： 2025-10-25 12:05:06

原创

872人浏览过

Cypress与Shadow DOM：如何正确选取隐藏在阴影DOM中的元素

cypress在测试web组件时，常因元素位于shadow dom内部而无法定位。本文旨在解决这一常见问题，详细阐述如何利用cypress的`.shadow()`命令，结合正确的shadow host选择器，有效穿透shadow dom边界，精准定位并操作其中的表单元素，确保测试的准确性和稳定性。

引言：Shadow DOM与Cypress测试的挑战

现代Web开发中，Web Components（Web组件）因其封装性、可重用性而日益普及。Shadow DOM是Web Components的关键技术之一，它允许开发者将一个DOM子树封装起来，使其与主文档DOM分离，从而避免样式和行为上的冲突。然而，这种封装特性也给自动化测试工具带来了挑战。

当元素被封装在Shadow DOM内部时，传统的Cypress选择器（如cy.get('input[name=firstName]')）默认情况下无法“穿透”Shadow DOM的边界。这意味着Cypress无法直接访问到这些隐藏在“阴影”中的元素，导致测试失败并抛出超时错误。

问题重现：无法定位Shadow DOM内元素

考虑一个常见的场景：您正在尝试测试一个包含表单字段的Web页面，而这些字段位于一个Web组件的Shadow DOM内部。例如，对于以下测试代码：

describe('Verify identity data', () => {
  it('Makes an assertion', function () {
    cy.visit('https://whitelabel.sandbox.array.io/signup?platform=v3');
    cy.get('input[name=firstName]');
  });
});

登录后复制

当目标页面（如https://whitelabel.sandbox.array.io/signup?platform=v3）上的input[name=firstName]元素实际位于Shadow DOM中时，Cypress会报告如下错误：

Timed out retrying after 4000ms: Expected to find element: input[name=firstName], but never found it.

登录后复制

这明确指出Cypress在默认超时时间内未能找到指定的元素，根本原因在于它无法跨越Shadow DOM的边界。

解决方案核心：Cypress的.shadow()命令

为了解决这一问题，Cypress提供了专门的.shadow()命令。此命令允许您在选择Shadow Host（即承载Shadow DOM的宿主元素）之后，进入其Shadow DOM内部，从而能够访问其中的元素。

工作原理：

腾讯元宝

腾讯混元平台推出的AI助手

223

查看详情

识别Shadow Host： 首先，您需要定位到包含Shadow DOM的宿主元素。这通常是一个自定义的HTML标签（如<array-account-enroll>）或者具有shadowRoot属性的常规HTML元素。您可以使用浏览器的开发者工具（Elements面板）来检查DOM结构，找到哪个元素是Shadow Host。通常，Shadow Host会显示一个#shadow-root (open)或#shadow-root (closed)的指示。
使用.shadow()进入： 一旦通过cy.get()或其他Cypress命令选中了Shadow Host，就可以在其后链式调用.shadow()命令。这个命令会将其上下文切换到Shadow DOM的根节点。
在Shadow DOM内查找元素： 切换到Shadow DOM根节点后，您可以继续使用.find()命令（而非cy.get()，因为cy.get()是从整个文档中查找）来定位Shadow DOM内部的特定元素。

实战演练：定位Shadow DOM中的表单元素

现在，我们将应用.shadow()命令来修正之前的测试代码。

假设通过开发者工具检查，我们发现input[name="firstName"]元素位于<array-account-enroll>这个自定义元素的Shadow DOM内部。

<!-- 页面主DOM结构 -->
<body>
  <div id="root">
    <array-account-enroll>
      #shadow-root (open)
        <!-- Shadow DOM 内部结构 -->
        <div class="form-container">
          <input name="firstName" type="text" />
          <!-- ... 其他 Shadow DOM 内部元素 ... -->
        </div>
    </array-account-enroll>
  </div>
</body>

登录后复制

修正后的Cypress测试代码如下：

describe("Verify identity data", () => {
  it("Makes an assertion", function () {
    cy.visit("https://whitelabel.sandbox.array.io/signup?platform=v3");
    // 1. 定位 Shadow Host 元素
    cy.get("array-account-enroll")
      // 2. 使用 .shadow() 进入 Shadow DOM
      .shadow()
      // 3. 在 Shadow DOM 内部查找目标元素
      .find('input[name="firstName"]')
      // 4. 可以继续对找到的元素进行操作，例如断言其存在或输入值
      .should('be.visible')
      .type('John');
  });
});

登录后复制

代码解析：

cy.get("array-account-enroll"): 首先，我们使用cy.get()命令定位到Shadow Host元素，即<array-account-enroll>。
.shadow(): 接着，我们链式调用.shadow()命令。这个命令会获取<array-account-enroll>元素的Shadow DOM根节点，并将后续命令的作用域限定在这个Shadow DOM内部。
.find('input[name="firstName"]'): 最后，我们使用.find()命令在当前作用域（即Shadow DOM内部）中查找name属性为firstName的input元素。此时，Cypress就能成功定位到目标元素。

注意事项与最佳实践

识别Shadow Host的重要性： 准确识别Shadow Host是使用.shadow()命令的关键。务必利用浏览器开发者工具仔细检查DOM结构，找到带有#shadow-root标识的元素。
.find()与cy.get()： 一旦进入Shadow DOM，应使用.find()命令来查找内部元素，而不是cy.get()。cy.get()总是从整个文档的根节点开始查找，而.find()则从当前被选中的元素（在此例中是Shadow DOM根节点）开始向下查找。
多层嵌套Shadow DOM： 如果存在多层嵌套的Shadow DOM（即一个Shadow DOM内部又包含另一个Shadow Host），您可能需要多次链式调用.shadow()命令来逐层深入。例如：cy.get('host-one').shadow().find('host-two').shadow().find('target-element')。
开放与封闭Shadow DOM： Shadow DOM可以是“开放（open）”或“封闭（closed）”的。Cypress的.shadow()命令主要用于处理开放的Shadow DOM。对于封闭的Shadow DOM，由于其设计上就是为了阻止外部JavaScript访问，Cypress通常也无法直接访问。幸运的是，大多数Web组件的Shadow DOM都是开放的，以允许外部交互。
测试稳定性： 确保您的Shadow Host选择器足够稳定，不易受页面结构变化影响。使用data-testid或其他明确的测试ID属性来定位Shadow Host是一个良好的实践。

总结

掌握如何处理Shadow DOM是进行Web组件自动化测试不可或缺的技能。Cypress的.shadow()命令提供了一个强大而直观的机制来穿透Shadow DOM的边界，使您能够像操作常规DOM元素一样，对Shadow DOM内部的元素进行定位和交互。通过正确识别Shadow Host并合理运用.shadow()和.find()命令，您可以构建出更健壮、更全面的Cypress测试套件，有效覆盖现代Web应用中的所有UI元素。

以上就是Cypress与Shadow DOM：如何正确选取隐藏在阴影DOM中的元素的详细内容，更多请关注php中文网其它相关文章！