Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mochapack CLI execution
✓ npm install --save-dev mocha webpack mochapack
// package.json scripts section:
"test": "mochapack \"test/**/*.spec.ts\""
✗ import mochapack from 'mochapack';
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
✓ mochapack --webpack-config ./webpack.config.test.js "test/**/*.js"
✗ mochapack --webpack-config webpack.config.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
✓ mochapack --watch "test/**/*.spec.ts"
✗ mocha --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.
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
mochapack --version
Debug
Known issues
breakingMochapack 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.fixUpgrade Mocha to a compatible version (5.x.x - 9.x.x). Check your `package.json` for `mocha` and update its version.
affects: >=2.0.0
gotchaWhen 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.fixUse double quotes around glob patterns, e.g., `mochapack "test/**/*.js"` instead of `mochapack test/**/*.js`.
affects: All versions
gotchaMochapack 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.fixVerify that your installed versions of `mocha` and `webpack` meet Mochapack's peer dependency requirements by checking your `package.json` and `node_modules`.
affects: All versions
deprecatedMochapack 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.fixMigrate your `mocha-webpack` setup to `mochapack`. Install `mochapack` and update your `package.json` scripts and configurations accordingly.
affects: All versions (for `mocha-webpack` users)
gotchaThe `--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.fixEnsure 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.
affects: >=2.0.0 <2.0.4
Errors
Common errors & fixes
Error: Cannot find module 'webpack' or Error: Cannot find module 'mocha'
Mochapack's peer dependencies (webpack and mocha) are not installed or are not resolvable.
fixInstall the required peer dependencies: `npm install --save-dev webpack mocha`.
0 passing (0ms)
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.
fixEnsure 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
A generic error indicating that Mochapack encountered a problem during execution, which could range from compilation failures (Webpack errors) to test failures (Mocha errors).
fixReview 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
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.
fixIn 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.
Audit
Dependencies
mocharequiredRequired test runner, supports versions 5.x.x - 9.x.x.
webpackrequiredRequired for test precompilation, supports versions 4.x.x - 5.x.x.