Configuring Mocha(node.js)

In the last tutorial, you were treated "desktop notifications", in this tutorial we will walk you through the process of configuring Mocha in node.js.

The ability to configure mocha in node.js came with the version 6.0.0 of Mocha. Added to supporting the legacy mocha.opts run-control format, mocha currently supports configuration files, this is typical of modern command-line tools, in several formats as shown below:

  • JavaScript: You should create a .mocharc.js in your project's root directory, and then export an object (module.exports = {/* ... */}) containing your configuration.
  • YAML: You should create a .mocharc.yaml (or .mocharc.yml) in your project's root directory.
  • JSON: You should create a .mocharc.json (or .mocharc.jsonc) in your project's root directory. Comments - though they are not valid JSON - are allowed in this file, and are ignored by Mocha.
  • package.json: You should not create a mocha property in your project's package.json.

mocha recommends that you use one of the above strategies for configuration rather than the legacy mocha.opts format.

Custom locations

It is possible to specify a custom location for your configuration file; this is achieved using the ?config <path> option. Mocha uses the files extension to determine how to parse the file, and will assume JSON when the file extension is unknown.

You can also specify a custom package.json location, by using the ?package option.

Ignoring config files

If you want to skip the search for config files, you should use -no-config. Similarly, you can use ?no-package to stop Mocha form looking for configuration in a package.json.


When there is no custom path was given and there are multiple configuration files in the same directory, Mocha searches for - and will use - only one. The priority will be:

  1. .mocharc.js
  2. .mocharc.yaml
  3. .mocharc.yml
  4. .mocharc.jsonc
  5. .mocharc.json,


Mocha also merges any options found in package.json and mocha.opts into mocha's run-time configuration. However, when there is a conflict, the priority will be:

  1. The arguments specified on command-line
  2. The configuration file (.mocharc.js, .mocharc.yml, etc.)
  3. The mocha property of package.json
  4. mocha.opts

Options which can safely be repeated (e.g., --require) are concatenated, with higher-priorty configuration sources appearing earlier in the list. For instance, a .mocharc.json that contains "require": "bar", added to the execution of mocha --require foo, would make Mocha to require foo, then bar, in that order.

Extending configuration

Configurations can inherit from other modules by using the extends keyword.

Configuration format

  • Any "boolean" flag (which does not require a parameter, such as --bail), can be specified by using a boolean value, e.g.: "bail": true.
  • Any "array"-type option (run mocha --help for a list) can be a single string value.
  • For options that contains a dash (-), you can specify the option name using camelCase.
  • Aliases are also valid names, e.g., R rather rthan reporter.
  • You can specify Test files using spec, e.g., "spec": "test/**/*.spec.js".
  • Flags to node are supported in configuration files as well, such as in mocha.opts. you should use caution, as these may vary between versions of Node.js!

Follow us on Facebook and Twitter for latest update.