Configuring Mocha (Node.js)

Mocha supports configuration files, typical of modern command-line tools, in several formats:

JavaScript: Create a .mocharc.js (or .mocharc.cjs when using "type"="module" in your package.json) in your project’s root directory, and export an object (module.exports = {/* ... */}) containing your configuration. For native ESM and using type="module" or using .mjs, use a default export (export default {/* ... */}).
YAML: Create a .mocharc.yaml (or .mocharc.yml) in your project’s root directory.
JSON: Create a .mocharc.json (or .mocharc.jsonc) in your project’s root directory. Comments—while not valid JSON—are allowed in this file, and will be ignored by Mocha.
package.json: Create a mocha property in your project’s package.json.

Custom Locations

You can specify a custom location for your configuration file with the --config <path> option. Mocha will use the file’s extension to determine how to parse the file, and will assume JSON if unknown.

You can specify a custom package.json location as well, using the --package <path> option.

Parent Directory Lookup

If Mocha does not find a configuration file in the current working directory, it will search parent directories until one is found or the filesystem root is reached. The same applies when looking for package.json. This means a config file placed in a repository root will be used automatically when running Mocha from any subdirectory.

Ignoring Config Files

To skip looking for config files, use --no-config. Likewise, use --no-package to stop Mocha from looking for configuration in a package.json.

Priorities

If no custom path was given, and if there are multiple configuration files in the same directory, Mocha will search for—and use—only one. The priority is:

.mocharc.js
.mocharc.yaml
.mocharc.yml
.mocharc.jsonc
.mocharc.json

Environment Variables

The MOCHA_OPTIONS environment variable may be used to specify command line arguments. These arguments take priority over those found in configuration files.

For example, setting the bail and retries options:

$ MOCHA_OPTIONS="--bail --retries 3" mocha

Merging

Mocha will also merge any options found in package.json into its run-time configuration. In case of conflict, the priority is:

Arguments specified on command-line
Arguments specified in MOCHA_OPTIONS environment variable.
Configuration file (.mocharc.js, .mocharc.yml, etc.)
mocha property of package.json

Options which can safely be repeated (e.g., --require) will be concatenated, with higher-priority configuration sources appearing earlier in the list. For example, a .mocharc.json containing "require": "bar", coupled with execution of mocha --require foo, would cause Mocha to require foo, then bar, in that order.

This also includes spec. For example, a .mocharc.json containing "spec": ["**/*.test.js"] coupled with execution of mocha bar.spec.js would be the same as running mocha bar.spec.js **/*.test.js, and it would still run all .test.js files. To workaround this, you can comment out the spec property or use a different config file via --config.

Extending Configuration

Configurations can inherit from other modules using the extends keyword. See yargs API reference for more information.

Configuration Format

Any “boolean” flag (which doesn’t require a parameter, such as --bail), can be specified using a boolean value, e.g.: "bail": true.
Any “array”-type option (see mocha --help for a list) can be a single string value.
For options containing a dash (-), the option name can be specified using camelCase.
Aliases are valid names, e.g., R instead of reporter.
Test files can be specified using spec, e.g., "spec": "test/**/*.spec.js".
Flags to node are also supported in configuration files. Use caution, as these can vary between versions of Node.js!

For more configuration examples, see the example/config directory on GitHub.