16. Shadow DOM 与复杂 DOM 定位技巧

Shadow DOM 是什么

Shadow DOM（影子 DOM）是 Web Component（Web 组件）的核心机制。它让一个元素挂上一份「内部独立文档」，跟外部的样式和结构互相隔离。自定义组件 <x-details> 就常这么干：

<x-details role=button aria-expanded=true aria-controls=inner-details>
  <div>Title</div>
  #shadow-root
    <div id=inner-details>Details</div>
</x-details>

#shadow-root 下面那份，就是 Shadow DOM。普通 CSS 选择器默认进不去。

Playwright 默认能穿透

好消息：Playwright 的所有定位器默认都能穿透开放的 Shadow Root。你不用写特殊语法，像平常一样找就行。

点内部的 “Details”：

await page.getByText('Details').click();

点外层宿主元素 <x-details>：

await page.locator('x-details', { hasText: 'Details' }).click();

断言它含 “Details” 文字：

await expect(page.locator('x-details')).toContainText('Details');

两个例外要记住

穿透不是万能的，有两条硬边界：

1. XPath 不穿透 Shadow Root。 用 xpath= 写的定位器进不去影子内部。
2. Closed 模式的影子根不支持。 元素用 attachShadow({ mode: 'closed' }) 创建时，外部脚本根本拿不到它的内部，Playwright 也没辙。

对比一下就清楚了：

// ✅ 开放 Shadow Root，正常写法就能进
await page.getByText('Details').click();

// ❌ XPath 停在宿主元素外面，找不到影子里的节点
await page.locator('xpath=//div[@id="inner-details"]').click();

至于 closed 模式，页面里长这样：

// 页面自己的代码，测试无法干预
element.attachShadow({ mode: 'closed' });

复杂 DOM 下定位不稳定的排查

页面一复杂，定位就爱出怪问题。按这几点逐一排查：

1. 是不是匹配到多个

严格模式会在「匹配多个」时报错。别急着 .first() 硬压，先看页面到底有几处同名元素。优先用文字、test id 让表达式唯一。

2. 是不是在 iframe 里

第 15 章讲过，Frame（框架）内外是隔离的。元素躺在 iframe 里，你却用主框架去找，必然扑空。先用 frameLocator 切进去。

3. 是不是在 Shadow DOM 里

在 Shadow 内部却用 XPath，会穿透失败。换成 role/text/test id 这类定位器。

4. 是不是时机没到

元素晚出现、晚可点。靠自动等待通常能解决；若仍超时，检查它是否真的渲染了、是否被弹层遮住（Receives Events 检查失败）。

5. 是不是定位器绑死了结构

一长串 CSS 或 XPath 路径最脆。回到「用户视角」原则：能用 role 用 role，能用 test id 用 test id。

小结

Playwright 默认能穿透开放的 Shadow Root，定位影子内部的元素跟平时写法一模一样。唯独 XPath 不穿透，closed 模式不支持。

复杂 DOM 下定位不稳，按「多匹配 → iframe → Shadow → 时机 → 结构绑定」这五点依次排查，基本能定位到根因。

到这儿，定位器这一块就讲完了。第 9 到第 16 章，Playwright 找元素的主力手段和兜底手段你都拿到手了。