返回知识中心
入门

使用 WebDriver BiDi 事件构建稳定的浏览器自动化

了解 WebDriver BiDi 的会话、事件和传输边界,构建易维护的浏览器自动化。

BotBrowser Team

文档中心

想直接进入 入门 文档吗?

这篇文章属于知识中心的指南库。若你要步骤化配置、参考说明和持续更新,请直接进入对应 docs 分区。

从会话设置、双向传输和事件观察到有界断言的自动化流程

WebDriver BiDi 提供双向的标准通道。客户端发送命令时,浏览器可以发布事件,因此测试能够观察导航、日志、网络和浏览上下文,而不必把每次转换都写成猜测出来的延迟。事件只是浏览器观察到的证据,并不证明应用或服务接受了操作。BotBrowser 可以在受控且已授权的自动化上下文中作为被测浏览器,但不能让协议事件证明应用接受了某项操作。

可以把一次 BiDi 运行看成一个小系统:协商的会话、明确归属的传输、显式订阅,以及用户可见的断言。这些边界让故障分类更清晰。Playwright 入门指南介绍浏览器生命周期,浏览器交互验证介绍超出协议事件的证据。Playwright 中的自动化信号与一致性则讨论相关框架中的自动化信号。

这种区分对日常维护很重要。测试可能观察到导航、控制台消息或响应,而应用仍在决定要显示什么。驱动器返回成功也不等于服务器接受了数据。分别命名浏览器观察和应用结果,才能区分页面、驱动器、传输或服务的问题。

在同一个框架内选择协议时,可以对照 WebDriver、BiDi 和 CDP 的操作支持;仅凭客户端库名称,无法判断哪种连接提供所需命令或事件。

TL;DR

  • BiDi 提供长连接通道,浏览器不必等待新命令就能发布事件,测试因此可以直接得知浏览上下文已创建或出现了控制台条目,而不必轮询。
  • session.subscribe 配上 ["log.entryAdded"] 只接收控制台条目,再在同一组参数里加上 "contexts": ["<context id>"],投递范围就限定在那一个浏览上下文,而不是会话里的所有标签页。
  • 导航里程碑用 browsingContext.contextCreated 观察,请求观察用 network.beforeRequestSent,随后断言用户可见的状态,而不是断言事件本身。
  • 命令响应超时、事件等待超时和页面就绪超时是三件事;传输错误、浏览器崩溃和被拒绝的订阅也是三类不同的失败。
  • BotBrowser 为授权运行提供受控的隔离上下文和可重复的配置输入,而驱动、协议实现和服务器端结果仍属于所选的浏览器栈与应用。

目录

WebDriver BiDi 带来的变化

经典 WebDriver 面向请求:客户端发送命令并接收响应。BiDi 增加长连接,让浏览器无需等待新的客户端请求就能发送事件。W3C WebDriver BiDi 规范定义命令、事件和浏览上下文之间的关系。

事件不能替代断言。log.entryAdded 表示浏览器观察到了控制台条目,却不表示服务器保存了记录或流程成功。网络事件可以描述请求或响应类别,但页面仍可能显示错误。应把事件和代表预期结果的最小断言配对。

BiDi 将观察与实现细节分开。客户端订阅命名的事件类型,也可以限定浏览上下文。这样比收集所有消息再事后搜索更清晰。订阅本身不是隐私边界;授权测试仍需限制 URL、请求头、控制台参数和页面内容。只保留诊断所需的元数据。

协议仍在演进,不同浏览器和驱动器的支持可能不同。会话可以连接成功,却拒绝命令、缺少可选字段,或因功能不可用而关闭。记录协商后的能力和实现版本,并把不支持的协议行为与应用失败分开,避免形成误导性的超时。

协商一个有明确归属的会话

创建会话时,客户端声明期望并获得后续使用的标识符。把配置、配置文件、日志策略和请求能力放在同一处审查。请求某项能力不等于浏览器一定实现它。读取响应,保存接受的值,再依据实际结果做决定。

浏览上下文也是归属边界。顶层标签页、子框架和新窗口都可能有自己的标识符。创建或发现时保存这些标识符。拥有多个上下文时,把事件交给拥有该上下文的用例,忽略无关通知,避免后台页面满足活动页面的等待条件。

夹具应定义会话何时就绪、何时不可用。就绪可能包括握手成功、上下文已知和订阅确认。关闭时停止新操作,移除监听器,请求支持的会话结束操作,再关闭传输。即使命令之外的事件回调失败,也要在 finally 路径执行清理。

让会话设置可重复。每个工作进程使用自己的配置文件和产物路径,并记录浏览器、驱动器和协议版本。不要复用来源不明的会话。Selenium 双向功能文档介绍客户端模型,但测试数据、服务器清理和保留策略仍由团队负责。

订阅事件时保留上下文

订阅范围应和问题一样窄。如果测试等待页面错误,就按目标上下文过滤日志事件;如果等待导航,就保留上下文标识符、允许记录的 URL 类别和时间。尽早过滤可以减少回调工作,也避免捕获同一会话其他页面的活动。每个订阅都明确列出所需事件:session.subscribe 只请求 ["log.entryAdded"] 时收到的是控制台条目,而不是全部消息。{"id":1,"method":"session.subscribe","params":{"events":["log.entryAdded"]}} 这样的帧不带上下文过滤;在同一 params 中加入 "contexts": ["<context id>"],投递范围才限定在该上下文内。导航里程碑来自 browsingContext.contextCreated,请求观察来自 network.beforeRequestSent。

事件处理器应尽量没有副作用。它可以追加有界记录、完成命名等待或更新状态机,但不应点击、提交表单、修改应用存储或启动另一个会话。这样一个事件不会意外触发重复用户操作和重入竞争。CDP 输入合并:保持悬停交互的一致性介绍了 CDP 驱动交互中相关的输入时序行为。

事件顺序只有在协议和实现给出保证时才有意义。请求事件可能早于结果显示,日志事件也可能晚于触发它的命令返回。先用事件标记观察,再等待用户可见状态。如果有多个合法结果,就明确列出并分类第一个命中的结果。

关闭过程中出现迟到事件很正常。释放监听器前把会话标记为正在关闭,并丢弃终止状态之后的消息。限制队列大小,发生溢出时返回诊断信息。订阅被拒绝时记录事件名称,只有在批准的回退方案存在时才继续,否则报告能力不支持。

把传输当作生命周期

BiDi 传输是承载命令、响应和主动事件的长连接。客户端需要用请求标识符关联响应,并把事件分发给订阅者。把关联逻辑留在协议库中;测试用例应接收命名结果或事件记录,而不是在每个用例里解析原始帧。

连接可能在命令等待期间或事件发送期间断开。区分正常关闭、传输错误、浏览器崩溃和应用超时。重连并不总是安全,重复提交可能产生重复操作。只有在明确策略下重试幂等的准备操作;无法证明旧会话状态时,创建新的归属会话。

应制定队列背压策略。大量控制台或网络事件可能挤掉真正需要的记录。在订阅时过滤,限制保留数量,并在结果中标明丢弃记录。写入持久化产物前先脱敏,尤其注意带查询参数的 URL、请求头和控制台参数。协议提供数据,但不决定团队能保留什么。

传输超时必须指出停止推进的层级。命令响应、事件等待和页面就绪是不同问题。错误记录应包含命令或事件名、允许的上下文、连接状态和最后观察到的类别。不要把所有断开都变成笼统的页面超时。

构建稳定的事件驱动断言

从明确的结果和小型状态模型开始。授权的结账流程可以包括合成购物车、提交交接、可见订单状态和有界失败记录。BiDi 可以观察导航或响应,但稳定断言应指向用户能读到的状态。先命名结果,能避免测试退化为信号集合。

每次转换使用一个等待,并给它语义化的名称。contextCreated 等待预期上下文出现,另一个等待确认标题。谓词只读状态,截止时间放在环境配置中。改变预算时,仍要在报告中保留条件名称,避免慢环境掩盖应用契约变化。

失败产物应保留第一个缺失条件。记录接受的能力、动作、事件类别、上下文归属,以及浏览器和驱动器版本,并对观察内容脱敏。批准的合成夹具可以保留截图或片段,但不必因为 BiDi 能观察页面就导出完整的认证页面。Puppeteer BrowserContext 生命周期指南也强调状态和清理归属。

要刻意演练负路径。在合成夹具中撤掉一个就绪信号,确认测试报告命名该信号的有界超时。模拟被拒绝的订阅或关闭的传输,验证结果被归类为环境或能力问题,而不是成功流程。演练应使用合成状态,不依赖真实账户或私密数据。

使用 BotBrowser 时保持边界清晰

BotBrowser 可以为观察 WebDriver BiDi 的授权自动化运行提供受控的隔离浏览器上下文和可重复配置文件输入,帮助团队在相同会话输入下比较事件行为并明确配置文件归属。BotBrowser 不实现 WebDriver BiDi 协议,不会补充未支持的命令或事件,也不保证驱动器、浏览器、传输和应用之间的兼容性。协议实现、事件支持和服务器结果仍由所选浏览器栈与应用负责。

隔离有助于分开合成存储和会话状态,但它本身并不赋予测试授权。应定义运行可以访问的页面、数据和事件字段,让配置文件和产物由工作进程负责,并通过支持的生命周期关闭会话。可重复的起点提升复现性,却不能保证事件到达或服务接受请求。

使用 BotBrowser 配合 BiDi 驱动器时,记录实际的浏览器与驱动器组合及接受的会话能力。如果命令或事件缺失,应把兼容性边界归因于拒绝它的组件。不要把配置文件隔离当作协议合规,也不要把可重复配置文件当作服务器事务完成的证据。产品验证和协议一致性应分开。

BiDi 团队的检查清单

运行前确认会话、配置文件、传输、请求能力和事件订阅的归属。为每条断言选择拥有它的上下文,规定哪些数据可以进入日志。先写清用户可见的完成状态,再列出支持该状态的协议事件。这样夹具可以被审查,而不是成为黑盒服务。

运行期间关联每个命令响应,并通过带上下文的处理器路由事件。处理器保持有界且无副作用。分别报告不支持的命令、断开、队列溢出和页面超时。如果策略允许重试,说明为何安全;无法证明旧状态时创建新的归属会话。不要让事件回调悄悄重复用户操作。

运行之后,即使断言失败也关闭监听器和会话。只保留批准的合成证据,包括第一个缺失条件和接受的能力。按结果和兼容组合比较,而不是比较偶然的事件时间。浏览器或驱动器变化后,先重新检查能力和事件,再调整页面等待预算。

稳定的测试契约很简单:BiDi 传递命令和观察结果,夹具管理会话与传输,应用定义完成的含义。职责分离后,事件能让故障更精确,却不会被误当成业务保证。

团队可以把这份契约放在每条流程旁边:启动命令、辅助观察的事件、归属上下文、用户能识别的断言,以及事件不可用时的回退。无需保留原始协议帧,但要有足够上下文区分页面回归、能力缺失和连接丢失。

记录中也要写明清理责任。子上下文有其拥有者,订阅有移除时机,产物有合成数据边界。这样迟到事件不会流入下一条测试,失败配置文件也不会影响后续运行。BiDi 提供观察机制,夹具和应用拥有者制定使用策略。

来源

实践结论

第一次运行之前先把四个名字写下来:启动这一步的命令、观察它的事件、拥有这次观察的浏览上下文,以及用户能认出的那条断言。四者固定之后,结果变化就能清楚归类为页面回归、能力不支持或连接丢失,后来调大超时也不会悄悄改变"完成"的含义。

落到操作上,就是每条流程只用一条订阅,例如 session.subscribe 加 ["log.entryAdded"] 并带上明确的 "contexts" 列表;处理器只读,只往有界队列追加或唤醒一个具名等待;结束前在 finally 里先移除监听再关闭会话。负面路径也要演练:在合成 fixture 上撤掉就绪信号,确认报告把它写成有界超时,并确认被拒绝的订阅被记为能力问题而不是流程通过。

下一次升级驱动或浏览器之前,重跑能力与事件检查,并把接受的 capabilities 与浏览器、驱动版本一起记录。比较结果时按结局和兼容元组对照,而不是按偶然的事件时序,并保持同一份 fixture,让比较本身站得住。

#WebDriver BiDi#浏览器自动化#事件#会话#测试

本文属于指南: 浏览器自动化入门:首次运行地图

在 BotBrowser 里跑一遍同样的检查

加载 profile,让刚读到的这些信号在浏览器内部保持一致,并在正式上线前先在自己的机器上确认结果。