Mocha v4 Nears Release

Mocha v4.0.0 is nearing release. With this new version also comes the obligatory breaking changes, and I'll enumerate them below.

UPDATE (April 18, 2018): Mocha v4 was released on October 2, 2017.

Mocha Will No Longer Support Node.js Pre-v4.0.0

There are several reasons for this:

  1. These versions of Node.js are no longer maintained and (some) have known security vulnerabilities which will not receive official patches. Users of these versions should upgrade Node.js. For example, v0.10.0 and v0.12.0 have been end-of-lifed since October and December 2016, respectively.
  2. Mocha's own dependencies have already dropped support for these platforms, and so Mocha cannot address to security vulnerabilities or critical bug fixes in reasonable manner nor timeframe.
  3. Mocha's development environment can no longer run out-of-the-box in a pre-v4.0.0 environment.

The following unmaintained versions of Node.js will no longer be supported by Mocha:

  • v0.10.0
  • v0.11.0
  • v0.12.0
  • iojs
  • v5.x

Node.js v5.x is likely to work as long as Node.js v4.x does, but will not be in Mocha's build matrix.

It's important to note that Mocha v3.x will still work on these platforms, but users can no longer expect upgrades.

For further reading, see this article by Eran Hammer and also the Node.js Release Schedule.

The above change also means:

Mocha Will No Longer Support npm Older Than v2.15.11


  • npm v2.15.11 is the version which shipped with Node.js v4.0.0.
  • Even older versions didn't support scoped packages (@foo/bar), nor the caret (^) semver range specifier. This made it virtually impossible to include production dependencies which used either of these features.

Users are encouraged to upgrade to the latest version of npm.

Users of Bower are also encouraged to upgrade, because:

A silhouette of a person riding a horse along a beach during sunset
Bower rides into the sunset. Photo by Alex Wigan / Unsplash

Mocha Will No Longer Support Bower

This may or may not make it into v4.

UPDATE (April 18, 2018): This made it.

Bower is an excellent tool to install front-end dependencies. However, over the years, more robust solutions have evolved. Its time has passed.

Mocha v4 will remove its "browser bundle" (mocha.js) from version control. This means bower will not install Mocha v4 out-of-the-box. There may be a workaround by means of a "resolver", but YMMV.

A Warning To Those Bundling Mocha

This change may also impact those users bundling Mocha themselves via browserify, webpack, etc. The browser field will now point to mocha.js, which is already bundled. You may no longer need to bundle yourself, or you may need to find a different way to do it. If you cannot find a reasonable workaround, please open an issue on our tracker.

Finally, my favorite:

Mocha Will No Longer Support Non-ES5-Compliant Environments

Mocha is likely the last major actively maintained testing framework to officially support these browsers.

While Mocha's maintainers have proudly sustained the poor, piteous developers who have such business (or government!) requirements, the overhead of retaining compatibility has become an albatross.

Much like supporting older versions of Node.js, this has severely limited the project's agility. Mocha should shed some weight after this, as it contains a plethora of handrolled shims.

The following browser environments will no longer be supported in Mocha v4:

  • Internet Explorer 7
  • Internet Explorer 8
  • PhantomJS 1.x

API and output changes follow.

Other Breaking Changes

Read this to save yourself some time.

Mocha Won't Force Exit

This may or may not make it into v4.

UPDATE (April 18, 2018): This made it.

To avoid false positives and encourage better testing practices, Mocha will no longer automatically kill itself via process.exit() when it thinks it should be done running.

If the mocha process is still alive after your tests seem "done", then your tests have scheduled something to happen (asynchronously) and haven't cleaned up after themselves properly. Did you leave a socket open?

Supply the --exit flag to use pre-v4 behavior.

If you're having trouble figuring out where the hangup is, this package might help.

UPDATE (April 17, 2018): I changed the link above; I've since had better success using wtfnode to debug this class of problems. Be sure to run it against the _mocha executable (not mocha)!

UPDATE (April 23, 2018): Fixed link to wtfnode.


There will be a few changes to reporters, which may negatively affect projects consuming Mocha's output directly:


By shedding support for older environments, Mocha becomes more nimble, and positions itself to leverage the present and future innovations of Node.js and JavaScript.