Cypress10.2.0集成cucumber-preprocessor未识别测试用例如何排查

以下是配置、代码中存在的问题及对应修复方法： #

1. Feature 文件不符合 Gherkin 语法规范 #

你当前编写的qaweb.feature存在语法错误：

• Gherkin 语法中单一场景必须使用Scenario:关键字声明，你错写为Scenarios:
• 测试步骤没有正确归属到Background或Scenario块下，导致 Cucumber 解析器无法识别有效测试用例

错误写法：

Feature: Web Test
Background: Background name: Navigate to webpage
Scenarios: Web Page Navigation
When navigate to a web page

修正后写法：

Feature: Web Test
  Background: Navigate to webpage
    // 此处编写Background下需要执行的公共步骤

  Scenario: Web Page Navigation
    When navigate to a web page

2. package.json 配置层级错误 #

你将stepDefinitions配置项写在了 package.json 根目录，该配置必须归属到cypress-cucumber-preprocessor配置块内部，否则预处理器无法读取步骤定义的路径规则，无法关联.feature 文件和对应步骤代码。

错误配置片段：

{
  "cypress-cucumber-preprocessor": {
    "json": {
      "enabled": true
    }
  },
  "stepDefinitions": [
    "**/cypress/e2e/**/*.{js,ts}",
    "**/cypress/e2e/.{js,ts}",
    "**/cypress/support/step_definitions/**/*.{js,ts}"
  ]
}

修正后配置片段：

{
  "dependencies": {
    "@badeball/cypress-cucumber-preprocessor": "^11.2.0-rc1",
    "@cypress/webpack-preprocessor": "^5.12.0",
    "cypress": "^10.2.0"
  },
  "cypress-cucumber-preprocessor": {
    "json": {
      "enabled": true
    },
    "stepDefinitions": [
      "cypress/e2e/**/*.{js,ts}",
      "cypress/support/step_definitions/**/*.{js,ts}"
    ]
  }
}

注：原stepDefinitions配置中"**/cypress/e2e/.{js,ts}"为无效路径，直接删除即可 #

3. cypress.config.js 配置存在缺陷 #

• 原specPattern配置为"**/*.feature"，会递归扫描所有目录（包括node_modules）下的feature文件，容易出现匹配异常，建议明确指定cypress目录下的扫描路径
• webpack 配置的resolve.extensions中未添加.feature后缀，会导致feature文件加载失败

修正后完整配置：

const { defineConfig } = require("cypress");
const webpack = require("@cypress/webpack-preprocessor");
const preprocessor = require("@badeball/cypress-cucumber-preprocessor");

async function setupNodeEvents(on, config) {
  await preprocessor.addCucumberPreprocessorPlugin(on, config);

  on(
    "file:preprocessor",
    webpack({
      webpackOptions: {
        resolve: {
          extensions: [".ts", ".js", ".feature"],
        },
        module: {
          rules: [
            {
              test: /\.ts$/,
              exclude: [/node_modules/],
              use: [
                {
                  loader: "ts-loader",
                },
              ],
            },
            {
              test: /\.feature$/,
              use: [
                {
                  loader: "@badeball/cypress-cucumber-preprocessor/webpack",
                  options: config,
                },
              ],
            },
          ],
        },
      },
    })
  );

  return config;
}

module.exports = defineConfig({
  e2e: {
    specPattern: "cypress/e2e/**/*.feature",
    supportFile: false,
    setupNodeEvents,
  },
});

4. 步骤定义文件模块语法不匹配 #

你的步骤定义文件qaweb.js使用了ES Module规范的import语法，但项目未在package.json中声明"type": "module"，Node.js默认使用CommonJS规范加载文件，会触发导入错误。

修正后步骤定义代码（CommonJS写法，无需额外修改package.json）：

/// <reference types="Cypress" />
const { When } = require("@badeball/cypress-cucumber-preprocessor");

When("navigate to a web page", () => {
  cy.visit("https://www.duckduckgo.com");
});

注：步骤定义文件路径需要和你配置的stepDefinitions规则匹配，建议和对应feature文件放在cypress/e2e目录的同级或子目录下 #

验证操作 #

所有配置修改完成后，执行以下操作清除缓存重启服务：

• 删除项目根目录下的.cypress-cache缓存文件夹
• 关闭当前Cypress运行窗口
• 重新执行npx cypress open启动测试执行器，即可在e2e测试列表中看到对应的feature测试用例

相关参考截图：

• Cypress自动化运行窗口报错截图
• VS Code项目结构截图

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