Mochapack: Webpack-integrated Mocha Test Runner

2.1.5 · active · verified Wed Apr 22

Mochapack is a command-line utility designed to seamlessly integrate Webpack's powerful asset compilation and module resolution directly into the Mocha test runner. Forked from the unmaintained `mocha-webpack`, it provides an optimized testing experience by precompiling test files with Webpack, automatically handling source maps, and avoiding temporary file writes to disk. A key differentiator is its 'watch' mode, which intelligently re-runs only the test files affected by a change, leveraging Webpack's dependency graph for efficient feedback during development. It aims to offer a CLI experience nearly identical to Mocha's, while enabling full Webpack benefits like custom path resolution within tests. The current stable version is 2.1.5, with releases typically occurring on a quarterly basis, focusing on dependency updates, Webpack/Mocha compatibility, and bug fixes.

Common errors

```
Error: Cannot find module 'webpack' or Error: Cannot find module 'mocha'
```
cause Mochapack's peer dependencies (webpack and mocha) are not installed or are not resolvable.

fix Install the required peer dependencies: `npm install --save-dev webpack mocha`.
```
0 passing (0ms)
```
cause This often occurs when Mochapack cannot find any test files to run. A common reason is incorrect or unquoted glob patterns in the CLI command, or issues with webpack's resolution/transpilation.

fix Ensure your glob patterns are correctly quoted (e.g., `mochapack "test/**/*.js"`). Verify your webpack configuration (especially `resolve.extensions` and `module.rules`) correctly handles your test file types and paths.
```
ERROR mochapack exited with code 1
```
cause A generic error indicating that Mochapack encountered a problem during execution, which could range from compilation failures (Webpack errors) to test failures (Mocha errors).

fix Review the output preceding this error for specific Webpack compilation messages or Mocha test failure reports. Check your webpack configuration for any syntax errors or incompatible loaders.
```
ReferenceError: window is not defined
```
cause This error typically indicates that Webpack is compiling your test code for a browser environment when it should be compiled for Node.js, usually due to a missing or incorrect `target` setting in your webpack configuration.

fix In your `webpack.config.js` used with mochapack, ensure `target: 'node'` is set. Also, consider using `webpack-node-externals` to prevent bundling Node.js native modules.

Warnings

breaking Mochapack v2.0.0 dropped support for Mocha 4.x. Projects using older Mocha versions must upgrade to Mocha 5.x.x or higher when updating Mochapack to v2.0.0 or later.
Fix: Upgrade Mocha to a compatible version (5.x.x - 9.x.x). Check your `package.json` for `mocha` and update its version.
gotcha When specifying test file glob patterns directly in the command line or `package.json` scripts, always enclose them in double quotes. Most terminals resolve glob patterns automatically before passing them to the command, leading to incorrect file matching if unquoted.
Fix: Use double quotes around glob patterns, e.g., `mochapack "test/**/*.js"` instead of `mochapack test/**/*.js`.
gotcha Mochapack relies on `mocha` and `webpack` as peer dependencies. Ensure compatible versions are installed in your project. Mochapack 2.x supports Webpack 4.x.x - 5.x.x and Mocha 5.x.x - 9.x.x.
Fix: Verify that your installed versions of `mocha` and `webpack` meet Mochapack's peer dependency requirements by checking your `package.json` and `node_modules`.
deprecated Mochapack is a fork of `mocha-webpack`. The original `mocha-webpack` project is no longer actively maintained. Users are encouraged to migrate to `mochapack` for ongoing support, new features, and compatibility with modern Webpack and Mocha versions.
Fix: Migrate your `mocha-webpack` setup to `mochapack`. Install `mochapack` and update your `package.json` scripts and configurations accordingly.
gotcha The `--file` option for including pre-test files might not have been respected in early 2.x versions, leading to setup scripts not being executed. This was addressed in later patch releases.
Fix: Ensure you are on Mochapack version `2.0.4` or newer if you rely on the `--file` option for loading setup files. Alternatively, use `--require` to load modules before tests, which is often more robust.

Install

npm install mochapack npm
yarn add mochapack yarn
pnpm add mochapack pnpm

Imports

mochapack CLI execution
wrong:
```
import mochapack from 'mochapack';
```
correct:
```
npm install --save-dev mocha webpack mochapack
// package.json scripts section:
"test": "mochapack \"test/**/*.spec.ts\""
```
Mochapack is a CLI tool and does not export JavaScript/TypeScript symbols for direct programmatic import. It is primarily used via npm scripts or direct command-line invocation.
Webpack configuration integration
wrong:
```
mochapack --webpack-config webpack.config.js
```
correct:
```
mochapack --webpack-config ./webpack.config.test.js "test/**/*.js"
```
Mochapack can automatically detect 'webpack.config.js' but explicitly specifying the config file path with `--webpack-config` is recommended for clarity, especially for test-specific configurations. Webpack configurations often need `target: 'node'` and `externals` to avoid bundling node modules.
Watch mode activation
wrong:
```
mocha --watch "test/**/*.spec.ts"
```
correct:
```
mochapack --watch "test/**/*.spec.ts"
```
The `--watch` flag enables Mochapack's intelligent watch mode, which unlike Mocha's, re-runs only affected tests based on the dependency graph, offering faster feedback.

Quickstart

This quickstart demonstrates how to set up Mochapack with TypeScript, Webpack, and Mocha. It includes `package.json` scripts, a basic Webpack configuration for testing Node.js environments, and a sample TypeScript test file. The setup shows how to run tests using a glob pattern and register `ts-node` for TypeScript compilation on the fly.

// First, install dependencies:
// npm install --save-dev mocha webpack mochapack ts-node chai

// package.json (excerpt)
// {
//   "devDependencies": {
//     "mocha": "^9.0.0",
//     "webpack": "^5.0.0",
//     "mochapack": "^2.0.0",
//     "ts-node": "^10.0.0",
//     "chai": "^4.0.0"
//   },
//   "scripts": {
//     "test": "mochapack --require ts-node/register \"test/**/*.spec.ts\""
//   }
// }

// webpack.config.test.js (simplified example)
const nodeExternals = require('webpack-node-externals');

module.exports = {
  mode: 'development',
  target: 'node',
  externals: [nodeExternals()],
  devtool: 'inline-cheap-module-source-map',
  resolve: {
    extensions: ['.ts', '.js', '.json']
  },
  module: {
    rules: [
      {
        test: /\.ts$/,
        loader: 'ts-loader',
        options: { transpileOnly: true }
      }
    ]
  }
};

// test/calculator.spec.ts
import { expect } from 'chai';
import { describe, it } from 'mocha';

class Calculator {
  add(a: number, b: number): number { return a + b; }
  subtract(a: number, b: number): number { return a - b; }
}

describe('Calculator', () => {
  const calculator = new Calculator();

  it('should correctly add two numbers', () => {
    expect(calculator.add(2, 3)).to.equal(5);
  });

  it('should correctly subtract two numbers', () => {
    expect(calculator.subtract(5, 2)).to.equal(3);
  });
});

// To run these tests: npm test

view raw JSON →