new Mocha(optionsopt)
Constructs a new Mocha instance with options
.
Parameters:
Classes
Members
(static) exports.reporters
(static) exports.Runner
(readonly) version :string
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 | Wether to force |
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
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 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:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
diff | boolean | <optional> | true | Whether to show diff on failure. |
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(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 |
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
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:
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:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
hideDiff | boolean | <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:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
ignoreLeaks | boolean | <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:
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
noHighlighting() → {Mocha}
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.
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}
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:
Name | Type | Description |
---|---|---|
colors | boolean | 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:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
inlineDiffs | boolean | <optional> | false | Whether to use inline diffs. |
Returns:
this
- Type
- Mocha