Skip to content
Mocha

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.
  • 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.

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:

  1. .mocharc.js
  2. .mocharc.yaml
  3. .mocharc.yml
  4. .mocharc.jsonc
  5. .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:

Terminal window
$ 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:

  1. Arguments specified on command-line
  2. Arguments specified in MOCHA_OPTIONS environment variable.
  3. Configuration file (.mocharc.js, .mocharc.yml, etc.)
  4. 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 runninng 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.