为什么 Playwright 会超时？

Scrapeless Agent Browser 为使用 Playwright 的工作流提供托管的浏览器运行环境，用于导航页面和检查渲染后的内容。

当某个操作或其外层任务未能在适用的时间预算内满足所需条件时，Playwright 就会超时。未完成的条件可能是导航、可操作元素、断言，或者整个测试。在修改超时设置前先阅读失败的操作和调用日志。

从停止等待的那个操作开始

Playwright 超时诊断从错误中点名的操作开始。导航失败和断言失败可以发生在同一个 URL 上，但描述的是不同的未完成工作。保留错误信息、源码位置、调用日志以及最终页面 URL，这样调查才能从正确的条件出发。

先判断你是在将 Playwright 作为库使用，还是通过 Playwright Test 使用。测试运行器会添加外层的时间预算和夹具行为，这与独立浏览器脚本并不相同。当外层测试或作业截止时间仍然更早结束运行时，对单个操作的更改可能不会产生可见效果。

记录失败环境中实际生效的配置。本地覆盖、项目级配置或特定环境包装器都可能改变有效超时。避免直接从不相关示例中拷贝一个默认值就假定它支配了这次故障。观察到的错误与当时生效的配置是更有力的证据。

导航等待与数据就绪是不同的

导航完成关心的是页面生命周期，而数据就绪关心的是工作流所需的应用状态。文档可能在产品网格填充之前就到达。页面也可能在后台请求继续进行时就已经显示出所需数据。选择与所需内容或操作相匹配的就绪条件。

该 Navigation Timing 规范 将连接、响应传递和文档处理等阶段区分开来。这些阶段有助于解释为什么“页面很慢”这一诊断过于笼统。检查浏览器是否仍在等待文档、脚本是否失败，或者后续应用请求是否从未产生预期状态。

在细化导航设置前检查最终 URL 和页面标题。登录重定向、同意页面或错误文档都可能正常完成其自身的生命周期。对该页面上的产品表格等待更久也不会让表格出现。先验证目的地，然后再验证业务条件。

已有元素仍可能未通过可操作性检查

Playwright 的操作会等待该操作所需的检查。 Playwright 可操作性模型 解释了点击需要一个可见、稳定、已启用且能够接收事件的合适目标。因此，即使文档中出现了匹配元素，遮罩层、动画或禁用控件也可以解释一次超时。

阅读调用日志以找到仍未满足的具体条件。如果是其他元素拦截了指针事件，就检查遮罩层以及预期用户流程。如果控件被禁用，就找出本应使其启用的应用状态。如果目标在动画过程中移动，就确定动画是否应该在操作前完成。

强制执行某个操作可以跳过部分检查，却并不能让应用真正就绪。这可能会把清晰的超时变成工作流后续更难解释的失败。在使用改变操作默认安全检查的选项之前，先纠正页面状态或交互顺序。

在正确的文档中定位正确的元素

定位器应当描述实际页面及其 frame 中的目标元素。从早期模板复制的选择器在重构后可能不再匹配任何元素，而过于宽泛的文本匹配可能标识出多个控件。请在失败快照中验证目标，而不是在另一次成功的浏览器访问中验证。

显式检查 frame。嵌入文档中可见的元素不一定属于顶层文档的查询上下文。如果脚本仍在原页面上运行，弹窗也会造成类似问题。屏幕上某处可见按钮的存在，并不能证明当前页面对象可以访问它。

区分歧义与缺失。解析为多个元素的严格定位器会产生一个需要收窄定位器而不是增加等待时间的错误。解析为零个元素的定位器则需要检查页面状态、模板和文档上下文。在故障排查记录中保留这些区别。

理解围绕某个操作的预算

一个操作实际可用的时间取决于它自身的限制以及任何包裹它的截止时间。测试在到达失败代码行之前，可能会将大量预算花在创建夹具或准备数据上。仅仅增加该操作的限额，无法创造出超过外层测试剩余配额的时间。

在度量时，将设置、导航、交互、断言和清理分开。冗长的设置阶段会导致原本正常的操作在总测试预算用尽时，看起来像是失败的那一步。相反，即使测试仍有剩余时间，某个断言本身可能只有更短的独立预算。

让截止时间保持有界且有明确目的。根据成功和失败运行的证据，判断某个操作究竟是真正变慢了，还是卡在一个不可能满足的条件上。过于宽松的全局超时时间，会让错误的定位器和未满足的前置条件更难被发现，同时又无法解决它们的根本原因。

使用 Trace 重建失败时的状态

Trace 可以帮助重建超时前浏览器展示的内容以及脚本发起的请求。检查操作时间线、DOM 快照、控制台消息和相关网络响应。将失败时的快照，与代码假定的状态进行比较，尤其是针对异步更新和页面间跳转。

在手动操作待测应用时，把浏览器端的证据和服务端请求标识符联系起来。 W3C Trace Context 定义了在服务之间传播 Trace 标识符的标准。标识符支持相关性分析，但浏览器 Trace 与分布式服务端 Trace 仍然是不同的工件，覆盖范围也不同。

将 Trace 文件视为可能敏感的记录进行保护。它们可能包含页面文本、请求细节以及已认证状态。只保留调试所需的内容，并通过批准的渠道共享。一个有用的缺陷报告可以描述失败条件，而无需附上不受限制的生产会话。

为什么 CI 会失败而本地笔记本却能通过

持续集成会暴露本地环境中被隐藏的假设。资源争用、不同的视口尺寸、缺失的测试数据、网络访问以及配置差异，都会改变期望状态出现的时机。重现相关条件，而不是将每一次 CI 超时都归咎为基础设施缺陷。

比较浏览器版本、视口、权限、区域设置以及认证配置。自适应布局可能在不同宽度下把桌面端控件隐藏到菜单中。区域设置的变化会改变定位器依赖的可见文本。不完整的夹具甚至会在高性能机器上，让一个按钮一直保持禁用状态。

同时也要衡量资源压力和任务调度。多个浏览器任务可能争夺 CPU 和内存，共享的测试账号会相互修改数据。在扩展所有超时时间之前，先隔离状态并限定并行工作量。目标是在受支持的环境下，实现可确定的就绪条件。

远程浏览器会话增加了单独的边界

Agent Browser 提供远程浏览器运行时，而你的 Playwright 进程仍然负责管理自动化逻辑。连接建立、会话生命周期、导航以及应用就绪都是彼此独立的边界。已连接的远程会话并不能证明目标站点已经加载了期望数据。

使用 Agent Browser 故障排查 来识别运行时连接问题，然后再检查实际目标页面是否出现浏览器层面的失败。要把服务连接错误与目标访问被拒区分开来。 Node.js browser workflow 为浏览器控制提供相关背景，但不会把针对特定目标的时序选择，作为通用默认值。

将当前 Scrapeless pricing 与有用且已完成的任务进行对比评估。对一个并不存在的选择器进行长时间等待，会占用会话时间而不提升采集效果。为错误目标或访问被拒页面定义及早的检查，让工作流能在耗尽全部预算之前，准确归类结果。

聚焦的修复步骤

聚焦的修复会改变证据所指出的那个条件。从失败的操作和最终页面入手。确认定位器的文档上下文，检查所需的可操作性状态，然后再查看相关的应用请求。只有在完成这些检查之后，由度量得出的延迟问题才应当导致更窄范围的截止时间调整。

在导致失败的同样条件下验证修复后的工作流。既要确认操作完成，又要确认产生了预期结果。如果点击成功返回，但表单从未提交或下一页包含错误，这仍然不算成功。用用户任务或采集到的数据来定义成功。

结论

当你能说清缺失的条件是什么时，Playwright 的超时问题就变得可控。检查实际页面、定位器的作用域、可操作性日志以及外层的截止时间。优先修复未满足的前置条件或错误假设，然后再基于证据为真正的工作分配时间预算。