Mocha

Mocha

new Mocha(optionsopt)

Source:

Constructs a new Mocha instance with options.

Parameters:
NameTypeAttributesDescription
optionsObject<optional>

Settings object.

Properties
NameTypeAttributesDescription
allowUncaughtboolean<optional>

Propagate uncaught errors?

asyncOnlyboolean<optional>

Force done callback or promise?

bailboolean<optional>

Bail after first test failure?

checkLeaksboolean<optional>

Check for global variable leaks?

colorboolean<optional>

Color TTY output from reporter?

delayboolean<optional>

Delay root suite execution?

diffboolean<optional>

Show diff on failure?

fgrepstring<optional>

Test filter given string.

forbidOnlyboolean<optional>

Tests marked only fail the suite?

forbidPendingboolean<optional>

Pending tests fail the suite?

fullTraceboolean<optional>

Full stacktrace upon failure?

globalArray:.<string:><optional>

Variables expected in global scope.

grepRegExp | string<optional>

Test filter given regular expression.

growlboolean<optional>

Enable desktop notifications?

inlineDiffsboolean<optional>

Display inline diffs?

invertboolean<optional>

Invert test filter matches?

noHighlightingboolean<optional>

Disable syntax highlighting?

reporterstring | constructor<optional>

Reporter name or constructor.

reporterOptionObject<optional>

Reporter settings object.

retriesnumber<optional>

Number of times to retry failed tests.

slownumber<optional>

Slow threshold value.

timeoutnumber | string<optional>

Timeout threshold value.

uistring<optional>

Interface name.

Classes

utils

Members

(static) exports.reporters

Source:

(static) exports.Runner

Source:

(readonly) version :string

Source:

Mocha version as specified by "package.json".

Type:
  • string

Methods

addFile(file) → {Mocha}

Adds file to be loaded for execution.

Source:
See:

Useful for generic setup code that must be included within test suite.

Parameters:
NameTypeDescription
filestring

Pathname of file to be loaded.

Returns:

this

Type
Mocha

allowUncaught(allowUncaughtopt) → {Mocha}

Source:
See:

Enables or disables uncaught errors to propagate.

Parameters:
NameTypeAttributesDefaultDescription
allowUncaughtboolean<optional>
true

Whether to propagate uncaught errors.

Returns:

this

Type
Mocha

asyncOnly(asyncOnlyopt) → {Mocha}

Source:
See:

Forces all tests to either accept a done callback or return a promise.

Parameters:
NameTypeAttributesDefaultDescription
asyncOnlyboolean<optional>
true

Wether to force done callback or promise.

Returns:

this

Type
Mocha

bail(bailopt) → {Mocha}

Source:
See:

Enables or disables bailing on the first failure.

Parameters:
NameTypeAttributesDefaultDescription
bailboolean<optional>
true

Whether to bail on first error.

Returns:

this

Type
Mocha

checkLeaks(checkLeaksopt) → {Mocha}

Source:
See:

Enables or disables checking for global variables leaked while running tests.

Parameters:
NameTypeAttributesDefaultDescription
checkLeaksboolean<optional>
true

Whether to check for global variable leaks.

Returns:

this

Type
Mocha

color(coloropt) → {Mocha}

Source:
See:

Enables or disables TTY color output by screen-oriented reporters.

Parameters:
NameTypeAttributesDefaultDescription
colorboolean<optional>
true

Whether to enable color output.

Returns:

this

Type
Mocha

delay() → {Mocha}

Delays root suite execution.

Source:
See:

Used to perform asynch operations before any suites are run.

Returns:

this

Type
Mocha

diff(diffopt) → {Mocha}

Source:
See:

Enables or disables reporter to include diff in test failure output.

Parameters:
NameTypeAttributesDefaultDescription
diffboolean<optional>
true

Whether to show diff on failure.

Returns:

this

Type
Mocha

enableTimeouts(enableTimeouts) → {Mocha}

Source:
See:

Enables or disables timeouts.

Parameters:
NameTypeDescription
enableTimeoutsboolean

Whether to enable timeouts.

Returns:

this

Type
Mocha

fgrep(str) → {Mocha}

Source:
See:

Sets grep filter after escaping RegExp special characters.

Example
// Select tests whose full title begins with `"foo"` followed by a period
mocha.fgrep('foo.');
Parameters:
NameTypeDescription
strstring

Value to be converted to a regexp.

Returns:

this

Type
Mocha

forbidOnly(forbidOnlyopt) → {Mocha}

Source:
See:

Causes tests marked only to fail the suite.

Parameters:
NameTypeAttributesDefaultDescription
forbidOnlyboolean<optional>
true

Whether tests marked only fail the suite.

Returns:

this

Type
Mocha

forbidPending(forbidPendingopt) → {Mocha}

Source:
See:

Causes pending tests and tests marked skip to fail the suite.

Parameters:
NameTypeAttributesDefaultDescription
forbidPendingboolean<optional>
true

Whether pending tests fail the suite.

Returns:

this

Type
Mocha

fullTrace(fullTraceopt) → {Mocha}

Source:
See:

Displays full stack trace upon test failure.

Parameters:
NameTypeAttributesDefaultDescription
fullTraceboolean<optional>
true

Whether to print full stacktrace upon failure.

Returns:

this

Type
Mocha

global(global) → {Mocha}

Source:
See:

Specifies whitelist of variable names to be expected in global scope.

Example
// Specify variables to be expected in global scope
mocha.global(['jQuery', 'MyLib']);
Parameters:
NameTypeDescription
globalArray:.<String:> | String

Accepted global variable name(s).

Returns:

this

Type
Mocha

grep(re) → {Mocha}

Sets grep filter used to select specific tests for execution.

Source:
See:

If re is a regexp-like string, it will be converted to regexp.
The regexp is tested against the full title of each test (i.e., the
name of the test preceded by titles of each its ancestral suites).
As such, using an exact-match fixed pattern against the
test name itself will not yield any matches.


Previous filter value will be overwritten on each call!

Examples
// Select tests whose full title contains `"match"`, ignoring case
mocha.grep(/match/i);
// Same as above but with regexp-like string argument
mocha.grep('/match/i');
// ## Anti-example
// Given embedded test `it('only-this-test')`...
mocha.grep('/^only-this-test$/');    // NO! Use `.only()` to do this!
Parameters:
NameTypeDescription
reRegExp | String

Regular expression used to select tests.

Returns:

this

Type
Mocha

growl() → {Mocha}

Source:
See:

Enables desktop notification support if prerequisite software installed.

Returns:

this

Type
Mocha

hideDiff(hideDiffopt) → {Mocha}

Source:
Deprecated:
  • since v7.0.0
See:

Determines if reporter should include diffs in test failure output.

Parameters:
NameTypeAttributesDefaultDescription
hideDiffboolean<optional>
false

Whether to hide diffs.

Returns:

this

Type
Mocha

ignoreLeaks(ignoreLeaksopt) → {Mocha}

Source:
Deprecated:
  • since v7.0.0
See:

Enables or disables ignoring global leaks.

Parameters:
NameTypeAttributesDefaultDescription
ignoreLeaksboolean<optional>
false

Whether to ignore global leaks.

Returns:

this

Type
Mocha

inlineDiffs(inlineDiffsopt) → {Mocha}

Source:
See:

Enables or disables reporter to use inline diffs (rather than +/-)
in test failure output.

Parameters:
NameTypeAttributesDefaultDescription
inlineDiffsboolean<optional>
true

Whether to use inline diffs.

Returns:

this

Type
Mocha

invert() → {Mocha}

Source:
See:

Inverts grep matches.

Example
// Select tests whose full title does *not* contain `"match"`, ignoring case
mocha.grep(/match/i).invert();
Returns:

this

Type
Mocha

noHighlighting() → {Mocha}

Source:

Disables syntax highlighting (in browser).

Returns:

this

Type
Mocha

reporter(reporter, reporterOptionsopt) → {Mocha}

Source:
See:

Sets reporter to reporter, defaults to "spec".

Example
// Use XUnit reporter and direct its output to file
mocha.reporter('xunit', { output: '/path/to/testspec.xunit.xml' });
Parameters:
NameTypeAttributesDescription
reporterString | function

Reporter name or constructor.

reporterOptionsObject<optional>

Options used to configure the reporter.

Throws:

if requested reporter cannot be loaded

Type
Error
Returns:

this

Type
Mocha

retries(retry) → {Mocha}

Source:
See:

Sets the number of times to retry failed tests.

Example
// Allow any failed test to retry one more time
mocha.retries(1);
Parameters:
NameTypeDescription
retrynumber

Number of times to retry failed tests.

Returns:

this

Type
Mocha

run(fnopt) → {Runner}

Source:
See:

To run tests multiple times (or to run tests in files that are
already in the require cache), make sure to clear them from
the cache first!

Parameters:
NameTypeAttributesDescription
fnDoneCB<optional>

Callback invoked when test execution completed.

Returns:

runner instance

Type
Runner

slow(msecs) → {Mocha}

Source:
See:

Sets slowness threshold value.

Examples
// Sets "slow" threshold to half a second
mocha.slow(500);
// Same as above but using string argument
mocha.slow('0.5s');
Parameters:
NameTypeDescription
msecsnumber

Slowness threshold value.

Returns:

this

Type
Mocha

timeout(msecs) → {Mocha}

Sets timeout threshold value.

Source:
See:

A string argument can use shorthand (such as "2s") and will be converted.
If the value is 0, timeouts will be disabled.

Examples
// Sets timeout to one second
mocha.timeout(1000);
// Same as above but using string argument
mocha.timeout('1s');
Parameters:
NameTypeDescription
msecsnumber | string

Timeout threshold value.

Returns:

this

Type
Mocha

ui(uiopt) → {Mocha}

Source:
See:

Sets test UI name, defaults to "bdd".

Parameters:
NameTypeAttributesDefaultDescription
uistring | function<optional>
bdd

Interface name or class.

Throws:

if requested interface cannot be loaded

Type
Error
Returns:

this

Type
Mocha

unloadFiles() → {Mocha}

Source:
See:

This allows files to be "freshly" reloaded, providing the ability
to reuse a Mocha instance programmatically.

Intended for consumers — not used internally

Returns:

this

Type
Mocha

useColors(colors) → {Mocha}

Source:
Deprecated:
  • since v7.0.0
See:

Enables or disables TTY color output by screen-oriented reporters.

Parameters:
NameTypeDescription
colorsboolean

Whether to enable color output.

Returns:

this

Type
Mocha

useInlineDiffs(inlineDiffsopt) → {Mocha}

Source:
Deprecated:
  • since v7.0.0
See:

Determines if reporter should use inline diffs (rather than +/-)
in test failure output.

Parameters:
NameTypeAttributesDefaultDescription
inlineDiffsboolean<optional>
false

Whether to use inline diffs.

Returns:

this

Type
Mocha