options.md

Option reference

Options are sourced from the following locations, in descending order of priority:

1. Command-line arguments
2. .mocharc.js
3. .mocharc.ya?ml
4. .mocharc.json
5. .mocharc.jsonc
6. package.json (mocha property of top-level object)
7. mocha.opts

• headless / interactive
• mocha
• noExtensions
• optFiles
• specPattern
• tests

Reporter-specific:

• autoIt
• autoScroll
• clipPaths
• css / js
• escapeHTML
• flipStack
• formatCode
• hidePending
• hideStatBar
• linkPaths
• minimal
• opacity
• slide
• stackFilter
• title

headless / interactive

package.json only
Allows different configurations to target different environments.

For instance, perhaps you'd like headless tests to use Mocha's landing reporter:

"atom-mocha": {
	"headless": {
		"mocha": {"reporter": "landing"}
	}
}

Anything that's valid for atom-mocha is also valid for headless or interactive.

mocha (package.json only)

⚠️ DEPRECATION WARNING:⚠️

Mocha v6 introduced support for package.json hosted configuration, but reads properties from the "mocha" key of the top-level JSON object. Having options for Mocha pulled from "atom‑mocha": "mocha" is now confusing and redundant, and we strongly recommend moving any Mocha settings you had to the mocha property of your package.json file.

This and many more changes are due to be made to the package's configuration in the next major release. See Alhadis/Atom-Mocha#3 for discussion and details.

An object containing Mocha configuration settings. For example:

"mocha": {
	"bail": true,
	"grep": "/(^tokenises|strings)\\b/i",
	"reporter": "landing",
	"retries": 1
}

The reporter option defaults to whatever makes sense for the running environment. Headless tests use Mocha's spec reporter, while interactive tests use the bespoke TTY-styled reporter. These defaults are also used if an environment doesn't support a reporter's output (such as HTML in terminal, or monospaced/SGR-coloured patterns in interactive mode).

Note that requesting the dot reporter will implicitly enable the minimal setting of the default HTML reporter.

noExtensions

Disables the loading of extensions.js. Consult the extensions reference for details of what this entails.

optFiles

An array of paths pointing to mocha.opts files to load. Only needed if your mocha.opts file is located in a different directory to your specs.

Note: This package is currently limited to loading one mocha.opts at once. This limitation may be fixed in future to permit directory-specific configurations.

specPattern

A regular expression that determines which files are loaded as specs. Default pattern:

/[-_.](?:spec|test)\.(?:coffee|[jt]sx?)$/i

Which matches any of the following filenames:

matched.test.js
matched-spec.coffee
MATCHED.TEST.CofFEE
also_a_spec.js
not-used.js

tests

package.json only
An array of additional specs to load. These may be directories or individual files.

"atom-mocha": {
	"tests": [
		"./spec/subfolder/",
		"./spec/adhoc.js"
	]
}

Paths are relative to the package's root directory.

Reporter-specific

The following options are specific to the default reporter only; they do nothing for other reporters (such as Mocha's HTML reporter).

autoIt

Default: Enabled (since v2.2.0)
Prepend It to the name of every test. See mocha-when for details.

it("runs a test", () => {});

Only applicable when Mocha's ui setting is set to bdd.

autoScroll

Default: Enabled
Automatically scroll to tests when they finish.

To disable this in a mocha.opts file, use --no-auto-scroll.

clipPaths

Default: Enabled
Make stack traces less noisy by removing the package's base directory:

To disable this in a mocha.opts file, use --no-clip-paths.

css / js

Paths to extra stylesheets or scripts to attach to the spec-runner.

"atom-mocha": {
	"css": "spec/assets/some custom counter.less",
	"js": [
		"node_modules/less/dist/less.min.js",
		"node_modules/annoying-nyan-cat/nyan.js"
	]
}

This provides an extension point for authors wishing to extend or modify the default reporter.

Paths are relative to whatever file defines them. So to write the above example in mocha.opts, you'd write this:

--css assets/some%20custom%20counter.less
--js node_modules/less/dist/less.min.js node_modules/annoying-nyan-cat/nyan.js

Note the use of %20 to encode spaces in the first filename.

escapeHTML

Default: Enabled
Escape < > & in failed assertion titles.

Generally, this is desired and expected behaviour. Depending on what you're testing, however, it may be cleaner to show embedded HTML:

To disable this setting in a mocha.opts file, use --no-escape-html.

flipStack

Print stack traces in reverse order, placing more recent calls at the bottom.

formatCode

Default: Enabled
Prettify the contents of embedded JavaScript snippets.

The specific effects of this option are:

• Removal of containing function headers
• Normalised indentation
• Syntax highlighting (using Atom's JavaScript grammar)

To disable this option in a mocha.opts file, use --no-format-code.

hidePending

Hide all mention of pending tests in Mocha's output.

hideStatBar

Hide the statbar at the bottom of the window.

linkPaths

Default: Enabled
Link sources in stack-traces to their offending lines of code when clicked on.

To disable this option in a mocha.opts file, use --no-link-paths.

minimal

Use dots to represent each test, highlighting failures.

opacity

Default: 0.8
Set the translucency of the feedback layer. This probably only matters if you're attaching elements with attachToDOM.

slide

Default: true
Allow the feedback layer to be toggled away, exposing anything added underneath (such as workspaces added with attachToDOM).

This is intended to help debug failed tests by making the DOM easier to examine. Works well with Mocha's --bail.

To restrict sliding to certain edges, pass any combination of up, down, left and right. Passing false disables sliding completely.

To disable sliding in a mocha.opts file, use --no-slide.

stackFilter

Default: /node_modules([\\\/])mocha(?:\1|\.js|[:\)])/
RegExp to filter unwanted lines from stack traces.

title

Title of the spec-runner window. Defaults to "Mocha".