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>

Check for global variable leaks?
color boolean <optional>

Color TTY output from reporter?
delay boolean <optional>

Delay root suite execution?
diff boolean <optional>

Show diff on failure?
dryRun boolean <optional>

Report tests without running them?
passOnFailingTestSuite boolean <optional>

Fail test run if tests were failed?
failZero boolean <optional>

Fail test run if zero tests?
fgrep string <optional>

Test filter given string.
forbidOnly boolean <optional>

Tests marked only fail the suite?
forbidPending boolean <optional>

Pending tests fail the suite?
fullTrace boolean <optional>

Full stacktrace upon failure?
global Array:.<string:> <optional>

Variables expected in global scope.
grep RegExp | string <optional>

Test filter given regular expression.
inlineDiffs boolean <optional>

Display inline diffs?
invert boolean <optional>

Invert test filter matches?
noHighlighting boolean <optional>

Disable syntax highlighting?
reporter string | constructor <optional>

Reporter name or constructor.
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.
parallel boolean <optional>

Run jobs in parallel.
jobs number <optional>

Max number of worker processes for parallel runs.
rootHooks MochaRootHookObject <optional>

Hooks to bootstrap the root suite with.
require Array:.<string:> <optional>

Pathname of rootHooks plugin for parallel runs.
isWorker boolean <optional>

Should be true if Mocha process is running in a worker process.

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(allowUncaughtopt) → {Mocha}

Source:
See:

Enables or disables uncaught errors to propagate.

Parameters:
Name Type Attributes Default Description
allowUncaught boolean <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:
Name Type Attributes Default Description
asyncOnly boolean <optional>
 true

Whether to force done callback or 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(checkLeaksopt) → {Mocha}

Source:
See:

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

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

Whether to check for global variable leaks.
Returns:

this

Type
Mocha

cleanReferencesAfterRun(cleanReferencesAfterRun) → {Mocha}

Source:
See:

Enables or disables whether or not to dispose after each test run.
Disable this to ensure you can run the test suite multiple times.
If disabled, be sure to dispose mocha when you're done to prevent memory leaks.

Parameters:
Name Type Description
cleanReferencesAfterRun boolean
Returns:

this

Type
Mocha

color(coloropt) → {Mocha}

Source:
See:

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

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

Whether to enable color output.
Returns:

this

Type
Mocha

delay() → {Mocha}

Delays root suite execution.

Source:
See:

Used to perform async 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:
Name Type Attributes Default Description
diff boolean <optional>
 true

Whether to show diff on failure.
Returns:

this

Type
Mocha

dispose()

Source:

Manually dispose this mocha instance. Mark this instance as disposed and unable to run more tests.
It also removes function references to tests functions and hooks, so variables trapped in closures can be cleaned by the garbage collector.

dryRun(dryRunopt) → {Mocha}

Source:
See:

Enables or disables running tests in dry-run mode.

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

Whether to activate dry-run mode.
Returns:

this

Type
Mocha

enableGlobalSetup(enabledopt) → {Mocha}

Source:

Toggle execution of any global setup fixture(s)

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

If false, do not run global setup fixture
Returns:
Type
Mocha

enableGlobalTeardown(enabledopt) → {Mocha}

Source:

Toggle execution of any global teardown fixture(s)

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

If false, do not run global teardown fixture
Returns:
Type
Mocha

failZero(failZeroopt) → {Mocha}

Source:
See:

Fails test run if no tests encountered with exit-code 1.

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

Whether to fail test run.
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(forbidOnlyopt) → {Mocha}

Source:
See:

Causes tests marked only to fail the suite.

Parameters:
Name Type Attributes Default Description
forbidOnly boolean <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:
Name Type Attributes Default Description
forbidPending boolean <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:
Name Type Attributes Default Description
fullTrace boolean <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:
Name Type Description
global Array:.<String:> | String

Accepted global variable name(s).
Returns:

this

Type
Mocha

globalSetup(setupFnsopt) → {Mocha}

Source:

Configures one or more global setup fixtures.

If given no parameters, unsets any previously-set fixtures.

Parameters:
Name Type Attributes Description
setupFns MochaGlobalFixture | Array:.<MochaGlobalFixture:> <optional>

Global setup fixture(s)
Returns:
Type
Mocha

globalTeardown(teardownFnsopt) → {Mocha}

Source:

Configures one or more global teardown fixtures.

If given no parameters, unsets any previously-set fixtures.

Parameters:
Name Type Attributes Description
teardownFns MochaGlobalFixture | Array:.<MochaGlobalFixture:> <optional>

Global teardown fixture(s)
Returns:
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

hasGlobalSetupFixtures() → {boolean}

Source:

Returns true if one or more global setup fixtures have been supplied.

Returns:
Type
boolean

hasGlobalTeardownFixtures() → {boolean}

Source:

Returns true if one or more global teardown fixtures have been supplied.

Returns:
Type
boolean

inlineDiffs(inlineDiffsopt) → {Mocha}

Source:
See:

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

Parameters:
Name Type Attributes Default Description
inlineDiffs boolean <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

lazyLoadFiles(enableopt)

Source:
To Do:
  • This should throw if we've already loaded files; such behavior necessitates adding a new state.

Disables implicit call to Mocha#loadFiles in Mocha#run. This
setting is used by watch mode, parallel mode, and for loading ESM files.

Parameters:
Name Type Attributes Description
enable boolean <optional>

If true, disable eager loading of files in
Mocha#run

loadFilesAsync(optionsopt) → {Promise}

Source:
See:

The implementation relies on Node's require and import to execute
the test interface functions and will be subject to its cache.
Supports both CJS and ESM modules.

Example
// loads ESM (and CJS) test files asynchronously, then runs root suite
mocha.loadFilesAsync()
  .then(() => mocha.run(failures => process.exitCode = failures ? 1 : 0))
  .catch(() => process.exitCode = 1);
Parameters:
Name Type Attributes Description
options Object <optional>

Settings object.

Properties
Name Type Attributes Description
esmDecorator function <optional>

Function invoked on esm module name right before importing it. By default will passthrough as is.
Returns:
Type
Promise

noHighlighting() → {Mocha}

Source:

Disables syntax highlighting (in browser).

Returns:

this

Type
Mocha

parallelMode(enableopt) → {Mocha}

Source:

Toggles parallel mode.

Must be run before calling Mocha#run. Changes the Runner class to
use; also enables lazy file loading if not already done so.

Warning: when passed false and lazy loading has been enabled via any means (including calling parallelMode(true)), this method will not disable lazy loading. Lazy loading is a prerequisite for parallel
mode, but parallel mode is not a prerequisite for lazy loading!

Parameters:
Name Type Attributes Description
enable boolean <optional>

If true, enable; otherwise disable.
Throws:

  • If run in browser

  • If Mocha not in INIT state

Returns:
Type
Mocha

passOnFailingTestSuite(passOnFailingTestSuiteopt) → {Mocha}

Source:
See:

Fail test run if tests were failed.

Parameters:
Name Type Attributes Default Description
passOnFailingTestSuite boolean <optional>
 false

Whether to fail test run.
Returns:

this

Type
Mocha

reporter(reporterName, 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
reporterName 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

rootHooks(hooksopt)

Source:

Assigns hooks to the root suite

Parameters:
Name Type Attributes Description
hooks MochaRootHookObject <optional>

Hooks to assign to root suite

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!

Example
// exit with non-zero status if there were test failures
mocha.run(failures => process.exitCode = failures ? 1 : 0);
Parameters:
Name Type Attributes Description
fn DoneCB <optional>

Callback invoked when test execution completed.
Returns:

runner instance

Type
Runner

runGlobalSetup(contextopt) → {Promise:.<object:>}

Source:

Run any global setup fixtures sequentially, if any.

This is automatically called by Mocha#run unless the runGlobalSetup option is false; see Mocha#enableGlobalSetup.

The context object this function resolves with should be consumed by Mocha#runGlobalTeardown.

Parameters:
Name Type Attributes Description
context object <optional>

Context object if already have one
Returns:

Context object

Type
Promise:.<object:>

runGlobalTeardown(contextopt) → {Promise:.<object:>}

Source:

Run any global teardown fixtures sequentially, if any.

This is automatically called by Mocha#run unless the runGlobalTeardown option is false; see Mocha#enableGlobalTeardown.

Should be called with context object returned by Mocha#runGlobalSetup, if applicable.

Parameters:
Name Type Attributes Description
context object <optional>

Context object if already have one
Returns:

Context object

Type
Promise:.<object:>

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 required files to be "freshly" reloaded, providing the ability
to reuse a Mocha instance programmatically.
Note: does not clear ESM module files from the cache

Intended for consumers — not used internally

Returns:

this

Type
Mocha