#4702: Error rethrow from cwd-relative path while loading .mocharc.js
(@kirill-golovan)
#4688: Usage of custom interface in parallel mode (@juergba)
#4687: ESM: don't swallow MODULE_NOT_FOUND
errors in case of type:module
(@giltayar)
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)
. 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)
Runner(suite: Suite, delay: boolean)
signature (@juergba)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.
require
interface (@alexander-fenster)EvalError
caused by regenerator-runtime (@snoack)import
from mocha in parallel mode (@nicojs)require
error when bundling Mocha with Webpack (@devhazem)Also thanks to @outsideris and @HyunSangHan for various fixes to our website and documentation.
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.
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-buffered
Runner.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!
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)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.
--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.
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.
enableTimeout()
(this.enableTimeout()
) from the context object (@craigtaub):sparkles: WORKAROUND: Replace usage of this.enableTimeout(false)
in your tests with this.timeout(0)
.
: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()
: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)
--forbid-only
does not recognize it.only
when before
crashes (@arvidOtt)#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)reporterOptions
(@holm)--debug
/--debug-brk
and deprecate debug
argument (@juergba)--list-interfaces
replaces --interfaces
--list-reporters
replaces --reporters
this.skip()
(@juergba):it
test, related afterEach
hooks are now executedbeforeEach
hook, subsequent inner beforeEach
hooks are now skipped and related afterEach
hooks are executedthis.skip()
within after
hooksgetOptions()
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-extensions
These 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)package.json
(@Munter)EVENT_RUN_END
events upon uncaught exception (@juergba)html
reporter (browser) (@pec9399)--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)yargs
-related global scope pollution (@inukshuk)pnpm
(@boneskull)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)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.
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)require
cache (@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)Documentation for this release can be found at next.mochajs.org!
Welcome @plroebuck, @craigtaub, & @markowsiak to the team!
--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: false
timeout: false
instead of enableTimeouts: false
All of the above deprecations were introduced by #3556.
mocha.opts
is now considered "legacy"; please prefer RC file or package.json
over mocha.opts
.
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.json
mocha.opts
Check out these example config files
Node/V8 flag support in mocha
executable:
Support all allowed 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
Use of e.g., --debug
will automatically invoke --inspect
if supported by running version of node
Support 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)
--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)mocha.opts
(@plroebuck)before
hooks when using --bail
(@outsideris)Buffer.from()
(@harrysarson)--watch
(@boneskull)Welcome @outsideris to the team!
--bail
failing to bail within hooks (@outsideris)describe.skip()
) (@outsideris)CHANGELOG.md
(@tagoro9, @honzajavorek)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 as passing. Details below. Sorry for the inconvenience!
```js 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')
.
browser-stdout
to v1.3.1 (@honzajavorek)...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.
Welcome @vkarpov15 to the team!
--file
command line argument (documentation) (@hswolff)--no-timeouts
docs (@dfberry)done()
callback docs (@maraisr)README.md
organization (@xxczaki)Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.