NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #2276 most downloaded on npm
Classic, reliable, trusted test framework for Node.js and the browser
Last release today
17 Sep 2026
Ships fairly regularly
a new release about every 3 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
105 versions withdrawn
withdrawn after publishing
15 years old
250 releases · first in 2011
fix #4837 Update glob due to vulnerability in dep by @jb2311 in https://github.com/mochajs/mocha/pull/4970
A test release tagged with next on npm, to test that we can do releases at all. See #5081 for context.
titlePath method by @F3n67u in https://github.com/mochajs/mocha/pull/4886Full Changelog: https://github.com/mochajs/mocha/compare/v10.2.0...v10.3.0-preminor.0
One column per quarter.
# 10.2.0 / 2022-12-11 ## :tada: Enhancements - #4945: API: add possibility to decorate ESM name before import (@j0tunn) ## :bug: Fixes - #4946: Browse
# 10.1.0 / 2022-10-16 ## :tada: Enhancements - #4896: Browser: add support for prefers-color-scheme: dark (@greggman) ## :nut\_and\_bolt: Other - #491
Promise.allSettled instead of polyfill (@outsideris)clean(@yetingli)Also thanks to @ea2305 and @SukkaW for improvements to our documentation.
#4863: Rename executable bin/mocha to bin/mocha.js (@juergba)
#4865: --ignore option in Windows: upgrade Minimatch (@juergba)
#4876: Add Node.js v18 to CI test matrix (@outsideris)
#4852: Replace deprecated String.prototype.substr() (@CommanderRoot)
Also thanks to @ea2305 and @SukkaW for improvements to our documentation.
Please also note our announcements.
Please also note our announcements.
Please also note our announcements.
Please also note our announcements.
Please also note our announcements.
Please also note our announcements.
Please also note our announcements.
EVENT_SUITE_ADD_* events (@beatfactor)Please also note our announcements.
Please also note our announcements.
browser-entry.js (@PaperStrike)Please also note our announcements.
Please also note our announcements.
XUNIT and JSON reporter crash in parallel mode (@curtisman)Please also note our announcements.
# 9.0.3 / 2021-07-25 ## :bug: Fixes - #4702: Error rethrow from cwd-relative path while loading .mocharc.js (@kirill-golovan) - #4688: Usage of custom
# 9.0.2 / 2021-07-03 ## :bug: Fixes - #4668: ESM: make --require work with new import-first loading (@giltayar) ## :nut_and_bolt: Other - #4674: Updat
We added a separate browser bundle mocha-es2018.js in javascript ES2018, as we skipped the transpilation down to ES5. This is an experimental step tow
We added a separate browser bundle mocha-es2018.js in javascript ES2018, as we skipped the transpilation down to ES5. This is an experimental step towards freezing Mocha's support of IE11.
hasStableEsmImplementation (@alexander-fenster)Mocha is going ESM-first! This means that it will now use ESM import(test_file) to load the test files, instead of the CommonJS require(test_file). Th
Mocha is going ESM-first! This means that it will now use ESM import(test_file) to load the test files, instead of the CommonJS require(test_file). This is not a problem, as import can also load most files that require does. In the rare cases where this fails, it will fallback to require(...). This ESM-first approach is the next step in Mocha's ESM migration, and allows ESM loaders to load and transform the test file.
#4638: Limit the size of actual/expected for diff generation (@juergba)
#4389: Refactoring: Consuming log-symbols alternate to code for win32 in reporters/base (@MoonSupport)
Also thanks to @outsideris for various improvements on our GH actions workflows.
options.require to Mocha constructor for root hook plugins on parallel runs (@juergba)top-level await and ESM test files (@juergba)Also thanks to @outsideris for various improvements on our GH actions workflows.
# 8.3.2 / 2021-03-12 ## :bug: Fixes - #4599: Fix regression in require interface (@alexander-fenster) ## :book: Documentation - #4601: Add build to GH
require interface (@alexander-fenster)# 8.3.1 / 2021-03-06 ## :bug: Fixes - #4577: Browser: fix EvalError caused by regenerator-runtime (@snoack) - #4574: ESM: allow import from mocha in p
Also thanks to @outsideris and @HyunSangHan for various fixes to our website and documentation.
require error when bundling Mocha with Webpack (@devhazem)Also thanks to @outsideris and @HyunSangHan for various fixes to our website and documentation.
Also thanks to @akeating for a documentation fix!
Fixed stuff.
Promise rejections and erroneous "done() called twice" errors (@boneskull)MaxListenersExceededWarning in watch mode (@boneskull)Also thanks to @akeating for a documentation fix!
The major feature added in v8.2.0 is addition of support for _global fixtures_.
The major feature added in v8.2.0 is addition of support for global fixtures.
While Mocha has always had the ability to run setup and teardown via a hook (e.g., a before() at the top level of a test file) when running tests in serial, Mocha v8.0.0 added support for parallel runs. Parallel runs are incompatible with this strategy; e.g., a top-level before() would only run for the file in which it was defined.
With global fixtures, Mocha can now perform user-defined setup and teardown regardless of mode, and these fixtures are guaranteed to run once and only once. This holds for parallel mode, serial mode, and even "watch" mode (the teardown will run once you hit Ctrl-C, just before Mocha finally exits). Tasks such as starting and stopping servers are well-suited to global fixtures, but not sharing resources--global fixtures do not share context with your test files (but they do share context with each other).
Here's a short example of usage:
// fixtures.js
// can be async or not
exports.mochaGlobalSetup = async function() {
this.server = await startSomeServer({port: process.env.TEST_PORT});
console.log(`server running on port ${this.server.port}`);
};
exports.mochaGlobalTeardown = async function() {
// the context (`this`) is shared, but not with the test files
await this.server.stop();
console.log(`server on port ${this.server.port} stopped`);
};
// this file can contain root hook plugins as well!
// exports.mochaHooks = { ... }
Fixtures are loaded with --require, e.g., mocha --require fixtures.js.
For detailed information, please see the documentation and this handy-dandy flowchart to help understand the differences between hooks, root hook plugins, and global fixtures (and when you should use each).
test.js) now usable with --extension option (@jordanstephens).js, .test.js) now usable with --extension option (@boneskull)json reporter now contains speed ("fast"/"medium"/"slow") property (@wwhurin)For implementors of custom reporters:
Runner.prototype.workerReporter()); reporters should subclass ParallelBufferedReporter in mocha/lib/nodejs/reporters/parallel-bufferedRunner.prototype.linkPartialObjects()); use if strict object equality is needed when consuming Runner event dataRunner.prototype.isParallelMode())npm v6.x causing some of Mocha's deps to be installed when mocha is present in a package's devDependencies and npm install --production is run the package's working copy (@boneskull)nyc with Mocha in parallel mode (@boneskull)lookupFiles() in mocha/lib/utils, which was broken/missing in Mocha v8.1.0; it now prints a deprecation warning (use const {lookupFiles} = require('mocha/lib/cli') instead) (@boneskull)Thanks to @AviVahl, @donghoon-song, @ValeriaVG, @znarf, @sujin-park, and @majecty for other helpful contributions!
# 8.1.3 / 2020-08-28 ## :bug: Fixes - #4425: Restore Mocha.utils.lookupFiles() and Webpack compatibility (both broken since v8.1.0); Mocha.utils.looku
Mocha.utils.lookupFiles() and Webpack compatibility (both broken since v8.1.0); Mocha.utils.lookupFiles() is now deprecated and will be removed in the next major revision of Mocha; use require('mocha/lib/cli').lookupFiles instead (@boneskull)Various fixes by @sujin-park, @wwhurin & @Donghoon759
# 8.1.1 / 2020-08-04 ## :bug: Fixes - #4394: Fix regression wherein certain reporters did not correctly detect terminal width (@boneskull)
In this release, Mocha now builds its browser bundle with Rollup and Babel, which will provide the project's codebase more flexibility and consistency
In this release, Mocha now builds its browser bundle with Rollup and Babel, which will provide the project's codebase more flexibility and consistency.
While we've been diligent about backwards compatibility, it's possible consumers of the browser bundle will encounter differences (other than an increase in the bundle size). If you do encounter an issue with the build, please report it here.
This release does not drop support for IE11.
Other community contributions came from @Devjeel, @Harsha509 and @sharath2106. Thank you to everyone who contributed to this release!
Do you read Korean? See this guide to running parallel tests in Mocha, translated by our maintainer, @outsideris.
mocha init (@boneskull)delay option in browser (@craigtaub)--enable-source-maps with Mocha (@bcoe)The obligatory patch after a major.
The obligatory patch after a major.
--parallel when combined with --watch (@boneskull)In this major release, Mocha adds the ability to _run tests in parallel_. Better late than never! Please note the breaking changes detailed below.
In this major release, Mocha adds the ability to run tests in parallel. Better late than never! Please note the breaking changes detailed below.
Let's welcome @giltayar and @nicojs to the maintenance team!
#4164: Mocha v8.0.0 now requires Node.js v10.12.0 or newer. Mocha no longer supports the Node.js v8.x line ("Carbon"), which entered End-of-Life at the end of 2019 (@UlisesGascon)
#4175: Having been deprecated with a warning since v7.0.0, mocha.opts is no longer supported (@juergba)
:sparkles: WORKAROUND: Replace mocha.opts with a configuration file.
#4260: Remove enableTimeout() (this.enableTimeout()) from the context object (@craigtaub)
:sparkles: WORKAROUND: Replace usage of this.enableTimeout(false) in your tests with this.timeout(0).
#4315: The spec option no longer supports a comma-delimited list of files (@juergba)
:sparkles: WORKAROUND: Use an array instead (e.g., "spec": "foo.js,bar.js" becomes "spec": ["foo.js", "bar.js"]).
#4309: Drop support for Node.js v13.x line, which is now End-of-Life (@juergba)
#4282: --forbid-only will throw an error even if exclusive tests are avoided via --grep or other means (@arvidOtt)
#4223: The context object's skip() (this.skip()) in a "before all" (before()) hook will no longer execute subsequent sibling hooks, in addition to hooks in child suites (@juergba)
#4178: Remove previously soft-deprecated APIs (@wnghdcjfe):
Mocha.prototype.ignoreLeaks()Mocha.prototype.useColors()Mocha.prototype.useInlineDiffs()Mocha.prototype.hideDiff()#4245: Add ability to run tests in parallel for Node.js (see docs) (@boneskull)
:exclamation: See also #4244; Root Hook Plugins (docs) -- root hooks must be defined via Root Hook Plugins to work in parallel mode
#4299: In some circumstances, Mocha can run ES modules under Node.js v10 -- use at your own risk! (@giltayar)
(All bug fixes in Mocha v8.0.0 are also breaking changes, and are listed above)
# 7.2.0 / 2020-05-22 ## :tada: Enhancements - #4234: Add ability to run tests in a mocha instance multiple times (@nicojs) - #4219: Exposing filename
--forbid-only does not recognize it.only when before crashes (@arvidOtt)# 7.1.2 / 2020-04-26 ## :nut_and_bolt: Other - #4251: Prevent karma-mocha from stalling (@juergba) - #4222: Update dependency mkdirp to v0.5.5 (@outsi
# 7.1.1 / 2020-03-18 ## :lock: Security Fixes - #4204: Update dependencies mkdirp, yargs-parser and yargs (@juergba) ## :bug: Fixes - #3660: Fix runne
Mocha supports writing your test files as ES modules:
#4038: Add Node.js native ESM support (@giltayar)
Mocha supports writing your test files as ES modules:
--experimental-modules optionNote: Node.JS native ECMAScript Modules implementation has status: Stability: 1 - Experimental
allowUncaught option (@juergba)package.json (@outsideris)# 7.0.1 / 2020-01-25 ## :bug: Fixes - #4165: Fix exception when skipping tests programmatically (@juergba) - #4153: Restore backwards compatibility fo
reporterOptions (@holm)These are _soft_-deprecated, and will emit a warning upon use. Support will be removed in (likely) the next major version of Mocha:
--debug/--debug-brk and deprecate debug argument (@juergba)--list-interfaces replaces --interfaces--list-reporters replaces --reportersthis.skip() (@juergba):
getOptions() and lib/cli/options.js (@juergba)pending test: don't swallow, but retrospectively fail the test for correct exit code (@juergba)Mocha constructor's option names with command-line options (@juergba)--watch mode with chokidar (@geigerzaehler):
--watch-files and --watch-ignore--watch-extensionsThese are soft-deprecated, and will emit a warning upon use. Support will be removed in (likely) the next major version of Mocha:
--inspect-brk/--inspect (@juergba)Mocha constructor: improve browser setup (@juergba)--allow-uncaught with this.skip() (@juergba)done() (@jgehrcke):coffee: with emoji ☕️ (@pzrq)sh to bash for code block in docs/index.md (@HyunSangHan)This is an experimental release based on v7.0.0: npm i mocha@7.0.0-esm1
This is an experimental release based on v7.0.0: npm i mocha@7.0.0-esm1
#4038: Add Node.js native ESM support (@giltayar)
Enables Mocha to load ECMAScript Modules test files, also valid for --file option.
Limitations:
--experimental-modules option--watch mode--require option--reporter custom reporters--ui custom interfacesmocharc configuration file848d6fb8: Update dependencies mkdirp, yargs-parser and yargs (@juergba)
# 6.2.2 / 2019-10-18 ## :bug: Fixes - #4025: Fix duplicate EVENT_RUN_END events upon uncaught exception (@juergba) - #4051: Fix "unhide" function in h
EVENT_RUN_END events upon uncaught exception (@juergba)html reporter (browser) (@pec9399)# 6.2.1 / 2019-09-29 ## :bug: Fixes - #3955: tty.getWindowSize is not a function inside a "worker_threads" worker (@1999) - #3970: remove extraGlobals
# 6.2.0 / 2019-07-18 ## :tada: Enhancements - #3827: Do not fork child-process if no Node flags are present (@boneskull) - #3725: Base reporter store
--file (@gabegorelick)global or globals (@pascalpp)_mocha binary (@juergba)--timeout/--slow string values and duplicate arguments (@boneskull, @juergba)--watch options (@geigerzaehler)--watch mode behavior (@geigerzaehler)runWatch into separate module (@geigerzaehler)mocha.min.js file to stacktrace filter (@brian-lagerman)--exclude to --ignore and create alias (@boneskull)mocha.css (@DanielRuf)# 6.1.4 / 2019-04-18 ## :lock: Security Fixes - #3877: Upgrade js-yaml, addressing code injection vulnerability (@bjornstar)
# 6.1.3 / 2019-04-11 ## :bug: Fixes - #3863: Fix yargs-related global scope pollution (@inukshuk) - #3869: Fix failure when installed w/ pnpm (@bonesk
yargs-related global scope pollution (@inukshuk)pnpm (@boneskull)# 6.1.2 / 2019-04-08 ## :bug: Fixes - #3867: Re-publish v6.1.1 from POSIX OS to avoid dropped executable flags (@boneskull)
# 6.1.1 / 2019-04-07 ## :bug: Fixes - #3866: Fix Windows End-of-Line publishing issue (@juergba & @cspotcode)
These are _soft_-deprecated, and will emit a warning upon use. Support will be removed in (likely) the next major version of Mocha:
options parameter (@plroebuck).jsonc extension (@sstephant)These are soft-deprecated, and will emit a warning upon use. Support will be removed in (likely) the next major version of Mocha:
this.skip() in "before each" hooks (@juergba)--allow-uncaught for uncaught exceptions thrown inside hooks (@givanse)and some regressions:
Suite cloning by copying root property (@fatso83)# 6.0.2 / 2019-02-25 ## :bug: Fixes Two more regressions fixed: - #3768: Test file paths no longer dropped from mocha.opts (@boneskull) - #3767: --req
Two more regressions fixed:
mocha.opts (@boneskull)--require does not break on module names that look like certain node flags (@boneskull)The obligatory round of post-major-release bugfixes.
The obligatory round of post-major-release bugfixes.
These issues were regressions.
test.js when run without arguments (@plroebuck)--ui (@boneskull)--watch (@boneskull)undefined value from a describe callback is no longer considered deprecated (@boneskull)@mocha/docdash@2 (@tendonstrength)These are _soft_-deprecated, and will emit a warning upon use. Support will be removed in (likely) the next major version of Mocha:
--grep and --fgrep are now mutually exclusive; attempting to use both will cause Mocha to fail instead of simply ignoring --grep--compilers is no longer supported; attempting to use will cause Mocha to fail with a link to more information-d is no longer an alias for --debug; -d is currently ignored--watch-extensions no longer implies js; it must be explicitly added (@TheDancingCode)tap reporter emits error messages (@chrmod)before hook, subsequent before hooks and tests in nested suites are now skipped (@bannmoore)lib/template.html has moved to lib/browser/template.html (@boneskull)mocha.opts at a user-specified path (@plroebuck)Base-extending reporter without a Runner parameter will throw an exception (@craigtaub)code property (and some will have additional metadata). Some Error messages have changed. Please use the code property to check Error types instead of the message property; these descriptions will be localized in the future. (@craigtaub)These are soft-deprecated, and will emit a warning upon use. Support will be removed in (likely) the next major version of Mocha:
-gc users should use --gc-global insteadbin/options should now use the loadMochaOpts or loadOptions (preferred) functions exported by the lib/cli/options moduleRegarding the Mocha class constructor (from lib/mocha):
color: false instead of useColors: falsetimeout: false instead of enableTimeouts: falseAll of the above deprecations were introduced by #3556.
mocha.opts is now considered "legacy"; please prefer RC file or package.json over mocha.opts.
require cache (@plroebuck)Enhancements introduced in #3556:
Mocha now supports "RC" files in JS, JSON, YAML, or package.json-based (using mocha property) format
.mocharc.js, .mocharc.json, .mocharc.yaml or .mocharc.yml are valid "rc" file names and will be automatically loaded--config /path/to/rc/file to specify an explicit path--package /path/to/package.json to specify an explicit package.json to read the mocha prop from--no-config or --no-package to completely disable loading of configuration via RC file and package.json, respectivelypackage.jsonmocha.optsNode/V8 flag support in mocha executable:
node flags as supported by the running version of node (also thanks to @demurgos)--v8- to the flag namepackage.json properties, or mocha.opts--inspect) now imply --no-timeouts--debug will automatically invoke --inspect if supported by running version of nodeSupport negation of any Mocha-specific command-line flag by prepending --no- to the flag name
Interfaces now have descriptions when listed using --interfaces flag
Mocha constructor supports all options
--extension is now an alias for --watch-extensions and affects non-watch-mode test runs as well. For example, to run only test/*.coffee (not test/*.js), you can do mocha --require coffee-script/register --extensions coffee.
#3552: tap reporter is now TAP13-capable (@plroebuck & @mollstam)
#3535: Mocha's version can now be queried programmatically via public property Mocha.prototype.version (@plroebuck)
#2529: Runner now emits a retry event when tests are retried (reporters can listen for this) (@catdad)
#2962, #3111: In-browser notification support; warn about missing prereqs when --growl supplied (@plroebuck)
Suite#_onlyTests and Suite#_onlySuites (@vkarpov15)lookupFiles and files (@plroebuck)--delay (and other boolean options) not working in all cases (@boneskull)--reporter-option/--reporter-options did not support comma-separated key/value pairs (@boneskull)mocharc.json in published package (@boneskull)--no-timeouts and --timeout 0 now does what you'd expect (@boneskull)--no-exit option (@boneskull)SIGINT (@boneskull)--forbid-only and --forbid-pending now "fail fast" when encountered on a suite (@outsideris)stdout: prefix in browser console (@Bamieh)utils.isPromise() (@fabiosantoscode)--bail would not execute "after" nor "after each" hooks (@juergba)TERM=dumb (@plroebuck).github/CONTRIBUTING.md (@markowsiak)slow option (@finfin)--watch docs (@benglass)ms userland module instead of hand-rolled solution (@gizemkeser)Nothing published for this version
Nothing published for this version
[#3375]: Add support for comments in mocha.opts ([@plroebuck])
mocha.opts (@plroebuck)before hooks when using --bail (@outsideris)Buffer.from() (@harrysarson)[#3325]: Revert change which broke --watch ([@boneskull])
[#3210]: Add --exclude option ([@metalex9])
Welcome [@outsideris] to the team!
Welcome @outsideris to the team!
--bail failing to bail within hooks (@outsideris)describe.skip()) (@outsideris)CHANGELOG.md (@tagoro9, @honzajavorek)[#3265]: Fixes regression in "watch" functionality introduced in v5.0.2 ([@outsideris])
This patch features a fix to address a potential "low severity" ReDoS vulnerability in the diff package (a dependency of Mocha).
This patch features a fix to address a potential "low severity" ReDoS vulnerability in the diff package (a dependency of Mocha).
generateDiff() in Base reporter (@harrysarson)This release fixes a class of tests which report as *false positives*. Certain tests will now break, though they would have previously been reported a
This release fixes a class of tests which report as false positives. Certain tests will now break, though they would have previously been reported as passing. Details below. Sorry for the inconvenience!
#3226: Do not swallow errors that are thrown asynchronously from passing tests (@boneskull). Example:
it('should actually fail, sorry!', function (done) {
// passing assertion
assert(true === true);
// test complete & is marked as passing
done();
// ...but something evil lurks within
setTimeout(() => {
throw new Error('chaos!');
}, 100);
});
Previously to this version, Mocha would have silently swallowed the chaos! exception, and you wouldn't know. Well, now you know. Mocha cannot recover from this gracefully, so it will exit with a nonzero code.
Maintainers of external reporters: If a test of this class is encountered, the Runner instance will emit the end event twice; you may need to change your reporter to use runner.once('end') intead of runner.on('end').
#3093: Fix stack trace reformatting problem (@outsideris)
browser-stdout to v1.3.1 (@honzajavorek)...your garden-variety patch release.
...your garden-variety patch release.
Special thanks to Wallaby.js for their continued support! :heart:
--delay now works with .only() (@silviom)--glob docs (@outsideris)Mocha starts off 2018 right by again dropping support for *unmaintained rubbish*.
Mocha starts off 2018 right by again dropping support for unmaintained rubbish.
Welcome @vkarpov15 to the team!
--file command line argument (documentation) (@hswolff)--no-timeouts docs (@dfberry)done() callback docs (@maraisr)README.md organization (@xxczaki)This is mainly a "housekeeping" release.
This is mainly a "housekeeping" release.
Welcome @Bamieh and @xxczaki to the team!
progress reporter now accepts reporter options (@canoztokmak)xit in bdd interface now properly returns its Test object (@Bamieh)--help will now help you even if you have a mocha.opts (@Zarel)--no-diff flag will completely disable diff output (@CapacitorSet)docs/ (@boneskull)[#3051]: Upgrade Growl to v1.10.3 to fix its peer dep problems ([@dpogue])
Your coding agent can read these notes before it upgrades. Set up the MCP server →