协议集成

相关源文件

• packages/app/src/studio/studio-app-types.ts
• packages/server/lib/browsers/browser-cri-client.ts
• packages/server/lib/browsers/cdp-connection.ts
• packages/server/lib/browsers/cdp_automation.ts
• packages/server/lib/browsers/chrome.ts
• packages/server/lib/browsers/cri-client.ts
• packages/server/lib/browsers/cri-errors.ts
• packages/server/lib/browsers/debug-cdp-connection.ts
• packages/server/lib/browsers/electron.ts
• packages/server/lib/browsers/firefox-util.ts
• packages/server/lib/browsers/firefox.ts
• packages/server/lib/browsers/index.ts
• packages/server/lib/browsers/types.ts
• packages/server/lib/browsers/utils.ts
• packages/server/lib/browsers/webkit-automation.ts
• packages/server/lib/browsers/webkit.ts
• packages/server/lib/cloud/protocol.ts
• packages/server/lib/cloud/studio.ts
• packages/server/lib/project-base.ts
• packages/server/lib/project_utils.ts
• packages/server/lib/socket-base.ts
• packages/server/test/integration/cdp_spec.ts
• packages/server/test/support/fixtures/cloud/protocol/test-protocol.ts
• packages/server/test/support/fixtures/cloud/studio/test-studio.ts
• packages/server/test/unit/browsers/browser-cri-client_spec.ts
• packages/server/test/unit/browsers/browsers_spec.js
• packages/server/test/unit/browsers/cdp-connection_spec.ts
• packages/server/test/unit/browsers/cdp_automation_spec.ts
• packages/server/test/unit/browsers/chrome_spec.js
• packages/server/test/unit/browsers/cri-client_spec.ts
• packages/server/test/unit/browsers/electron_spec.js
• packages/server/test/unit/browsers/firefox_spec.ts
• packages/server/test/unit/cloud/protocol_spec.ts
• packages/server/test/unit/cloud/studio_spec.ts
• packages/server/test/unit/open_project_spec.js
• packages/server/test/unit/project_spec.js
• packages/server/test/unit/project_utils_spec.ts
• packages/server/test/unit/socket_spec.js
• packages/types/package.json
• packages/types/src/protocol.ts
• packages/types/src/studio/studio-server-types.ts

此页面文档记录了 Cypress 如何通过标准化协议与浏览器通信，以实现浏览器自动化、网络拦截和事件处理。它解释了 Chrome DevTools Protocol (CDP) 和 WebDriver BiDi 如何集成到 Cypress 的架构中以支持不同的浏览器。

有关常规浏览器自动化的信息，请参阅 浏览器自动化。

概述

Cypress 使用不同的协议与浏览器通信

1. Chrome DevTools Protocol (CDP) - 用于 Chrome、Chromium 浏览器和 Electron
2. WebDriver BiDi - 用于较新的 Firefox 版本 (v135+)
3. 遗留 CDP 支持 - 用于较旧的 Firefox 版本

这些协议使 Cypress 能够

• 控制浏览器行为（导航、执行上下文）
• 拦截和修改网络请求
• 捕获屏幕截图和视频
• 监控和响应浏览器事件
• 访问和修改浏览器状态（Cookie、本地存储）

来源

• packages/server/lib/cloud/protocol.ts1-519
• packages/server/lib/browsers/cdp_automation.ts1-166
• packages/server/lib/browsers/firefox.ts412-436
• packages/server/lib/automation.ts

协议管理器

ProtocolManager 类是 Cypress 中协议操作的中央协调器。它提供了一个统一的接口，用于与浏览器进行交互，而不管其具体的协议实现。

职责

• 初始化协议脚本
• 连接到浏览器
• 管理协议生命周期（设置、拆卸）
• 处理协议错误
• 协调测试事件与协议操作

来源

• packages/server/lib/cloud/protocol.ts37-507
• packages/types/src/protocol.ts129-142

协议初始化流程

来源

• packages/server/lib/project-base.ts143-198
• packages/server/lib/cloud/protocol.ts69-125

浏览器协议客户端

Cypress 使用不同的客户端实现来通过各自的协议与浏览器通信。

Chrome Remote Interface (CRI) 客户端

对于 Chrome、Chromium 浏览器和 Electron，Cypress 使用两个主要的客户端类

1. CriClient - 用于 CDP 通信的基类客户端
2. BrowserCriClient - 特定于浏览器的 CDP 客户端，用于管理选项卡和目标

来源

• packages/server/lib/browsers/cri-client.ts35-85
• packages/server/lib/browsers/cri-client.ts101-467
• packages/server/lib/browsers/browser-cri-client.ts73-343

Firefox 协议支持

Firefox 同时支持 WebDriver BiDi（用于较新版本）和 CDP（用于较旧版本）。

来源

• packages/server/lib/browsers/firefox.ts412-436
• packages/server/lib/browsers/firefox.ts345-352

Firefox 版本检测逻辑

来源

• packages/server/lib/browsers/firefox.ts412-419

协议通信流程

命令执行流程

此图说明了命令如何从 Cypress 流经协议层到达浏览器

来源

• packages/server/lib/socket-base.ts283-290
• packages/server/lib/browsers/cdp_automation.ts248-261

事件处理流程

此图显示了 Cypress 如何捕获和处理浏览器事件

来源

• packages/server/lib/browsers/cdp_automation.ts262-333
• packages/server/lib/socket-base.ts495-507

浏览器特定协议实现

Chrome/Chromium/Electron (CDP)

Chrome DevTools Protocol (CDP) 实现由 CdpAutomation 类处理，该类提供以下主要功能

1. 网络请求拦截和修改
2. Cookie 管理
3. 浏览器导航和控制
4. 屏幕截图和视频捕获
5. 事件监控

来源

• packages/server/lib/browsers/cdp_automation.ts206-212
• packages/server/lib/browsers/chrome.ts487-511

Firefox (WebDriver BiDi 和 CDP)

Firefox 支持两种协议

1. WebDriver BiDi (用于 Firefox v135+)
2. CDP (用于较旧的 Firefox 版本)

Firefox 协议选择

来源

• packages/server/lib/browsers/firefox.ts421-437
• packages/server/lib/browsers/firefox-util.ts13-28

协议在项目生命周期中的集成

协议管理器通过 ProjectBase 类集成到 Cypress 项目生命周期中，该类负责管理测试的初始化、配置和执行。

来源

• packages/server/lib/project-base.ts153-198
• packages/server/lib/project-base.ts430-477
• packages/server/lib/cloud/protocol.ts460-475

错误处理

协议管理器包含强大的错误处理功能，可以捕获和报告协议相关错误，而不会导致 Cypress 崩溃。

来源

• packages/server/lib/cloud/protocol.ts481-498
• packages/server/lib/cloud/protocol.ts460-475

协议配置

Cypress 提供了协议行为的配置选项，包括

1. 网络处理选项
2. Firefox 的协议选择
3. 协议特定偏好设置

来源

• packages/server/lib/browsers/firefox.ts347-352
• packages/server/lib/browsers/chrome.ts209-211

协议与浏览器自动化

理解 Cypress 中协议集成与浏览器自动化的区别非常重要

协议集成	浏览器自动化
使用标准化协议（CDP、WebDriver BiDi）与浏览器进行低级通信	用于控制浏览器行为的更高级抽象
处理原始协议命令和事件	为测试交互提供用户友好的 API
浏览器特定协议实现	跨浏览器的统一自动化接口
由 ProtocolManager 管理	由 Automation 类管理

来源

• packages/server/lib/project-base.ts8-33
• packages/server/lib/automation.ts

未来协议支持

随着浏览器协议的不断发展，Cypress 被设计为通过以下方式进行适应

1. 在通用接口后面抽象特定于协议的代码
2. 提供特定于浏览器的协议实现
3. 使用版本检测来选择合适的协议

Firefox 从 CDP 过渡到 WebDriver BiDi 证明了这种方法

来源

• packages/server/lib/browsers/firefox.ts421-437
• packages/server/test/unit/browsers/firefox_spec.ts147-167