如何正确配置Cypress 10、Vue2、Vuetify与Composition API组件测试环境

前置依赖版本强制要求 #

版本不匹配是80%报错的根源，严格按以下版本安装，不要装适配Vue3的高版本包：

• cypress 锁定10.x版本，11+版本对Vue2的组件测试适配存在不兼容变更
• @cypress/vue 必须安装3.x版本，4.x及以上版本仅支持Vue3，装错会直接出现导入失效、自定义组件识别失败问题
• Vue生态包版本对齐：
  • vue 推荐用2.7.x版本，内置Composition API支持，无需额外安装插件；如果用2.6.x及更早版本，需额外安装@vue/composition-api并全局注册
  • vuetify 锁定2.6.x版本，3.x版本仅支持Vue3
  • sass、sass-loader、vue-style-loader、css-loader 版本需和Vuetify2要求的版本对齐，不要装最新版

核心配置修正（覆盖官方文档错误点） #

官方文档给出的自定义挂载、组件层级复刻示例存在3处明确错误：展开运算符位置错误、未正确注册Vuetify实例、未绑定Composition API运行上下文，直接照抄会出现语法报错、setup返回值无法访问、未知标签等问题。以下是可直接运行的配置：

1. cypress.config.js 配置 #

const { defineConfig } = require("cypress");

module.exports = defineConfig({
  component: {
    devServer: {
      framework: "vue",
      bundler: "webpack",
      // 显式声明Vue版本为2，否则Cypress默认按Vue3逻辑处理挂载
      vue: {
        version: 2,
      },
      // 补全Vuetify依赖的webpack loader，解决样式、字体文件导入失效问题
      webpackConfig: {
        module: {
          rules: [
            {
              test: /\.s(c|a)ss$/,
              use: [
                'vue-style-loader',
                'css-loader',
                {
                  loader: 'sass-loader',
                  options: {
                    implementation: require('sass'),
                    additionalData: "@import '~vuetify/src/styles/styles.sass';"
                  }
                }
              ]
            },
            {
              test: /\.(woff|woff2|eot|ttf|otf)$/,
              type: 'asset/resource'
            }
          ]
        }
      }
    },
    // 测试文件匹配规则按自己项目结构调整
    specPattern: "src/**/*.cy.{js,jsx,ts,tsx}"
  },
});

2. 自定义mount命令配置（cypress/support/component.js） #

import { mount } from '@cypress/vue'
import Vuetify from 'vuetify'
import Vue from 'vue'
// 如果你用Vue2.6及以下版本，取消下面两行注释
// import VueCompositionAPI from '@vue/composition-api'
// Vue.use(VueCompositionAPI)

// 全局注册Vuetify，解决v-app、v-btn等自定义标签未知报错
Vue.use(Vuetify)

// 重写mount命令，复刻项目真实的组件嵌套层级
Cypress.Commands.add('mount', (component, options = {}) => {
  const {
    vuetify = new Vuetify(),
    propsData = {},
    plugins = [],
    ...restOptions
  } = options

  // 修正官方文档的展开运算符位置错误：必须放在Vue.extend接收的配置对象内部
  // 不要把展开逻辑写在extend()括号外层，会直接触发语法错误
  const wrappedComponent = Vue.extend({
    ...component,
    propsData,
  })

  return mount({
    render(h) {
      // 包裹v-app根节点，和实际项目运行时的DOM层级完全一致，解决Vuetify布局、弹窗类组件渲染异常
      return h('v-app', [h(wrappedComponent)])
    }
  }, {
    plugins: [vuetify, ...plugins],
    ...restOptions
  })
})

常见报错对应解决方案 #

• 未知标签报错（如Unknown custom element: <v-btn>）：先检查@cypress/vue版本是否为3.x，再确认是否全局注册了Vuetify，最后检查cypress.config.js里是否显式声明了vue版本为2
• setup()返回值无法在测试中访问：不要把单文件组件直接传给原始mount方法，必须经过Vue.extend()包装，包装时要把原组件的所有配置（包括setup）完整展开到extend配置对象里，上述代码已经处理了这个逻辑
• 展开运算符语法报错：检查Vue.extend()的传参，官方示例错误地把组件配置展开写在了extend方法的参数外层，必须放在extend接收的配置对象内部
• 样式、字体文件导入失效：检查webpack配置里是否补全了sass、字体文件对应的loader，注意loader版本不要和Vuetify2要求的版本冲突

测试用例验证 #

配置完成后可以写一个最小用例验证环境正常：

// 引入一个用了Composition API和Vuetify组件的单文件组件
import MyButton from '@/components/MyButton.vue'

describe('测试环境校验', () => {
  it('组件可正常渲染,setup返回值可访问', () => {
    cy.mount(MyButton, {
      propsData: {
        btnText: '测试按钮'
      }
    })
    // 验证Vuetify组件渲染正常
    cy.get('.v-btn').should('contain.text', '测试按钮')
    // 验证点击事件正常触发
    cy.get('.v-btn').click().should('emit', 'click')
  })
})

内容的提问来源于stack exchange，提问作者Sami Kuhmonen