Cypress 组件测试的 Vue 3 挂载适配器深入解析 cypress/vue 包的架构与源码【免费下载链接】cypressFast, easy and reliable testing for anything that runs in a browser.项目地址: https://gitcode.com/GitHub_Trending/cy/cypresscypress/vue是 Cypress 开源仓库当前工作目录cy/cypress中随 Cypress 二进制分发的官方 npm 包为 Vue 3 组件测试提供mount挂载能力。本指南以 npm/vue/AGENTS.md 为骨架结合包源码、测试用例与构建配置展开帮助你理解它如何把一个 Vue 组件渲染进 Cypress 的 AUT 测试页面、如何正确构建与调试该包以及它和vue/test-utils、cypress/mount-utils之间的分工。读完本文你既能在自己的 Vue 3 项目中熟练使用cy.mount编写组件测试也能在 Cypress 仓库内独立完成该包的开发、类型检查与测试。一、包定位什么情况下需要直接依赖 cypress/vue从 package.json 可知cypress/vue的完整描述是Browser-based Component Testing for Vue.js with Cypress.io。它对外暴露一个与 Cypress 命令链兼容的mount函数用于把 Vue 3 组件实例挂载到 Cypress 组件测试运行器的 AUT iframe 中。对于绝大多数终端用户无需单独安装这个包——它已捆绑在cypress主包内官方组件测试文档引导用户直接使用cy.mount。只有下面这类高级场景才需要显式import { mount } from cypress/vue在支持文件中手工注册自定义的mount命令如本仓库 cypress/support/commands.js 所示需要访问本包二次导出的VueTestUtils或自定义挂载选项参与 Cypress 仓库开发、为cypress/vue贡献代码。包的peerDependencies约束了它的运行前提依赖要求说明cypress7.0.0提供组件测试运行器与命令链基础vue3.0.0本包仅支持 Vue 3Vue 2 由cypress/vue2单独支持cypress/webpack-dev-server可选仅 webpack 组件测试配置需要已在peerDependenciesMeta标记为optional: true关于版本当前仓库中的 CHANGELOG.md 保留了逐版本变更记录引擎要求为 Node.js^22 || ^24 || 26构建产物通过main/module/types字段同时提供 CJS、ESM-bundler 与类型声明dist/cypress-vue.cjs.js、dist/cypress-vue.esm-bundler.js、dist/index.d.ts。二、源码架构与文件导航npm/vue目录顶层结构如下以仓库根目录为基准路径职责npm/vue/src/index.ts公共入口完整的mount实现、类型重载、Cypress 全局类型扩展npm/vue/src/shims-vue.d.ts.vue单文件组件的模块声明 shimnpm/vue/cypress/包自身的组件测试示例basic / advanced 等分类与支持文件npm/vue/test-tsd/tsd类型断言测试目录npm/vue/cypress.config.ts该包的组件测试运行配置Vite Vuenpm/vue/rollup.config.mjsRollup 打包配置npm/vue/webpack.config.js供可选 peer 依赖 webpack-dev-server 场景使用的配置值得注意的是AGENTS 文档按早期结构列出的src/mount.ts与src/types.ts在当前代码中已不存在挂载核心逻辑、mount 选项类型与全部类型重载都被收敛到了单个 src/index.ts 文件中。阅读时只需以src/index.ts为唯一真源。src/index.ts内部可拆解为四个逻辑块从vue/test-utilsVTU复用能力解构出mount重命名为VTUmount与shallowMount再把其余工具整体以VueTestUtils命名空间重新导出。代码注释明确说明设计取舍刻意不暴露shallowMount因为“浅挂载”在 Cypress 真实浏览器环境里意义不大仅当有人需要迁移旧 VTU 测试时才会重新开放。扩展全局 Cypress 命名空间声明Cypress.vueWrapper与Cypress.vue供测试中断言与访问组件实例。类型重载层为 9 种组件声明形态提供泛型重载详见后文“类型安全”一节。mount运行时实现见下一节。三、mount 的实现原理组件如何进入 Cypress AUTmount的运行时逻辑集中在 src/index.ts 的实现函数中配合文件底部的setupHooks(cleanup)完成全生命周期管理。关键步骤前置清理每次调用先执行cleanup()——卸载上一次挂载的Cypress.vueWrapper、移除 DOM 中 id 为__cy_vue_root的容器节点并清空两个全局引用保证同一测试内多次cy.mount不会残留旧实例。等待 Cypress 文档就绪在cy.then内通过cy.state(document)拿到 AUT 文档再调用getContainerEl()定位挂载容器。创建容器节点以VUE_ROOT__cy_vue_root为 id 新建div追加到容器元素上——该容器由 npm/mount-utils/src/index.ts 的getContainerEl提供它查找[data-cy-root]选择器找不到会抛出带指引的明确错误。这也是component-index.html中必须有div>/// reference typescypress / import { mount } from cypress/vue Cypress.Commands.add(mount, (comp) { return mount(comp) })随后在支持文件中import ./commands见 cypress/support/component.jsspec 中即可直接写cy.mount(Component)。5.2 组件测试配置本包自身的 cypress.config.ts 是 Vite 方案的完整参照devServer.bundler: viteframework: vue配合experimentalSingleTabRunMode: true提升运行效率。webpack 场景则依赖可选 peer 依赖cypress/webpack-dev-server与 webpack.config.js。5.3 传 props、验证渲染与动态改 props以 basic/props/message-list.cy.ts 为例mount 选项中的props与 VTU 完全一致mount(MessageList, { props: { messages } }) cy.get(ul li).should(have.length, 2) // 挂载后再动态更新 props Cypress.vueWrapper.setProps({ messages: [one, two] })当组件没声明 props、需要包裹一层模板时也可以直接传入一个组件选项对象mount({ template, data, components })5.4 插槽与作用域插槽VTU 的slots机制被原样透传见 basic/slots/Card.cy.js。该文件注释指出由于上游 VTU 的已知 bug插槽内容当前用渲染函数h()编写而非 HTML 字符串mount(Card, { slots: { header: () h(h1, HEADER), footer: () h(div, FOOTER), }, }) mount(Card, { slots: { default: ({ content }) h(div, {}, h(p, Yay! ${content})), }, })5.5 插件、全局扩展与旧版 extensions 选项basic/plugins/plugin.cy.js 展示了如何注入 Vue 插件包括带参数的插件元组形式const use [ MyPlugin, // 无需参数 [MyPluginWithOptions, { label: testing }], // 带参数 ] mount(EmptyComponent, { extensions: { use } }) cy.wrap(Cypress).its(vue).invoke(aPluginMethod).should(equal, foo)需要说明源码中extensions已被标记为deprecated推荐改用 VTU 标准的global选项global: { plugins, mixins, components, ... }。src/index.ts中做了兼容合并若检测到options.extensions会先将其use/mixin拼接进plugins/mixins再并入options.global。5.6 拦截网络请求组件测试同样适用 Cypress 的 stubbing 能力。仓库的 advanced/mocking-axios/Users.cy.js 演示挂载前cy.stub(Axios, get)返回 mock 数据、甚至直接从 JSON fixture 加载cy.stub(Axios, get).resolves({ data: mockUsers }).as(get) mount(Users) cy.get(li).should(have.length, 2) cy.get(get).should(have.been.calledOnce)advanced/mocking-fetch、advanced/mocking-components、advanced/mocking-imports 等目录分别覆盖fetch、子组件、ESM 导入的替换目录中还包含 Vue Routerrouter-example、Vuexcounter-vuex、i18nadvanced/i18n、render 函数advanced/render-functions等进阶样例每个目录下的 README 都附带完整可运行代码是学习真实组件测试模式的最佳素材库。六、类型安全为 9 种组件形态提供重载由于 VTU 的mount类型无法直接被扩展源码注释说明了这一限制cypress/vue在 src/index.ts 中为组件各种声明风格逐一编写了重载签名非vue-class-component的 class 组件无 props / 有 props基于vue-class-component的 class 组件无 props /props()声明 /registerHooks带emits的函数式组件FunctionalComponentdefineComponent完整泛型形态vue-tsc/script setup生成的DefineComponent无 props 的组件选项对象ComponentOptionsWithoutProps{ props: [] }数组声明ComponentOptionsWithArrayProps{ props: { ... } }对象声明ComponentOptionsWithObjectProps借助Readonly约束使required: true保持字面量类型。所有重载的返回类型都是Cypress.Chainable{ wrapper: VueWrapper...; component: ...[vm] }——与直接mount同步返回 wrapper 的 VTU 不同本包返回的是Cypress 命令链这样调用方无需手动cy.wrap即可进入 Cypress 的重试/链式语义。通用MountingOptionsProps, Data还剔除了 VTU 的attachTo字段挂载目标由包内部控制并新增 Cypress 专属的log?: boolean。这些签名由 test-tsd/ 目录中的tsd断言守护——yarn check-ts会先构建出最新的dist类型声明再执行断言避免类型与实现脱节。七、Gotchas 与常见坑总结结合 AGENTS 文档与源码归纳出最容易踩的五个点类型检查必须用vue-tsc而非tsc.vueSFC 的类型推断依赖vue-tsc同时check-ts会先跑tsd。完整校验入口只有一个yarn check-ts。postbuild会同步到cli/vue/改动源码后若直接跑 Cypress 测试跑的是旧产物任何验证前先yarn build。.vue导入需要 shimsrc/shims-vue.d.ts声明了*.vue模块的默认导出类型TS 工程务必把它包含进include。组件测试中禁止cy.visit/cy.session/cy.originsetupHooks会在组件模式下 overwrite 这三个命令并抛错这是设计使然而非 bug。extensions已废弃新代码统一走 VTU 的global选项文档中extensions.use/extensions.mixin的写法仅是向后兼容。此外shallowMount属于刻意不开放的能力VTU 其余工具如flushPromises、RouterLinkStub等通过具名导出VueTestUtils命名空间按需可取。八、集成关系总结cypress/mount-utils兄弟包见 npm/mount-utils/src/index.ts提供getContainerEl定位[data-cy-root]与setupHooks组件模式守卫 自动清理 禁用visit/session/origin是所有框架适配器Vue、React、Svelte、Angular 等的公共底座vue/test-utils真正执行 Vue 组件创建与挂载的引擎本包负责把结果接到 Cypress 命令链与全局对象上cypress/webpack-dev-server可选 peerwebpack 打包方案的组件测试服务仅在对应配置中启用scripts/sync-exported-npm-with-cli.js把本包 dist 同步进cli/vue支撑“随 Cypress 二进制分发、无需单独安装”的交付模型。对外部使用者结论始终是默认使用 Cypress 官方文档指引的cy.mount即可仅当需要自定义挂载行为、复用VueTestUtils命名空间或参与本仓库开发时才深入阅读 npm/vue/src/index.ts 与上述测试示例。【免费下载链接】cypressFast, easy and reliable testing for anything that runs in a browser.项目地址: https://gitcode.com/GitHub_Trending/cy/cypress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cypress 组件测试的 Vue 3 挂载适配器：深入解析 @cypress/vue 包的架构与源码
Cypress 组件测试的 Vue 3 挂载适配器深入解析 cypress/vue 包的架构与源码【免费下载链接】cypressFast, easy and reliable testing for anything that runs in a browser.项目地址: https://gitcode.com/GitHub_Trending/cy/cypresscypress/vue是 Cypress 开源仓库当前工作目录cy/cypress中随 Cypress 二进制分发的官方 npm 包为 Vue 3 组件测试提供mount挂载能力。本指南以 npm/vue/AGENTS.md 为骨架结合包源码、测试用例与构建配置展开帮助你理解它如何把一个 Vue 组件渲染进 Cypress 的 AUT 测试页面、如何正确构建与调试该包以及它和vue/test-utils、cypress/mount-utils之间的分工。读完本文你既能在自己的 Vue 3 项目中熟练使用cy.mount编写组件测试也能在 Cypress 仓库内独立完成该包的开发、类型检查与测试。一、包定位什么情况下需要直接依赖 cypress/vue从 package.json 可知cypress/vue的完整描述是Browser-based Component Testing for Vue.js with Cypress.io。它对外暴露一个与 Cypress 命令链兼容的mount函数用于把 Vue 3 组件实例挂载到 Cypress 组件测试运行器的 AUT iframe 中。对于绝大多数终端用户无需单独安装这个包——它已捆绑在cypress主包内官方组件测试文档引导用户直接使用cy.mount。只有下面这类高级场景才需要显式import { mount } from cypress/vue在支持文件中手工注册自定义的mount命令如本仓库 cypress/support/commands.js 所示需要访问本包二次导出的VueTestUtils或自定义挂载选项参与 Cypress 仓库开发、为cypress/vue贡献代码。包的peerDependencies约束了它的运行前提依赖要求说明cypress7.0.0提供组件测试运行器与命令链基础vue3.0.0本包仅支持 Vue 3Vue 2 由cypress/vue2单独支持cypress/webpack-dev-server可选仅 webpack 组件测试配置需要已在peerDependenciesMeta标记为optional: true关于版本当前仓库中的 CHANGELOG.md 保留了逐版本变更记录引擎要求为 Node.js^22 || ^24 || 26构建产物通过main/module/types字段同时提供 CJS、ESM-bundler 与类型声明dist/cypress-vue.cjs.js、dist/cypress-vue.esm-bundler.js、dist/index.d.ts。二、源码架构与文件导航npm/vue目录顶层结构如下以仓库根目录为基准路径职责npm/vue/src/index.ts公共入口完整的mount实现、类型重载、Cypress 全局类型扩展npm/vue/src/shims-vue.d.ts.vue单文件组件的模块声明 shimnpm/vue/cypress/包自身的组件测试示例basic / advanced 等分类与支持文件npm/vue/test-tsd/tsd类型断言测试目录npm/vue/cypress.config.ts该包的组件测试运行配置Vite Vuenpm/vue/rollup.config.mjsRollup 打包配置npm/vue/webpack.config.js供可选 peer 依赖 webpack-dev-server 场景使用的配置值得注意的是AGENTS 文档按早期结构列出的src/mount.ts与src/types.ts在当前代码中已不存在挂载核心逻辑、mount 选项类型与全部类型重载都被收敛到了单个 src/index.ts 文件中。阅读时只需以src/index.ts为唯一真源。src/index.ts内部可拆解为四个逻辑块从vue/test-utilsVTU复用能力解构出mount重命名为VTUmount与shallowMount再把其余工具整体以VueTestUtils命名空间重新导出。代码注释明确说明设计取舍刻意不暴露shallowMount因为“浅挂载”在 Cypress 真实浏览器环境里意义不大仅当有人需要迁移旧 VTU 测试时才会重新开放。扩展全局 Cypress 命名空间声明Cypress.vueWrapper与Cypress.vue供测试中断言与访问组件实例。类型重载层为 9 种组件声明形态提供泛型重载详见后文“类型安全”一节。mount运行时实现见下一节。三、mount 的实现原理组件如何进入 Cypress AUTmount的运行时逻辑集中在 src/index.ts 的实现函数中配合文件底部的setupHooks(cleanup)完成全生命周期管理。关键步骤前置清理每次调用先执行cleanup()——卸载上一次挂载的Cypress.vueWrapper、移除 DOM 中 id 为__cy_vue_root的容器节点并清空两个全局引用保证同一测试内多次cy.mount不会残留旧实例。等待 Cypress 文档就绪在cy.then内通过cy.state(document)拿到 AUT 文档再调用getContainerEl()定位挂载容器。创建容器节点以VUE_ROOT__cy_vue_root为 id 新建div追加到容器元素上——该容器由 npm/mount-utils/src/index.ts 的getContainerEl提供它查找[data-cy-root]选择器找不到会抛出带指引的明确错误。这也是component-index.html中必须有div>/// reference typescypress / import { mount } from cypress/vue Cypress.Commands.add(mount, (comp) { return mount(comp) })随后在支持文件中import ./commands见 cypress/support/component.jsspec 中即可直接写cy.mount(Component)。5.2 组件测试配置本包自身的 cypress.config.ts 是 Vite 方案的完整参照devServer.bundler: viteframework: vue配合experimentalSingleTabRunMode: true提升运行效率。webpack 场景则依赖可选 peer 依赖cypress/webpack-dev-server与 webpack.config.js。5.3 传 props、验证渲染与动态改 props以 basic/props/message-list.cy.ts 为例mount 选项中的props与 VTU 完全一致mount(MessageList, { props: { messages } }) cy.get(ul li).should(have.length, 2) // 挂载后再动态更新 props Cypress.vueWrapper.setProps({ messages: [one, two] })当组件没声明 props、需要包裹一层模板时也可以直接传入一个组件选项对象mount({ template, data, components })5.4 插槽与作用域插槽VTU 的slots机制被原样透传见 basic/slots/Card.cy.js。该文件注释指出由于上游 VTU 的已知 bug插槽内容当前用渲染函数h()编写而非 HTML 字符串mount(Card, { slots: { header: () h(h1, HEADER), footer: () h(div, FOOTER), }, }) mount(Card, { slots: { default: ({ content }) h(div, {}, h(p, Yay! ${content})), }, })5.5 插件、全局扩展与旧版 extensions 选项basic/plugins/plugin.cy.js 展示了如何注入 Vue 插件包括带参数的插件元组形式const use [ MyPlugin, // 无需参数 [MyPluginWithOptions, { label: testing }], // 带参数 ] mount(EmptyComponent, { extensions: { use } }) cy.wrap(Cypress).its(vue).invoke(aPluginMethod).should(equal, foo)需要说明源码中extensions已被标记为deprecated推荐改用 VTU 标准的global选项global: { plugins, mixins, components, ... }。src/index.ts中做了兼容合并若检测到options.extensions会先将其use/mixin拼接进plugins/mixins再并入options.global。5.6 拦截网络请求组件测试同样适用 Cypress 的 stubbing 能力。仓库的 advanced/mocking-axios/Users.cy.js 演示挂载前cy.stub(Axios, get)返回 mock 数据、甚至直接从 JSON fixture 加载cy.stub(Axios, get).resolves({ data: mockUsers }).as(get) mount(Users) cy.get(li).should(have.length, 2) cy.get(get).should(have.been.calledOnce)advanced/mocking-fetch、advanced/mocking-components、advanced/mocking-imports 等目录分别覆盖fetch、子组件、ESM 导入的替换目录中还包含 Vue Routerrouter-example、Vuexcounter-vuex、i18nadvanced/i18n、render 函数advanced/render-functions等进阶样例每个目录下的 README 都附带完整可运行代码是学习真实组件测试模式的最佳素材库。六、类型安全为 9 种组件形态提供重载由于 VTU 的mount类型无法直接被扩展源码注释说明了这一限制cypress/vue在 src/index.ts 中为组件各种声明风格逐一编写了重载签名非vue-class-component的 class 组件无 props / 有 props基于vue-class-component的 class 组件无 props /props()声明 /registerHooks带emits的函数式组件FunctionalComponentdefineComponent完整泛型形态vue-tsc/script setup生成的DefineComponent无 props 的组件选项对象ComponentOptionsWithoutProps{ props: [] }数组声明ComponentOptionsWithArrayProps{ props: { ... } }对象声明ComponentOptionsWithObjectProps借助Readonly约束使required: true保持字面量类型。所有重载的返回类型都是Cypress.Chainable{ wrapper: VueWrapper...; component: ...[vm] }——与直接mount同步返回 wrapper 的 VTU 不同本包返回的是Cypress 命令链这样调用方无需手动cy.wrap即可进入 Cypress 的重试/链式语义。通用MountingOptionsProps, Data还剔除了 VTU 的attachTo字段挂载目标由包内部控制并新增 Cypress 专属的log?: boolean。这些签名由 test-tsd/ 目录中的tsd断言守护——yarn check-ts会先构建出最新的dist类型声明再执行断言避免类型与实现脱节。七、Gotchas 与常见坑总结结合 AGENTS 文档与源码归纳出最容易踩的五个点类型检查必须用vue-tsc而非tsc.vueSFC 的类型推断依赖vue-tsc同时check-ts会先跑tsd。完整校验入口只有一个yarn check-ts。postbuild会同步到cli/vue/改动源码后若直接跑 Cypress 测试跑的是旧产物任何验证前先yarn build。.vue导入需要 shimsrc/shims-vue.d.ts声明了*.vue模块的默认导出类型TS 工程务必把它包含进include。组件测试中禁止cy.visit/cy.session/cy.originsetupHooks会在组件模式下 overwrite 这三个命令并抛错这是设计使然而非 bug。extensions已废弃新代码统一走 VTU 的global选项文档中extensions.use/extensions.mixin的写法仅是向后兼容。此外shallowMount属于刻意不开放的能力VTU 其余工具如flushPromises、RouterLinkStub等通过具名导出VueTestUtils命名空间按需可取。八、集成关系总结cypress/mount-utils兄弟包见 npm/mount-utils/src/index.ts提供getContainerEl定位[data-cy-root]与setupHooks组件模式守卫 自动清理 禁用visit/session/origin是所有框架适配器Vue、React、Svelte、Angular 等的公共底座vue/test-utils真正执行 Vue 组件创建与挂载的引擎本包负责把结果接到 Cypress 命令链与全局对象上cypress/webpack-dev-server可选 peerwebpack 打包方案的组件测试服务仅在对应配置中启用scripts/sync-exported-npm-with-cli.js把本包 dist 同步进cli/vue支撑“随 Cypress 二进制分发、无需单独安装”的交付模型。对外部使用者结论始终是默认使用 Cypress 官方文档指引的cy.mount即可仅当需要自定义挂载行为、复用VueTestUtils命名空间或参与本仓库开发时才深入阅读 npm/vue/src/index.ts 与上述测试示例。【免费下载链接】cypressFast, easy and reliable testing for anything that runs in a browser.项目地址: https://gitcode.com/GitHub_Trending/cy/cypress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考