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

cypress-io/cypress

菜单

框架适配器

相关源文件

框架适配器是专门的包，通过在 Cypress 的测试基础架构和使用 React、Vue、Angular 和 Svelte 等特定前端框架构建的组件之间提供桥梁，从而支持组件测试。它们规范了在不同框架中挂载、测试和卸载组件的方式。

有关与框架适配器配合使用的开发服务器的信息，请参阅 开发服务器。

架构概述

框架适配器是 Cypress 组件测试基础设施中的关键子系统。它们与开发服务器协同工作，将组件编译并在隔离环境中进行渲染以进行测试。

来源

支持的框架

Cypress 正式支持以下框架适配器

框架包最新版本支持的框架版本
React@cypress/reactv9.0.0+React 18+
Vue@cypress/vuev6.0.0+Vue 3+
Angular@cypress/angularv3.0.0+Angular 17.2+
Svelte@cypress/svelte-Svelte 3+

来源

核心概念

挂载命令

所有框架适配器都提供了一个 mount 命令，该命令是组件测试的主要 API。此命令

  1. 将组件渲染到 DOM 中指定的根元素
  2. 为组件提供任何必需的 props、state 或 context
  3. 返回一个 Cypress chainable，用于后续命令和断言

来源

Mount Utils

@cypress/mount-utils 包提供了所有框架适配器使用的共享实用程序，包括

  • getContainerEl()：检索指定的 DOM 容器元素
  • ROOT_SELECTOR：组件挂载点的选择器（现在是 [data-cy-root]）
  • setupHooks()：配置生命周期钩子，以便在测试之间进行正确的清理

这些实用程序确保了所有框架适配器之间的一致行为，同时允许进行特定于框架的实现。

来源

特定于框架的实现

每个框架适配器都实现了其目标框架特有的挂载逻辑

React Adapter (@cypress/react)

React 适配器使用 ReactDOM（适用于 React 18+）来挂载组件，处理

  • React 组件生命周期
  • Props 和状态管理
  • Hook 支持和 Context Provider

Vue Adapter (@cypress/vue)

Vue 适配器支持 Vue 3 的 Composition API 并处理

  • 单文件组件 (SFCs)
  • Props、slots 和 provide/inject
  • 全局插件和组件

Angular Adapter (@cypress/angular)

Angular 适配器由于 Angular 的架构最为复杂

  • 使用 TestBed 配置测试模块
  • 处理依赖注入
  • 支持组件模板、输入和输出
  • 最近增加了对 Angular 17.2+ 和 Signals 的支持

Svelte Adapter (@cypress/svelte)

Svelte 适配器支持 Svelte 的编译时方法

  • Props 管理
  • 事件处理
  • 生命周期管理

来源

与打包器的集成

框架适配器与由打包器驱动的开发服务器协同工作，以编译和提供组件进行测试。支持的主要打包器是

  1. Webpack：通过 @cypress/webpack-dev-server 包

    • 支持所有框架
    • 处理各种 webpack 配置
    • 可通过 webpack loader 和 plugin 进行配置

  2. Vite：通过 @cypress/vite-dev-server 包

    • 更快的开发体验
    • 支持 React 和 Vue

打包器的选择在组件测试设置过程中指定，并由框架适配器管理。

来源

挂载过程内部

当组件被挂载时，会发生以下过程

主要实现细节

  • DOM 容器元素已从 ID #__cy_root 更改为使用属性 [data-cy-root]
  • 卸载在测试之间得到正确处理，以防止跨测试污染
  • 每个适配器都确保正确清理特定于框架的资源

来源

创建自定义框架适配器

框架适配器的架构允许创建其他框架的自定义适配器。自定义适配器必须

  1. 从 @cypress/mount-utils 导入实用程序
  2. 实现一个接受组件和选项的挂载函数
  3. 使用 setupHooks() 注册生命周期钩子
  4. 返回一个 Cypress chainable

自定义适配器实现模式示例

来源

使用框架适配器进行项目设置

框架适配器的组件测试是通过 Cypress 的组件测试向导配置的，该向导有助于设置

  1. 所选的前端框架
  2. 合适的打包器
  3. 必需的依赖

WizardDataSource 根据选择的框架和打包器管理必需依赖的检测和安装。

来源

框架适配器演进

框架适配器已发生重大演变

  1. 首次集成：组件测试最初是使用独立的、特定于框架的包开始的
  2. 统一架构：引入 @cypress/mount-utils 标准化了核心功能
  3. 嵌入 Cypress：随着 Cypress 10+ 的发布，框架适配器得到了更紧密的集成
  4. 重大更改：主版本已停止支持旧版框架，同时增加了对新版框架的支持

最近的显著更改包括

  • React 19 支持已包含在 @cypress/react v9.0.0 中
  • Angular 19 支持已包含在 @cypress/angular v3.0.0 中
  • @cypress/vue 的新版本仅支持 Vue 3

来源

最佳实践

在使用框架适配器时

  1. 始终使用适合您框架的适配器
  2. 确保正确导入组件依赖项
  3. 在测试拆卸（teardown）中清理副作用（如定时器或订阅）
  4. 使用特定于框架的模式进行测试（例如 React 的 Context Provider）
  5. 利用打包器的功能进行资源导入

框架适配器的设计旨在让组件测试在每个框架生态系统中感觉自然，同时提供 Cypress 测试功能的力量。