安装selenium-webdriver后Jest运行失败的原因及解决方法

问题背景 #

为React应用维护两类测试：单元测试使用Jest，特性测试选用@cucumber/cucumber（因jest-cucumber两年未更新弃用）。package.json中的测试脚本如下：

"test:unit": "jest --ci",
"test:feature": "cucumber-js"

原本yarn test:unit运行正常，编写Cucumber步骤文件steps.mjs后特性测试可运行但部分用例失败。添加selenium-webdriver依赖（执行yarn add -D selenium-webdriver）后，Jest单元测试出现ESM兼容报错，提示CommonJS模块无法require ES Module。当前环境为Node.js v20.8.0、Yarn 1.22.19。

问题原因 #

• selenium-webdriver新版本采用ESM格式发布，而Jest默认以CommonJS模式运行，两者加载逻辑冲突，导致Jest无法正确加载该依赖。
• Node.js v20对模块格式的检测机制更严格，selenium-webdriver的package.json中可能设置了"type": "module"，或入口文件为ESM格式，触发了Jest加载器的错误。
• 项目中存在.mjs格式的Cucumber步骤文件，进一步激活了Node.js的模块格式检测逻辑，加剧了冲突。

解决方法 #

方案1：配置Jest支持ESM #

修改Jest配置文件（jest.config.js或package.json中的jest字段），启用ESM支持：

module.exports = {
  transform: {},
  extensionsToTreatAsEsm: ['.mjs', '.jsx', '.js'],
  moduleNameMapper: {
    '^(\\.{1,2}/.*)\\.js$': '$1',
  },
  testEnvironment: 'jsdom', // React应用需保留此配置
};

若在package.json中添加"type": "module"，需将Jest配置文件改为jest.config.mjs，并调整导出语法为ESM格式：

export default {
  // 上述配置内容
};

方案2：降级selenium-webdriver到CommonJS兼容版本 #

查找selenium-webdriver仍使用CommonJS格式的版本（如4.10.0之前的版本），执行降级命令：

yarn add -D selenium-webdriver@4.9.1

此方案无需修改现有Jest配置，适合不想调整项目模块系统的场景。

方案3：隔离测试依赖环境 #

使用Yarn工作区或单独子目录分离单元测试与特性测试的依赖，避免selenium-webdriver影响Jest运行：

1. 创建tests/feature目录，在该目录下执行yarn init -y初始化独立的package.json。
2. 在该目录下安装特性测试依赖：yarn add -D @cucumber/cucumber selenium-webdriver。
3. 修改项目根目录的package.json测试脚本：

"test:feature": "cd tests/feature && cucumber-js"

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