本文详细阐述了在 cypress 测试中，当目标元素位于 shadow dom 内部时，标准选择器失效的原因及解决方案。教程将指导读者如何识别 shadow host 并利用 cypress 的 `.shadow()` 命令，有效定位并与 shadow dom 中的表单元素进行交互，确保测试的准确性和稳定性。
在现代 Web 开发中，组件化和封装性变得越来越重要。Shadow DOM 作为 Web Components 技术栈的一部分，提供了一种强大的方式来封装组件的结构、样式和行为，使其与文档的其他部分完全隔离。然而，这种封装性也给自动化测试工具带来了挑战，尤其是在使用 Cypress 这类工具进行元素定位时。
理解 Shadow DOM 及其对 Cypress 的影响
Shadow DOM 允许浏览器将一个 DOM 子树（称为 Shadow Tree）附加到一个常规 DOM 元素（称为 Shadow Host）上。这个 Shadow Tree 是独立于主文档 DOM 的，其内部的元素默认不会被主文档的 CSS 或 JavaScript 直接访问。对于 Cypress 而言，这意味着标准的 cy.get() 命令在尝试定位 Shadow DOM 内部的元素时会失败，因为它只能在主文档 DOM 中进行查找。
当 Cypress 尝试使用 cy.get('input[name=firstName]') 这样的选择器去定位一个位于 Shadow DOM 内部的输入框时，如果该输入框不直接存在于主文档 DOM 中，Cypress 将无法找到它，并最终抛出超时错误，提示“Expected to find element: input[name=firstName], but never found it.”。
解决方案：使用 Cypress 的 .shadow() 命令
Cypress 提供了专门的 .shadow() 命令来解决 Shadow DOM 的元素定位问题。.shadow() 命令允许您穿透 Shadow DOM 的边界，进入 Shadow Tree 内部进行元素操作。
.shadow() 命令的工作原理
要成功使用 .shadow() 命令，关键在于两步：
- 定位 Shadow Host： 首先，您需要使用常规的 Cypress 选择器定位到承载 Shadow DOM 的宿主元素（Shadow Host）。这个 Shadow Host 必须是主文档 DOM 中的一个可见元素。
- 进入 Shadow DOM 并定位内部元素： 一旦定位到 Shadow Host，您可以链式调用 .shadow() 命令。此命令会改变 Cypress 的上下文，使其能够在 Shadow Tree 内部进行操作。之后，您可以使用 .find() 命令（而不是 cy.get()）来定位 Shadow DOM 内部的元素。
示例代码
假设我们有一个 Web 页面，其中包含一个自定义组件 array-account-enroll，而 firstName 输入框位于其 Shadow DOM 内部。以下是使用 .shadow() 命令进行定位的 Cypress 测试代码：
describe('Verify identity data within Shadow DOM', () => {
it('Successfully finds and interacts with form elements in Shadow DOM', function () {
// 访问目标页面
cy.visit('https://whitelabel.sandbox.array.io/signup?platform=v3');
// 1. 定位 Shadow Host 元素
// 'array-account-enroll' 是承载 Shadow DOM 的自定义元素标签
cy.get('array-account-enroll')
// 2. 使用 .shadow() 命令进入 Shadow DOM 内部
.shadow()
// 3. 在 Shadow DOM 内部使用 .find() 定位目标元素
.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');
// 如果有按钮也在 Shadow DOM 内部，同样可以定位并点击
// cy.get('array-account-enroll').shadow().find('button[type="submit"]').click();
});
});在上述代码中：
- cy.get('array-account-enroll') 定位了 Shadow Host 元素。
- .shadow() 命令将 Cypress 的查询范围切换到 array-account-enroll 元素的 Shadow Tree 内部。
- .find('input[name="firstName"]') 则在 Shadow Tree 内部查找名为 firstName 的输入框。
注意事项与最佳实践
-
识别 Shadow Host： 正确识别 Shadow Host 是使用 .shadow() 的第一步也是最关键的一步。通常，Shadow Host 是一个自定义元素（如
）或具有 shadowRoot 属性的常规元素。您可以使用浏览器的开发者工具来检查元素结构，确认哪个元素是 Shadow Host。 - .shadow() 只能在 Shadow Host 上调用： 确保您在 .shadow() 命令之前定位的元素确实是一个 Shadow Host。如果在非 Shadow Host 元素上调用 .shadow()，Cypress 将会报错。
- 链式调用 find()： 一旦进入 Shadow DOM，您应该使用 .find() 命令来定位内部元素，而不是 cy.get()。cy.get() 总是从根 DOM 开始查询，而 .find() 是从当前主题（即 Shadow Root）开始查询。
- 多次进入 Shadow DOM： 如果页面中有多个独立的 Shadow DOM 实例，或者您需要操作不同 Shadow DOM 中的元素，您可能需要多次重复 cy.get('shadow-host').shadow().find('element') 的模式。
- 调试技巧： 在 Cypress 测试运行时，打开浏览器开发者工具，检查元素的 DOM 结构。带有 #shadow-root 标记的元素就是 Shadow Host。展开它，您就能看到 Shadow DOM 内部的元素结构。这对于编写正确的选择器非常有帮助。
总结
处理 Shadow DOM 是 Cypress 高级测试场景中常见的挑战。通过理解 Shadow DOM 的封装特性以及 Cypress 提供的 .shadow() 命令，测试工程师可以有效地穿透 Shadow DOM 边界，精准定位并与内部元素进行交互。遵循先定位 Shadow Host、再使用 .shadow() 进入，最后用 .find() 定位内部元素的策略，将确保您的 Cypress 测试在面对复杂 Web 组件时依然保持高效和稳定。
