本文旨在解决cypress测试中因shadow dom导致元素查找失败的问题。我们将深入探讨shadow dom的特性及其对自动化测试的影响，并详细介绍如何利用cypress提供的`.shadow()`命令，结合正确的选择器策略，精准定位并操作shadow dom内部的元素，确保测试脚本的稳定性和可靠性。
理解Shadow DOM及其对Cypress测试的影响
在现代Web开发中，为了实现组件化和样式封装，Shadow DOM（影子DOM）被广泛应用。它允许开发者将一个DOM子树（即“影子树”）附加到一个元素上，并将其从主文档DOM中隔离出来。这意味着，影子树内部的元素在主文档DOM中是不可见的，也无法通过常规的CSS选择器直接访问。
当Cypress尝试使用cy.get()等命令定位页面元素时，它默认是在主文档DOM中进行查找。如果目标元素位于Shadow DOM内部，Cypress将无法找到它，从而导致测试超时错误，提示“Expected to find element: [selector], but never found it.”。这正是许多Cypress初学者在处理复杂Web应用时常遇到的困境。
使用Cypress的.shadow()命令访问Shadow DOM
为了解决这一问题，Cypress提供了专门的.shadow()命令，允许测试脚本“穿透”Shadow DOM的边界，访问其内部的元素。使用.shadow()命令的关键在于首先定位到Shadow DOM的宿主元素（Shadow Host），然后通过该宿主元素进入其影子树。
识别Shadow Host
在进行Cypress测试之前，你需要使用浏览器的开发者工具来识别目标元素所在的Shadow DOM宿主。通常，Shadow Host元素会在开发者工具中显示一个特殊的标识，例如一个带有“#shadow-root (open)”或“#shadow-root (closed)”的节点。你需要找到这个宿主元素，并为其编写一个Cypress选择器。
.shadow()命令的语法与应用
一旦确定了Shadow Host，就可以按照以下步骤使用.shadow()命令：
- 定位Shadow Host： 使用cy.get()命令定位到Shadow DOM的宿主元素。
- 进入Shadow DOM： 在定位到宿主元素后，链式调用.shadow()命令。这将把Cypress的上下文切换到该宿主元素的影子树内部。
- 查找内部元素： 在.shadow()命令之后，可以使用find()命令（或get()，但find()更常用，因为它是在当前链的子元素中查找）来定位影子树内部的元素。
示例代码：
假设我们要在https://whitelabel.sandbox.array.io/signup?platform=v3页面中查找一个位于Shadow DOM内部的firstName输入框。通过开发者工具检查发现，该输入框位于一个名为array-account-enroll的自定义元素所托管的Shadow DOM中。
describe('Verify form elements within Shadow DOM', () => {
it('Successfully finds and interacts with firstName input', function () {
// 访问目标页面
cy.visit('https://whitelabel.sandbox.array.io/signup?platform=v3');
// 1. 定位Shadow DOM的宿主元素 (Shadow Host)
// 在本例中，宿主元素是
cy.get('array-account-enroll')
// 2. 使用 .shadow() 命令进入Shadow DOM
.shadow()
// 3. 在Shadow DOM内部查找目标元素
.find('input[name="firstName"]')
// 4. 对找到的元素执行操作，例如输入文本
.type('John')
.should('have.value', 'John');
// 可以继续查找Shadow DOM内的其他元素
cy.get('array-account-enroll')
.shadow()
.find('input[name="lastName"]')
.type('Doe')
.should('have.value', 'Doe');
});
}); 在上面的代码中：
- cy.visit() 导航到测试页面。
- cy.get('array-account-enroll') 定位到承载Shadow DOM的自定义元素，即Shadow Host。
- .shadow() 命令将Cypress的查找范围限定在array-account-enroll元素的影子树内部。
- .find('input[name="firstName"]') 在影子树内部查找name属性为firstName的input元素。
通过这种方式，Cypress能够成功地定位并操作位于Shadow DOM内部的元素，从而避免了超时错误。
注意事项与最佳实践
嵌套Shadow DOM： 如果存在多层嵌套的Shadow DOM，你需要逐层使用.shadow()命令。例如，cy.get('host-element-1').shadow().find('host-element-2').shadow().find('target-element')。
Shadow DOM的开启/关闭状态： .shadow()命令主要用于访问开放（open）的Shadow DOM。对于封闭（closed）的Shadow DOM，通常无法直接通过自动化工具访问其内部元素，因为它旨在提供更强的封装性。在实际测试中，封闭的Shadow DOM相对较少见，或者通常会提供公共API进行交互。
-
全局配置includeShadowDom： Cypress也提供了一个全局配置选项includeShadowDom，可以在cypress.config.js（或cypress.json）中设置为true。当此选项为true时，cy.get()和cy.find()命令会自动尝试遍历Shadow DOM。然而，对于某些特定场景或更精细的控制，显式使用.shadow()仍然是推荐的做法，因为它提供了更明确的意图和更强的可读性。
// cypress.config.js const { defineConfig } = require('cypress'); module.exports = defineConfig({ e2e: { setupNodeEvents(on, config) { // implement node event listeners here }, includeShadowDom: true, // 启用全局Shadow DOM遍历 }, });当includeShadowDom: true时，原始的cy.get('input[name=firstName]')可能就能找到元素，但前提是该元素是Shadow DOM中唯一匹配的选择器，并且Cypress能正确识别其宿主。在复杂页面中，显式使用.shadow()通常更可靠。
选择器策略： 在Shadow DOM内部，元素的ID或类名可能与主文档DOM中的元素重复。因此，使用更具体的选择器（如input[name="firstName"]或带有特定属性的选择器）可以提高定位的准确性。
总结
Shadow DOM是现代Web开发中不可或缺的一部分，但它也给自动化测试带来了新的挑战。Cypress通过其强大的.shadow()命令，为我们提供了有效应对这些挑战的工具。理解Shadow DOM的工作原理，并熟练运用.shadow()命令，是编写健壮、可靠的Cypress测试脚本的关键。通过定位Shadow Host，进入影子树，然后查找内部元素，我们可以确保即使是最复杂的Web组件也能被自动化测试所覆盖。
