Option reference

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

Command-line arguments
.mocharc.js
.mocharc.ya?ml
.mocharc.json
.mocharc.jsonc
package.json (mocha property of top-level object)
mocha.opts

afterTest / beforeTest / onFail / onPass
headless / interactive
mocha
noExtensions
optFiles
specPattern
snapshotDir
tests

Reporter-specific:

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

afterTest / beforeTest / onFail / onPass

.mocharc.js only
Lifecycle hooks that behave similarly to Mocha's beforeEach() and afterEach() hooks, but are guaranteed to run before any other hook. onFail and onPass are called for every test which fails or passes, respectively, and run before afterTest().

Handlers are called with two parameters: the Mocha.Runnable instance (test object), and the exception which triggered its failure (if any).

// .mocharc.js
module.exports = {
	onFail(test, error){
		debugger;
	},
};

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.

snapshotDir

A directory in which to store screen-captures taken automatically after failed tests. If the path does not exist, it will be created. Moreover, setting this option enables the aforementioned auto-capture feature, with each individual snapshot saved to:

`${options.snapshotDir}/${CURRENT_DATE}/${FAILURE_NUMBER}.{png,html,json}`

For example, given a snapshotDir of /tmp/atom-tests, the second failed test will be saved to:

/tmp/atom-tests/2021-08-08T03-06-05.811Z/2.png
/tmp/atom-tests/2021-08-08T03-06-05.811Z/2.html
/tmp/atom-tests/2021-08-08T03-06-05.811Z/2.json

The HTML file saved with the screen-capture image is a scrape of the DOM following the respective test failure (specifically, document.documentElement.outerHTML). The JSON file contains metadata identifying the failed test and the stack trace of the relevant error:

{
	"test": [
		"Suite title",
		"it breaks something"
	],
	"file": "/Users/Alhadis/Labs/Atom-Mocha/spec/basic-spec.js",
	"error": "ReferenceError: something is not defined\n    at Context.<anonymous> (…)",
	"snapshot": {
		"img": "/tmp/atom-tests/2021-08-08T03-06-05.811Z/2.png",
		"dom": "/tmp/atom-tests/2021-08-08T03-06-05.811Z/2.html"
	}
}

This feature exists mainly to facilitate cross-platform testing in headless environments, especially in CI environments. Note that snapshots will (usually) not be retained by most CI providers: remember to tailor your configuration appropriately. For example, using AppVeyor:

# .mocharc.yml
snapshotDir: .atom-mocha

# appveyor.yml
on_finish:
  - ps: |
      if(Get-ChildItem '.atom-mocha/**/*.json' -ErrorAction Ignore){
          7z a -t7z -m0=lzma -mx=9 -mfb=64 -md=32m -ms=on screenshots.7z .atom-mocha
          Push-AppveyorArtifact screenshots.7z -FileName "$env:APPVEYOR_JOB_ID-screenshots.7z"
      }

If finer control is desired, call AtomMocha.snapshot() directly:

const pathBase = require("os").homedir() + "/workspace";
const format   = "jpg";
const quality  = 100;

const {
	img, // ~/workspace.jpg
	dom, // ~/workspace.html
} = await AtomMocha.snapshot(pathBase, format, quality);

snapshotFormat

Default: png
File format used when generating screen-captures via snapshotDir. May be one of png, pdf, or jpg/jpeg.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

options.md

options.md

Option reference

afterTest / beforeTest / onFail / onPass

headless / interactive

mocha (`package.json` only)

noExtensions

optFiles

snapshotDir

snapshotFormat

specPattern

tests

Reporter-specific

autoIt

autoScroll

clipPaths

css / js

escapeHTML

flipStack

formatCode

hidePending

hideStatBar

linkPaths

minimal

opacity

slide

stackFilter

title

Files

options.md

Latest commit

History

options.md

File metadata and controls

Option reference

afterTest / beforeTest / onFail / onPass

headless / interactive

mocha (package.json only)

noExtensions

optFiles

snapshotDir

snapshotFormat

specPattern

tests

Reporter-specific

autoIt

autoScroll

clipPaths

css / js

escapeHTML

flipStack

formatCode

hidePending

hideStatBar

linkPaths

minimal

opacity

slide

stackFilter

title

mocha (`package.json` only)