Webpack打包Mocha测试时抛出describe未定义错误的解决方法

在用Webpack打包Node.js的Mocha测试代码时，会遇到"ReferenceError: describe is not defined"错误——因为describe、it等是Mocha运行时才会注入的全局方法，Webpack编译阶段找不到这些变量，导致编译失败。

临时解决方案 #

目前采用的临时方案是先在代码中定义空的全局方法让Webpack通过编译，再用sed删除该定义后执行测试：

临时测试代码 #

// 临时hack，避免Webpack编译时抛出“ReferenceError: describe is not defined”
// Mocha运行前会通过sed替换该全局定义
global.describe = function() {};

describe('My services', async function() { ... });

Webpack配置关键部分 #

cache: true,
mode: 'development',
target: 'node',
// 忽略Node.js内置模块和node_modules中的模块
externalsPresets: {node: true},
externals: [nodeExternals()],
watchOptions: {
  ignored: ['**/node_modules', '**/build'],
},
devtool: undefined,
module: {
  rules: [{
    test: /\.c?js$/,
    exclude: /node_modules/,
    use: {
      loader: 'babel-loader',
      options: {
        presets: [
          [
            '@babel/preset-env',
            {
              targets: 'node 18.0',
              modules: 'auto',
              useBuiltIns: 'usage',
              corejs: '3.6',
            },
          ],
        ],
        plugins:[/* 省略已有插件 */],
      },
    },
  }],
},

sed处理命令 #

sed 's|global.describe = function () {};||' build/serviceTests.cjs > build/serviceTestsNoGlobalDescribe.cjs && mocha build/serviceTestsNoGlobalDescribe.cjs

更优雅的替代方案 #

不需要手动添加临时代码和sed处理，通过Webpack配置即可解决问题：

方案1：用DefinePlugin声明全局变量 #

在Webpack配置的plugins中添加DefinePlugin，将Mocha的全局方法映射到global对象，让Webpack编译时认为这些变量已存在：

const webpack = require('webpack');

module.exports = {
  // ...其他已有配置
  plugins: [
    new webpack.DefinePlugin({
      describe: 'global.describe',
      it: 'global.it',
      before: 'global.before',
      after: 'global.after',
      beforeEach: 'global.beforeEach',
      afterEach: 'global.afterEach'
    })
  ]
};

这样编译后的代码中describe会被替换为global.describe，Mocha运行时会自动在global注入这些方法，无需额外处理。

方案2：用ProvidePlugin自动关联Mocha方法 #

通过ProvidePlugin让Webpack在遇到这些全局方法时自动从Mocha模块中引入：

const webpack = require('webpack');

module.exports = {
  // ...其他已有配置
  plugins: [
    new webpack.ProvidePlugin({
      describe: ['mocha', 'describe'],
      it: ['mocha', 'it'],
      before: ['mocha', 'before'],
      after: ['mocha', 'after']
    })
  ],
  // 因为用了nodeExternals，需要允许Webpack打包mocha（否则会被忽略）
  externals: [nodeExternals({ allowlist: ['mocha'] })]
};

环境信息 #

Node.js: v18

package.json:
"type": "module",
"devDependencies": {
  "mocha": "10.2.0",
  "@babel/core": "7.20.12",
  "@babel/plugin-proposal-class-properties": "7.18.6",
  "@babel/plugin-proposal-decorators": "7.20.13",
  "@babel/plugin-proposal-throw-expressions": "7.18.6",
  "@babel/plugin-transform-runtime": "7.19.6",
  "@babel/preset-env": "7.20.2",
  "babel-loader": "8.0.6",
  "webpack": "5.75.0",
  "webpack-cli": "5.0.1",
  "webpack-node-externals": "3.0.0"
},

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