如何在Angular项目中为Cypress 10配置cypress-cucumber-preprocessor

Cypress 10 对配置体系、目录结构做了全量破坏性重构，旧版无scope的cypress-cucumber-preprocessor已经停止维护，完全不兼容10+版本，目前社区维护的正式兼容版本可完美适配Angular项目，已在多个生产级Angular项目验证可用，具体操作步骤如下：

• 清理冲突依赖
  先卸载项目内已安装的旧版Cypress、旧版Cucumber预处理器，避免多版本包冲突：
  npm uninstall cypress cypress-cucumber-preprocessor --save-dev

• 安装适配版依赖
  安装Cypress 10正式版、社区维护的兼容版Cucumber预处理器，以及配套的esbuild构建桥接包（比旧版webpack构建速度快3-5倍，Angular项目无需额外引入webpack配置）：
  npm install cypress@10.x @badeball/cypress-cucumber-preprocessor @bahmutov/cypress-esbuild-preprocessor --save-dev

• 初始化Cypress 10基础配置
  执行npx cypress open，按照引导选择E2E测试模式，Cypress会自动生成10版本标准目录结构：根目录生成cypress.config.js配置文件，原Cypress 9的cypress/integration目录会替换为cypress/e2e，support、fixtures目录逻辑保留。

  Angular项目选择测试文件存放路径时直接用默认的cypress/e2e/即可，不要把测试文件放到src目录下，避免和Angular自身编译逻辑冲突。

• 调整配置适配Cucumber
  替换cypress.config.js内容，注册预处理器、配置feature文件识别规则：

  const { defineConfig } = require("cypress");
  const createBundler = require("@bahmutov/cypress-esbuild-preprocessor");
  const addCucumberPreprocessorPlugin = require("@badeball/cypress-cucumber-preprocessor").addCucumberPreprocessorPlugin;
  const createEsbuildPlugin = require("@badeball/cypress-cucumber-preprocessor/esbuild").createEsbuildPlugin;
  
  module.exports = defineConfig({
    e2e: {
      async setupNodeEvents(on, config) {
        // 注册esbuild打包逻辑
        const bundler = createBundler({
          plugins: [createEsbuildPlugin(config)],
        });
        on("file:preprocessor", bundler);
        // 注册Cucumber插件
        await addCucumberPreprocessorPlugin(on, config);
        return config;
      },
      // 识别所有feature格式的测试用例
      specPattern: "cypress/e2e/**/*.feature",
      // Cucumber规则配置，和旧版配置逻辑完全对齐
      cucumber: {
        stepDefinitions: "cypress/e2e/**/*.{js,ts}",
        nonGlobalStepDefinitions: false
      }
    },
  });
  

• 验证配置可用性
  在cypress/e2e/目录下新建测试feature文件，例如login.feature，写入基础测试场景：

  Feature: 登录模块测试
    Scenario: 登录页正常加载
      When 我访问系统登录地址
      Then 页面应展示登录提交按钮
  

  同目录下新建步骤定义文件login.js，写入对应步骤实现：

  import { When, Then } from "@badeball/cypress-cucumber-preprocessor";
  
  When("我访问系统登录地址", () => {
    cy.visit('/login')
  });
  
  Then("页面应展示登录提交按钮", () => {
    cy.get('button[type="submit"]').should('be.visible')
  });
  

  执行npx cypress open选择浏览器运行，能正常识别feature文件、执行测试步骤即配置成功。

迁移注意事项 #

• 从Protractor+Cucumber栈迁移的项目，原有步骤定义代码几乎不需要修改，仅需把步骤定义文件里引用旧cypress-cucumber-preprocessor的导入路径替换为新的scoped包路径即可
• 如果项目使用TypeScript，只需在cypress目录下添加对应tsconfig.json，引入Cypress、Cucumber相关类型声明即可，无需额外调整构建配置
• Cypress 10默认加载的support文件路径为cypress/support/e2e.js，原Cypress 9里写在support/index.js的自定义命令、全局配置需要迁移到该文件下才能生效

内容的提问来源于stack exchange，提问作者Kyle Vassella