在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

cypress-io/cypress

菜单

浏览器集成

相关源文件

此页面记录了 Cypress 如何与各种浏览器集成和自动化。浏览器集成系统负责启动浏览器实例，通过各种协议与它们通信，并提供自动化功能，使 Cypress 能够执行命令、与 DOM 交互、管理 cookie、处理网络请求以及捕获屏幕截图。

有关浏览器协议扩展的信息，请参阅 协议集成。

概述

浏览器集成系统是 Cypress 的核心部分，支持在不同浏览器环境中进行测试。它为 Cypress 提供了一个统一的接口，以便在不考虑底层技术的情况下控制浏览器。

来源

  • [packages/server/lib/browsers/chrome.ts]
  • [packages/server/lib/browsers/firefox.ts]
  • [packages/server/lib/browsers/electron.ts]
  • [packages/server/lib/browsers/webkit.ts]

架构

浏览器集成架构由几个关键组件组成

来源

  • [packages/server/lib/browsers/cdp_automation.ts]
  • [packages/server/lib/browsers/browser-cri-client.ts]
  • [packages/server/lib/browsers/cri-client.ts]
  • [packages/server/lib/browsers/firefox-util.ts]

组件职责

  1. 浏览器启动器：负责启动具有适当调试功能已启用的浏览器实例

    • chrome.ts - Chrome 浏览器启动器
    • firefox.ts - Firefox 浏览器启动器
    • electron.ts - Electron 浏览器启动器
    • webkit.ts - WebKit 浏览器启动器

  2. 协议客户端：通过调试协议处理与浏览器的通信

    • BrowserCriClient - 浏览器目标的 Chrome 远程接口客户端
    • CriClient - 基本 Chrome 远程接口客户端
    • WebDriver 客户端 - 使用 WebDriver 协议用于 Firefox/WebKit

  3. 自动化实现：为不同浏览器实现自动化接口

    • CdpAutomation - 使用 Chrome DevTools Protocol 进行自动化
    • BidiAutomation - 使用 WebDriver BiDi 协议进行自动化

  4. 通信协议:

    • CDP (Chrome DevTools Protocol) - 用于 Chrome、Electron 和旧版 Firefox
    • WebDriver BiDi - 用于较新版本的 Firefox (≥135) 和 WebKit

来源

  • [packages/server/lib/browsers/types.ts]
  • [packages/server/lib/browsers/utils.ts]

浏览器启动流程

浏览器启动流程因浏览器类型而异，但遵循以下通用模式

每种浏览器都有特定的启动机制

Chrome 启动流程

Chrome 启动的关键步骤

  1. 设置远程调试端口和用户配置文件
  2. 编写 Cypress 扩展
  3. 启动启用远程调试的 Chrome 浏览器
  4. 通过 CDP 连接到 Chrome
  5. 创建 CdpAutomation 实例以控制浏览器

来源

  • [packages/server/lib/browsers/chrome.ts:516-627]
  • [packages/server/test/unit/browsers/chrome_spec.js:80-340]

Firefox 启动流程

Firefox 有两种自动化模式，取决于版本

Firefox 方法的关键区别

  • 新方法 (Firefox ≥135)：直接使用 WebDriver BiDi 协议
  • 旧方法 (Firefox <135)：通过 WebDriver/geckodriver 使用 CDP

来源

  • [packages/server/lib/browsers/firefox.ts:452-514]
  • [packages/server/lib/browsers/firefox-util.ts:1-117]
  • [packages/server/test/unit/browsers/firefox_spec.ts:124-168]

Electron 启动流程

Electron 有其独特性

  • 利用 Electron 内置的浏览器功能
  • 直接创建 BrowserWindow
  • 像 Chrome 一样使用 CDP 进行自动化

来源

  • [packages/server/lib/browsers/electron.ts:155-632]
  • [packages/server/test/unit/browsers/electron_spec.js:120-215]

浏览器自动化

一旦浏览器启动，Cypress 就使用特定于协议的自动化实现。

CDP 自动化

用于 Chrome、Electron 和 Firefox <135

CdpAutomation 类处理

  • 截图
  • 管理 cookie
  • 监控网络活动
  • 处理页面事件
  • 处理运行时评估

来源

  • [packages/server/lib/browsers/cdp_automation.ts:165-618]
  • [packages/server/test/unit/browsers/cdp_automation_spec.ts:84-166]

WebDriver BiDi 自动化

用于 Firefox ≥135 和 WebKit

BidiAutomation 方法

  • 使用标准化的 WebDriver BiDi 协议
  • 具有与 CDP 相同的 P 功能，但通过不同的命令实现
  • 随着浏览器在 WebDriver BiDi 上实现标准化，这更具前瞻性

来源

  • [packages/server/lib/browsers/firefox.ts:411-432]

协议客户端架构

协议客户端管理 Cypress 和浏览器之间的通信

Chrome 远程接口 (CRI) 客户端

CRI 客户端的关键方面

  • BrowserCriClient：管理浏览器级别的 CDP 目标
  • CriClient：处理单个页面目标
  • CDPConnection：管理 WebSocket 连接和消息传输
  • 支持连接断开后的恢复
  • 在连接丢失时排队命令

来源

  • [packages/server/lib/browsers/browser-cri-client.ts:179-1161]
  • [packages/server/lib/browsers/cri-client.ts:101-486]
  • [packages/server/test/unit/browsers/cri-client_spec.ts:77-251]
  • [packages/server/test/unit/browsers/browser-cri-client_spec.ts:72-141]

CI 环境集成

Cypress 检测 CI 环境以增强 CI 中的浏览器测试

CI 提供商检测系统

  • 检测约 30 种不同的 CI 环境
  • 提取 CI 特定参数 (构建 ID、项目等)
  • 提取提交信息 (分支、SHA 等)
  • 有助于在 CI 环境中配置浏览器启动

来源

  • [packages/server/lib/util/ci_provider.js:1-743]
  • [packages/server/test/unit/util/ci_provider_spec.js:25-60]

高级特性

网络拦截

网络拦截允许 Cypress 通过协议实现来拦截、修改和存根网络请求。

来源

  • [packages/server/lib/browsers/cdp_automation.ts:262-334]

浏览器崩溃处理

崩溃处理可检测浏览器崩溃并向用户提供有用的错误报告。

来源

  • [packages/server/lib/browsers/chrome.ts:464-481]
  • [packages/server/lib/browsers/electron.ts:175-193]

支持的浏览器技术表

浏览器协议扩展支持无头模式支持主启动器文件
ChromeCDP是是chrome.ts
ElectronCDP是是electron.ts
FirefoxCDP (<v135)、WebDriver BiDi (≥v135)是是firefox.ts
WebKitWebDriver BiDi有限是webkit.ts

来源

  • [packages/server/lib/browsers/index.ts:1-149]
  • [packages/server/lib/browsers/types.ts:1-39]

连接到新的 spec 文件

在连续运行多个 spec 文件时，Cypress 可以重用同一个浏览器实例

此过程允许 Cypress 在不重新启动浏览器的情况下运行多个 spec，从而提高性能。

来源

  • [packages/server/lib/browsers/chrome.ts:416-433]
  • [packages/server/lib/browsers/firefox.ts:421-432]
  • [packages/server/lib/browsers/firefox-util.ts:12-58]

浏览器协议连接

浏览器通信通过调试协议连接进行管理

来源

  • [packages/server/lib/browsers/chrome.ts:435-459]
  • [packages/server/lib/browsers/firefox.ts:63-77]

结论

浏览器集成系统是 Cypress 的基础部分，可实现跨不同浏览器的统一测试执行。它抽象了浏览器及其自动化协议之间的差异，为 Cypress 的其余部分提供了一个统一的接口。随着浏览器供应商朝着标准化 WebDriver BiDi 发展，Cypress 能够保持兼容性，同时提供最先进的测试功能。

来源

  • [packages/server/lib/browsers/index.ts]
  • [packages/server/lib/browsers/types.ts]