mocha-loader

5.1.5 verified Sat Apr 25 auth: no javascript maintenance

A webpack loader that allows Mocha tests to be bundled and run via webpack. Current stable version is 5.1.5 (October 2020), supporting mocha ^5.0.0 to ^8.0.0 and webpack ^4.0.0 || ^5.0.0. It is maintained under the webpack-contrib organization. Key differentiator: integrates Mocha testing into the webpack build pipeline, enabling module resolution, loaders, and plugins for test files. No options are needed; simply apply the loader to test files. Note: v5.0.0 dropped support for the node target (only works in browser-like environments). Release cadence is sporadic; last release over 3 years ago.

Common errors

error Error: Can't resolve 'mocha-loader' ↓

cause Missing installation of mocha-loader or incorrect webpack configuration (not resolving node_modules).

fix

Run npm install --save-dev mocha-loader mocha webpack and ensure webpack.config.js has resolveLoader appropriately (usually defaults).

error TypeError: mocha.run is not a function ↓

cause Incompatible Mocha version (v9+ changed export structure). mocha-loader v5.1.5 only supports mocha up to v8.

fix

Downgrade mocha to v8: npm install --save-dev mocha@8 or switch to a loader that supports Mocha 9+.

error Cannot find module 'css-loader' ↓

cause Obsolete dependency issue (mocha-loader v5.1.5 requires css-loader which is missing if not installed).

fix

Install css-loader as a devDependency: npm install --save-dev css-loader or use an older version of mocha-loader (but newer has fixes).

error Error: webpack target 'node' is not supported by mocha-loader ↓

cause Using mocha-loader v5+ with webpack target set to 'node'.

fix

Remove target: 'node' from webpack config, or switch to a different testing setup for Node.js tests (e.g., run mocha directly).

Warnings

breaking v5.0.0 drops support for the 'node' webpack target; only works in browser-like environments ↓

fix If needed, use mocha directly (without webpack) for Node.js testing, or consider using mocha-webpack (alternative).

breaking v4.0.0 drops support for Node.js <10.13 and Mocha <5 ↓

fix Upgrade Node.js to >=10.13 and Mocha to ^5.0.0 or later.

deprecated The package has not been updated since October 2020. Some users report compatibility issues with newer Mocha versions (>8). ↓

fix Consider using alternatives like karma-mocha-webpack or switch to a dedicated test runner (Jest, Vitest).

gotcha This loader runs tests in a browser context (simulated by webpack). Asynchronous operations like timers may behave differently than in Node.js. ↓

fix Ensure test code is browser-compatible or use a Node.js target alternative if needed.

gotcha Inline loader syntax (import 'mocha-loader!./test.js') does not work with webpack's 'entry' field; you must use a configuration with rules. ↓

fix Use webpack config rules as shown in the quickstart.

Install

npm install mocha-loader

yarn add mocha-loader

pnpm add mocha-loader

Imports

mocha-loader
wrong
```
const test = require('mocha-loader!./test.js')
```
correct
```
import test from 'mocha-loader!./test.js'
```
Inline loader syntax works with both ESM and CJS, but the loader itself is webpack-specific and not a standard Node module.

mocha-loader

wrong

module.exports = { module: { loaders: [ { test: /\.test\.js$/, loader: 'mocha-loader' } ] } }

correct

module.exports = { module: { rules: [ { test: /\.test\.js$/, use: 'mocha-loader' } ] } }

In webpack 4+, use 'rules' with 'use', not the deprecated 'loaders' array. 'loader' property still works but is less flexible.

mocha-loader
wrong
```
import test from './test.js'
```
correct
```
import 'mocha-loader!./test.js'
```
If you want to run a test file as side-effect (no export), use an import without default binding. The loader runs the tests on bundle execution.

Quickstart

Shows a minimal setup: install dependencies, configure webpack rule, write a test file, and build. Tests run when the bundle is loaded in a browser.

// Install
npm install --save-dev mocha-loader mocha webpack

// webpack.config.js
module.exports = {
  entry: './entry.js',
  output: { path: __dirname, filename: 'bundle.js' },
  module: {
    rules: [
      { test: /\.test\.js$/, use: 'mocha-loader', exclude: /node_modules/ },
    ],
  },
};

// entry.js
import './test.test.js';

// test.test.js
describe('Test', () => {
  it('should pass', () => {});
});

// Build and run (in browser)
// webpack
// open index.html (which includes bundle.js)