浏览器自动化

相关源文件

• 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/test/integration/cdp_spec.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

此页面记录了 Cypress 中的浏览器自动化子系统，该子系统负责在测试执行期间启动、连接到和控制浏览器实例。浏览器自动化系统利用每个浏览器原生的能力，通过标准化的接口，提供跨浏览器兼容性。

有关 CDP 和 WebDriver BiDi 等特定协议集成的更多信息，请参阅协议集成。

概述

浏览器自动化系统是连接 Cypress 的测试基础设施与实际浏览器进程的关键组件。它负责

1. 使用特定配置启动浏览器
2. 建立和维护与浏览器的通信
3. 将 Cypress 命令转换为特定于浏览器的操作
4. 管理浏览器配置文件、扩展和首选项
5. 处理浏览器崩溃和重新连接场景
6. 支持各种浏览器类型（Chrome、Firefox、Electron、WebKit）

来源

• packages/server/lib/browsers/chrome.ts1-633
• packages/server/lib/browsers/firefox.ts1-813
• packages/server/lib/browsers/electron.ts1-627
• packages/server/lib/browsers/webkit.ts1-95

浏览器启动流程

浏览器启动流程负责配置、启动和连接浏览器。虽然每种浏览器都有特定的要求，但它们都遵循一个通用模式

启动流程的关键组件包括

1. 浏览器特定配置

每种浏览器都需要特定的配置选项

• Chrome/Chromium：命令行标志、Chrome 首选项、扩展加载
• Firefox：配置文件首选项、Firefox 特定参数、WebSocket 调试器端口
• Electron：BrowserWindow 选项、与 Electron 应用架构的集成
• WebKit：Playwright 特定配置

2. 配置文件和缓存管理

系统为每次测试运行创建隔离的浏览器配置文件

3. 扩展安装

对于 Chrome、Firefox 和 Electron，Cypress 会安装其扩展以启用高级功能

4. 浏览器进程启动

实际的浏览器启动因浏览器类型而异

• Chrome/Firefox：使用 @packages/launcher 启动浏览器进程
• Electron：在当前 Electron 进程中创建 BrowserWindow
• WebKit：使用 Playwright 启动和控制 WebKit

5. 浏览器连接

启动后，Cypress 会建立与浏览器的连接

• Chrome/Electron/旧版 Firefox：通过 BrowserCriClient 创建 CDP 连接
• 现代 Firefox (≥ 135)：通过 WebDriver BiDi 连接
• WebKit：通过 Playwright 的 API 连接

来源

• packages/server/lib/browsers/chrome.ts516-627
• packages/server/lib/browsers/firefox.ts452-805
• packages/server/lib/browsers/electron.ts154-392
• packages/server/lib/browsers/utils.ts78-167

浏览器通信

CRI 客户端系统

对于 Chrome、Electron 和旧版 Firefox，Cypress 使用 Chrome Remote Interface (CRI) 客户端系统，该系统包含两个主要类

1. CriClient：处理基本的 CDP 通信
2. BrowserCriClient：管理浏览器内的多个目标（标签页）

CRI 客户端系统提供

• 命令执行：向浏览器发送命令并接收响应
• 重新连接处理：如果连接断开，会自动重新连接
• 命令排队：确保命令按顺序运行并在重新连接时重试
• 事件分发：将浏览器事件转发给 Cypress

来源

• packages/server/lib/browsers/cri-client.ts101-486
• packages/server/lib/browsers/browser-cri-client.ts179-693

CDP 自动化

CdpAutomation 类在 Cypress 命令和 CDP 命令之间进行转换

CDP 自动化处理

• Cookie 管理：获取、设置和清除 cookie
• 截图捕获：捕获页面截图
• 网络操作：清除缓存和数据
• 下载管理：跟踪和管理文件下载
• 状态重置：在测试之间重置浏览器状态

例如，take:screenshot 命令实现为

来源

• packages/server/lib/browsers/cdp_automation.ts165-618

WebDriver BiDi for Firefox

对于 Firefox 135+，Cypress 正在过渡到 WebDriver BiDi

BiDi 实现提供了与 CDP 类似的功能，但使用了 Firefox 的新协议

来源

• packages/server/lib/browsers/firefox.ts411-432
• packages/server/lib/browsers/firefox-util.ts13-130

浏览器特定实现细节

Chrome

Chrome 自动化通过 CRI 客户端系统利用 Chrome DevTools Protocol (CDP)。主要功能包括

• Chrome 首选项管理：读取和修改 Chrome 首选项文件
• 扩展加载：加载 Cypress 扩展和用户扩展
• 无头支持：配置 Chrome 以支持有头和无头模式
• Chrome 特定标志：设置特定于 Chrome 需求的命令行标志

例如，Chrome 参数是使用特定于浏览器的选项构建的

来源

• packages/server/lib/browsers/chrome.ts273-380
• packages/server/lib/browsers/chrome.ts516-627

Firefox

Firefox 同时支持 CDP（旧版本）和 WebDriver BiDi（135+）。实现包括

• Firefox 配置文件管理：创建和配置 Firefox 配置文件
• Firefox 特定首选项：为测试设置大量 Firefox 首选项
• WebDriver 集成：使用 geckodriver/WebDriver 进行某些操作
• 协议选择：根据 Firefox 版本在 CDP 和 WebDriver BiDi 之间选择

Firefox 根据版本选择协议

来源

• packages/server/lib/browsers/firefox.ts412-420
• packages/server/lib/browsers/firefox.ts452-805

Electron

Electron 是独特的，因为它与 Cypress 运行在同一个进程中。它的实现包括

• BrowserWindow 管理：创建和配置 Electron BrowserWindow
• IPC 通信：处理与渲染器之间的进程间通信
• 菜单集成：为 Electron 设置应用程序菜单
• 子窗口处理：管理由测试打开的子窗口

Electron 的启动流程与其他浏览器不同

来源

• packages/server/lib/browsers/electron.ts154-392
• packages/server/lib/browsers/electron.ts279-627

WebKit

WebKit 支持通过 Playwright 提供，具有不同的自动化适配器

来源

• packages/server/lib/browsers/webkit.ts1-95
• packages/server/lib/browsers/webkit-automation.ts76-588

错误处理和重新连接

浏览器自动化系统包括强大的错误处理和重新连接功能

崩溃检测

系统检测浏览器崩溃并将其报告给 Cypress

重新连接逻辑

CRI 客户端处理连接丢失并自动重新连接

命令排队

命令在连接丢失期间排队，并在重新连接时执行

来源

• packages/server/lib/browsers/cri-client.ts395-486
• packages/server/lib/browsers/chrome.ts465-481

配置文件和扩展管理

浏览器配置文件和扩展由实用函数管理

配置文件目录

为每个浏览器和运行模式创建配置文件目录

扩展安装

安装 Cypress 扩展以启用高级功能

插件集成

插件可以修改浏览器启动选项

来源

• packages/server/lib/browsers/utils.ts87-92
• packages/server/lib/browsers/utils.ts312-331
• packages/server/lib/browsers/utils.ts137-165

未来方向

浏览器自动化系统持续发展

1. WebDriver BiDi 采纳：Firefox 正在从 Firefox 135+ 的 CDP 过渡到 WebDriver BiDi
2. 更好的 WebKit 支持：通过 Playwright 不断改进 WebKit 支持
3. 协议标准化：朝着跨浏览器标准化协议发展

来源

• packages/server/lib/browsers/firefox.ts346-352
• packages/server/lib/browsers/firefox.ts412-420

总结

浏览器自动化系统为 Cypress 在测试执行期间控制浏览器提供了一个强大而灵活的基础。通过将特定于浏览器的细节抽象为通用接口，并利用原生的浏览器协议，它能够在支持网络拦截、Cookie 管理和崩溃恢复等高级功能的同时，实现跨不同浏览器环境的一致性测试。