Mocha

Mocha

new Mocha(optionsopt)

Source:

Constructs a new Mocha instance with options.

Parameters:
Name Type Attributes Description
options Object <optional>

Settings object.

Properties
Name Type Attributes Description
allowUncaught boolean <optional>

Propagate uncaught errors?

asyncOnly boolean <optional>

Force done callback or promise?

bail boolean <optional>

Bail after first test failure?

checkLeaks boolean <optional>

If true, check leaks.

delay boolean <optional>

Delay root suite execution?

enableTimeouts boolean <optional>

Enable timeouts?

fgrep string <optional>

Test filter given string.

forbidOnly boolean <optional>

Tests marked only fail the suite?

forbidPending boolean <optional>

Pending tests fail the suite?

fullStackTrace boolean <optional>

Full stacktrace upon failure?

global Array:.<string:> <optional>

Variables expected in global scope.

grep RegExp | string <optional>

Test filter given regular expression.

growl boolean <optional>

Enable desktop notifications?

hideDiff boolean <optional>

Suppress diffs from failures?

ignoreLeaks boolean <optional>

Ignore global leaks?

invert boolean <optional>

Invert test filter matches?

noHighlighting boolean <optional>

Disable syntax highlighting?

reporter string <optional>

Reporter name.

reporterOption Object <optional>

Reporter settings object.

retries number <optional>

Number of times to retry failed tests.

slow number <optional>

Slow threshold value.

timeout number | string <optional>

Timeout threshold value.

ui string <optional>

Interface name.

color boolean <optional>

Color TTY output from reporter?

useInlineDiffs boolean <optional>

Use inline diffs?

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:
Name Type Description
file string

Pathname of file to be loaded.

Returns:

this

Type
Mocha

allowUncaught() → {Mocha}

Source:

Enables uncaught errors to propagate (in browser).

Returns:

this

Type
Mocha

asyncOnly() → {Mocha}

Source:

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

Returns:

this

Type
Mocha

bail(bailopt) → {Mocha}

Source:
See:

Enables or disables bailing on the first failure.

Parameters:
Name Type Attributes Default Description
bail boolean <optional>
true

Whether to bail on first error.

Returns:

this

Type
Mocha

checkLeaks() → {Mocha}

Source:
See:

Enables checking for global variables leaked while running tests.

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

enableTimeouts(enableTimeouts) → {Mocha}

Source:
See:

Enables or disables timeouts.

Parameters:
Name Type Description
enableTimeouts boolean

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:
Name Type Description
str string

Value to be converted to a regexp.

Returns:

this

Type
Mocha

forbidOnly() → {Mocha}

Source:

Causes tests marked only to fail the suite.

Returns:

this

Type
Mocha

forbidPending() → {Mocha}

Source:

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

Returns:

this

Type
Mocha

fullTrace() → {Mocha}

Source:

Displays full stack trace upon test failure.

Returns:

this

Type
Mocha

globals(globals) → {Mocha}

Source:
See:

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

Example
// Specify variables to be expected in global scope
mocha.globals(['jQuery', 'MyLib']);
Parameters:
Name Type Description
globals Array:.<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:
Name Type Description
re RegExp | String

Regular expression used to select tests.

Returns:

this

Type
Mocha

growl() → {Mocha}

Source:
See:
  • Mocha#isGrowlCapable
  • Mocha#_growl

Enables desktop notification support if prerequisite software installed.

Returns:

this

Type
Mocha

hideDiff(hideDiff) → {Mocha}

Source:

Determines if reporter should include diffs in test failure output.

Parameters:
Name Type Description
hideDiff boolean

Whether to hide diffs.

Returns:

this

Type
Mocha

ignoreLeaks(ignoreLeaks) → {Mocha}

Source:
See:

Enables or disables ignoring global leaks.

Example
// Ignore global leaks
mocha.ignoreLeaks(true);
Parameters:
Name Type Description
ignoreLeaks boolean

Whether to ignore global leaks.

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:
Name Type Attributes Description
reporter String | function

Reporter name or constructor.

reporterOptions Object <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:
Name Type Description
retry number

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:
Name Type Attributes Description
fn DoneCB <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:
Name Type Description
msecs number

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:
Name Type Description
msecs number | string

Timeout threshold value.

Returns:

this

Type
Mocha

ui(uiopt) → {Mocha}

Source:
See:

Sets test UI name, defaults to "bdd".

Parameters:
Name Type Attributes Default Description
ui string | 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:

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

Parameters:
Name Type Description
colors boolean

Whether to enable color output.

Returns:

this

Type
Mocha

useInlineDiffs(inlineDiffs) → {Mocha}

Source:

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

Parameters:
Name Type Description
inlineDiffs boolean

Whether to use inline diffs.

Returns:

this

Type
Mocha