Playwright iframe 的那些坑

写了一段时间 Playwright 测试后，有一点非常清楚：iframe 是端到端测试中的终极麻烦制造者。

核心结论

document.querySelectorAll('#elementId') 和 page.locator('#elementId') 是完全不同的东西。

1. 典型问题

document.querySelectorAll('#elementId') ❌ 找不到page.locator('#elementId') ✅ 能找到

这是完全正常的行为——你的代码没有写错。

2. 它们到底有什么区别？（关键）

① document.querySelectorAll(...)

• 运行在浏览器内部
• 只能找到已经在 DOM 中渲染的元素
• 完全不等待
• 无法找到动态加载、稍后渲染、或 iframe 内的元素
• 无法找到还未出现的元素
• 本质：原生 JS 的一次性即时查询

② page.locator(...)

• Playwright 内置的智能定位器
• 自动等待元素存在、可见、可交互
• 有自动重试机制
• 能找到动态加载、懒加载、异步渲染的元素
• 原生支持 Shadow DOM、frames、动态内容
• 本质：智能定位 + 自动等待 + 自动重试 + 自动检查

3. 为什么 document.querySelectorAll 找不到元素？

最常见的 4 个原因：

原因 1：元素尚未渲染（异步 / API 请求 / 懒加载）

• 原生 JS 查询在元素创建之前就立即执行了
• Playwright locator 会等待它出现

原因 2：元素在 Shadow DOM 内

• document.querySelector无法访问 Shadow DOM
• locator自动支持 Shadow DOM

原因 3：元素在 iframe 内

• 原生 API 需要手动切换到 iframe 内部
• Locator 可以跨 frame 定位

原因 4：你用了 ID 选择器 #id，但页面上有重复 ID

• querySelectorAll 可能行为异常
• Playwright 更健壮

4. 最重要的知识（必读）

✅ page.locator() 是 Playwright 中唯一推荐、正确的用法

❌ 避免在测试中直接使用 document.querySelector

因为：

• Playwright 内置了等待、自动重试、防抖保护
• 原生 JS API 完全没有等待逻辑——瞬间找不到就失败

5. 正确的写法

正确（稳定可靠）

// 自动等待 + 自动重试 ✅const count = await page.locator('#elementId').count();

错误（经常失败）

// 不等待，不重试 ❌const elements = await page.evaluate(() => {returndocument.querySelectorAll('#elementId'); // 一次性即时查找});

6. 一句话总结

document.querySelectorAll 是”单次快照查找” page.locator 是”等到它出现为止的查找”