☕️ Classic, reliable, trusted test framework for Node.js and the browser
add createInvalidArgumentError(); see #3676 (#3677)
Christopher Hiller186ca3657b4d
diff --git a/docs/index.md b/docs/index.mdindex 7bfe5895..f3d775f6 100644--- a/docs/index.md+++ b/docs/index.md@@ -3,7 +3,8 @@ layout: defaulttitle: 'Mocha - the fun, simple, flexible JavaScript test framework'description: 'Mocha is a feature-rich JavaScript test framework running on Node.js and in the browser, making asynchronous testing simple and fun.'----Mocha is a feature-rich JavaScript test framework running on [Node.js](https://nodejs.org) and in the browser, making asynchronous testing *simple* and *fun*. Mocha tests run serially, allowing for flexible and accurate reporting, while mapping uncaught exceptions to the correct test cases. Hosted on [GitHub](https://github.com/mochajs/mocha).++Mocha is a feature-rich JavaScript test framework running on [Node.js](https://nodejs.org) and in the browser, making asynchronous testing _simple_ and _fun_. Mocha tests run serially, allowing for flexible and accurate reporting, while mapping uncaught exceptions to the correct test cases. Hosted on [GitHub](https://github.com/mochajs/mocha).<nav class="badges"><a href="https://gitter.im/mochajs/mocha"><img src="/images/join-chat.svg" alt="Gitter"></a>@@ -114,7 +115,7 @@ var assert = require('assert');describe('Array', function() {describe('#indexOf()', function() {it('should return -1 when the value is not present', function() {- assert.equal([1,2,3].indexOf(4), -1);+ assert.equal([1, 2, 3].indexOf(4), -1);});});});@@ -152,7 +153,7 @@ $ npm testA brief outline on the order Mocha's components are executed.Worth noting that all hooks, `describe` and `it` callbacks are run in the order they are defined (i.e. found in the file).-``` js+```jsrun 'mocha spec.js'|spawn child process@@ -223,17 +224,17 @@ $ ./node_modules/.bin/mocha mocha.test.js## Assertions-Mocha allows you to use any assertion library you wish. In the above example, we're using Node.js' built-in [assert](https://nodejs.org/api/assert.html) module--but generally, if it throws an `Error`, it will work! This means you can use libraries such as:+Mocha allows you to use any assertion library you wish. In the above example, we're using Node.js' built-in [assert](https://nodejs.org/api/assert.html) module--but generally, if it throws an `Error`, it will work! This means you can use libraries such as:- [should.js](https://github.com/shouldjs/should.js) - BDD style shown throughout these docs- [expect.js](https://github.com/LearnBoost/expect.js) - `expect()` style assertions- [chai](http://chaijs.com/) - `expect()`, `assert()` and `should`-style assertions-- [better-assert](https://github.com/visionmedia/better-assert) - C-style self-documenting `assert()`+- [better-assert](https://github.com/visionmedia/better-assert) - C-style self-documenting `assert()`- [unexpected](http://unexpected.js.org) - "the extensible BDD assertion toolkit"## Asynchronous Code-Testing asynchronous code with Mocha could not be simpler! Simply invoke the callback when your test is complete. By adding a callback (usually named `done`) to `it()`, Mocha will know that it should wait for this function to be called to complete the test. This callback accepts both an `Error` instance (or subclass thereof) *or* a falsy value; anything else will cause a failed test.+Testing asynchronous code with Mocha could not be simpler! Simply invoke the callback when your test is complete. By adding a callback (usually named `done`) to `it()`, Mocha will know that it should wait for this function to be called to complete the test. This callback accepts both an `Error` instance (or subclass thereof) _or_ a falsy value; anything else will cause a failed test.```jsdescribe('User', function() {@@ -249,7 +250,7 @@ describe('User', function() {});```-To make things even easier, the `done()` callback also accepts an `Error` instance (i.e. `new Error()`), so we may use this directly:+Alternatively, just use the `done()` callback directly (which will handle an error argument, if it exists):```jsdescribe('User', function() {@@ -268,36 +269,35 @@ Alternately, instead of using the `done()` callback, you may return a [Promise](```jsbeforeEach(function() {- return db.clear()- .then(function() {- return db.save([tobi, loki, jane]);- });+ return db.clear().then(function() {+ return db.save([tobi, loki, jane]);+ });});describe('#find()', function() {it('respond with matching records', function() {- return db.find({ type: 'User' }).should.eventually.have.length(3);+ return db.find({type: 'User'}).should.eventually.have.length(3);});});```> The latter example uses [Chai as Promised](https://www.npmjs.com/package/chai-as-promised) for fluent promise assertions.-In Mocha v3.0.0 and newer, returning a `Promise` *and* calling `done()` will result in an exception, as this is generally a mistake:+In Mocha v3.0.0 and newer, returning a `Promise` _and_ calling `done()` will result in an exception, as this is generally a mistake:```jsconst assert = require('assert');-it('should complete this test', function (done) {- return new Promise(function (resolve) {+// antipattern+it('should complete this test', function(done) {+ return new Promise(function(resolve) {assert.ok(true);resolve();- })- .then(done);+ }).then(done);});```-The above test will fail with `Error: Resolution method is overspecified. Specify a callback *or* return a Promise; not both.`. In versions older than v3.0.0, the call to `done()` is effectively ignored.+The above test will fail with `Error: Resolution method is overspecified. Specify a callback *or* return a Promise; not both.`. In versions older than v3.0.0, the call to `done()` is effectively ignored.### Using async / await@@ -311,7 +311,7 @@ beforeEach(async function() {describe('#find()', function() {it('responds with matching records', async function() {- const users = await db.find({ type: 'User' });+ const users = await db.find({type: 'User'});users.should.have.length(3);});});@@ -325,8 +325,8 @@ When testing synchronous code, omit the callback and Mocha will automatically codescribe('Array', function() {describe('#indexOf()', function() {it('should return -1 when the value is not present', function() {- [1,2,3].indexOf(5).should.equal(-1);- [1,2,3].indexOf(0).should.equal(-1);+ [1, 2, 3].indexOf(5).should.equal(-1);+ [1, 2, 3].indexOf(0).should.equal(-1);});});});@@ -334,7 +334,7 @@ describe('Array', function() {## Arrow Functions-Passing [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions) ("lambdas") to Mocha is discouraged. Lambdas lexically bind `this` and cannot access the Mocha context. For example, the following code will fail:+Passing [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions) ("lambdas") to Mocha is discouraged. Lambdas lexically bind `this` and cannot access the Mocha context. For example, the following code will fail:```jsdescribe('my suite', () => {@@ -346,15 +346,14 @@ describe('my suite', () => {});```-*If you do not need to use* Mocha's context, lambdas should work. However, the result will be more difficult to refactor if the need eventually arises.+_If you do not need to use_ Mocha's context, lambdas should work. However, the result will be more difficult to refactor if the need eventually arises.## Hooks-With its default "BDD"-style interface, Mocha provides the hooks `before()`, `after()`, `beforeEach()`, and `afterEach()`. These should be used to set up preconditions and clean up after your tests.+With its default "BDD"-style interface, Mocha provides the hooks `before()`, `after()`, `beforeEach()`, and `afterEach()`. These should be used to set up preconditions and clean up after your tests.```jsdescribe('hooks', function() {-before(function() {// runs before all tests in this block});@@ -375,11 +374,11 @@ describe('hooks', function() {});```-> Tests can appear before, after, or interspersed with your hooks. Hooks will run in the order they are defined, as appropriate; all `before()` hooks run (once), then any `beforeEach()` hooks, tests, any `afterEach()` hooks, and finally `after()` hooks (once).+> Tests can appear before, after, or interspersed with your hooks. Hooks will run in the order they are defined, as appropriate; all `before()` hooks run (once), then any `beforeEach()` hooks, tests, any `afterEach()` hooks, and finally `after()` hooks (once).### Describing Hooks-Any hook can be invoked with an optional description, making it easier to pinpoint errors in your tests. If a hook is given a named function, that name will be used if no description is supplied.+Any hook can be invoked with an optional description, making it easier to pinpoint errors in your tests. If a hook is given a named function, that name will be used if no description is supplied.```jsbeforeEach(function() {@@ -401,7 +400,7 @@ All hooks (`before()`, `after()`, `beforeEach()`, `afterEach()`) may be sync or```jsdescribe('Connection', function() {- var db = new Connection,+ var db = new Connection(),tobi = new User('tobi'),loki = new User('loki'),jane = new User('jane');@@ -427,7 +426,7 @@ describe('Connection', function() {### Root-Level Hooks-You may also pick any file and add "root"-level hooks. For example, add `beforeEach()` outside of all `describe()` blocks. This will cause the callback to `beforeEach()` to run before any test case, regardless of the file it lives in (this is because Mocha has an *implied* `describe()` block, called the "root suite").+You may also pick any file and add "root"-level hooks. For example, add `beforeEach()` outside of all `describe()` blocks. This will cause the callback to `beforeEach()` to run before any test case, regardless of the file it lives in (this is because Mocha has an _implied_ `describe()` block, called the "root suite").```jsbeforeEach(function() {@@ -437,7 +436,7 @@ beforeEach(function() {### Delayed Root Suite-If you need to perform asynchronous operations before any of your suites are run, you may delay the root suite. Run `mocha` with the `--delay` flag. This will attach a special callback function, `run()`, to the global context:+If you need to perform asynchronous operations before any of your suites are run, you may delay the root suite. Run `mocha` with the `--delay` flag. This will attach a special callback function, `run()`, to the global context:```jssetTimeout(function() {@@ -453,7 +452,7 @@ setTimeout(function() {## Pending Tests-"Pending"--as in "someone should write these test cases eventually"--test-cases are simply those *without* a callback:+"Pending"--as in "someone should write these test cases eventually"--test-cases are simply those _without_ a callback:```jsdescribe('Array', function() {@@ -468,8 +467,8 @@ Pending tests will be included in the test results, and marked as pending. A pen## Exclusive Tests-The exclusivity feature allows you to run *only* the specified suite or test-case- by appending `.only()` to the function. Here's an example of executing only a particular suite:+The exclusivity feature allows you to run _only_ the specified suite or test-case+by appending `.only()` to the function. Here's an example of executing only a particular suite:```jsdescribe('Array', function() {@@ -479,7 +478,7 @@ describe('Array', function() {});```-*Note*: All nested suites will still be executed.+_Note_: All nested suites will still be executed.Here's an example of executing an individual test case:@@ -497,7 +496,7 @@ describe('Array', function() {});```-Previous to v3.0.0, `.only()` used string matching to decide which tests to execute. As of v3.0.0, this is no longer the case. In v3.0.0 or newer, `.only()` can be used multiple times to define a subset of tests to run:+Previous to v3.0.0, `.only()` used string matching to decide which tests to execute; this is no longer the case. In v3.0.0 or newer, `.only()` can be used multiple times to define a subset of tests to run:```jsdescribe('Array', function() {@@ -531,21 +530,21 @@ describe('Array', function() {});});- describe.only('#concat()', function () {- it('should return a new Array', function () {+ describe.only('#concat()', function() {+ it('should return a new Array', function() {// this test will also be run});});- describe('#slice()', function () {- it('should return a new Array', function () {+ describe('#slice()', function() {+ it('should return a new Array', function() {// this test will not be run});});});```-But *tests will have precedence*:+But _tests will have precedence_:```jsdescribe('Array', function() {@@ -561,13 +560,13 @@ describe('Array', function() {});```-*Note*: Hooks, if present, will still be executed.+_Note_: Hooks, if present, will still be executed.> Be mindful not to commit usages of `.only()` to version control, unless you really mean it! To do so one can run mocha with the option `--forbid-only` in the continuous integration test command (or in a git precommit hook).## Inclusive Tests-This feature is the inverse of `.only()`. By appending `.skip()`, you may tell Mocha to simply ignore these suite(s) and test case(s). Anything skipped will be marked as [pending](#pending-tests), and reported as such. Here's an example of skipping an entire suite:+This feature is the inverse of `.only()`. By appending `.skip()`, you may tell Mocha to simply ignore these suite(s) and test case(s). Anything skipped will be marked as [pending](#pending-tests), and reported as such. Here's an example of skipping an entire suite:```jsdescribe('Array', function() {@@ -593,9 +592,9 @@ describe('Array', function() {});```-> *Best practice*: Use `.skip()` instead of commenting tests out.+> _Best practice_: Use `.skip()` instead of commenting tests out.-You may also skip *at runtime* using `this.skip()`. If a test needs an environment or configuration which cannot be detected beforehand, a runtime skip is appropriate. For example:+You may also skip _at runtime_ using `this.skip()`. If a test needs an environment or configuration which cannot be detected beforehand, a runtime skip is appropriate. For example:```jsit('should only test in the correct environment', function() {@@ -607,9 +606,9 @@ it('should only test in the correct environment', function() {});```-The above test will be reported as [pending](#pending-tests). It's also important to note that calling `this.skip()` will effectively *abort* the test.+The above test will be reported as [pending](#pending-tests). It's also important to note that calling `this.skip()` will effectively _abort_ the test.-> *Best practice*: To avoid confusion, do not execute further instructions in a test or hook after calling `this.skip()`.+> _Best practice_: To avoid confusion, do not execute further instructions in a test or hook after calling `this.skip()`.Contrast the above test with the following code:@@ -623,11 +622,11 @@ it('should only test in the correct environment', function() {});```-Because this test *does nothing*, it will be reported as *passing*.+Because this test _does nothing_, it will be reported as _passing_.-> *Best practice*: Don't do nothing! A test should make an assertion or use `this.skip()`.+> _Best practice_: Don't do nothing! A test should make an assertion or use `this.skip()`.-To skip *multiple* tests in this manner, use `this.skip()` in a "before" hook:+To skip _multiple_ tests in this manner, use `this.skip()` in a "before" hook:```jsbefore(function() {@@ -642,21 +641,21 @@ before(function() {This will skip all `it`, `beforeEach/afterEach`, and `describe` blocks within the suite. `before/after` hooks are skipped unless they are defined at the same level as the hook containing `this.skip()`.```js-describe('outer', function () {- before(function () {+describe('outer', function() {+ before(function() {this.skip();});- after(function () {+ after(function() {// will be executed});- describe('inner', function () {- before(function () {+ describe('inner', function() {+ before(function() {// will be skipped});- after(function () {+ after(function() {// will be skipped});});@@ -678,22 +677,21 @@ describe('retries', function() {// Retry all tests in this suite up to 4 timesthis.retries(4);- beforeEach(function () {+ beforeEach(function() {browser.get('http://www.yahoo.com');});- it('should succeed on the 3rd try', function () {+ it('should succeed on the 3rd try', function() {// Specify this test to only retry up to 2 timesthis.retries(2);expect($('.foo').isDisplayed()).to.eventually.be.true;});});-```## Dynamically Generating Tests-Given Mocha's use of `Function.prototype.call` and function expressions to define suites and test cases, it's straightforward to generate your tests dynamically. No special syntax is required — plain ol' JavaScript can be used to achieve functionality similar to "parameterized" tests, which you may have seen in other frameworks.+Given Mocha's use of `Function.prototype.call` and function expressions to define suites and test cases, it's straightforward to generate your tests dynamically. No special syntax is required — plain ol' JavaScript can be used to achieve functionality similar to "parameterized" tests, which you may have seen in other frameworks.Take the following example:@@ -708,8 +706,8 @@ function add() {describe('add()', function() {var tests = [- {args: [1, 2], expected: 3},- {args: [1, 2, 3], expected: 6},+ {args: [1, 2], expected: 3},+ {args: [1, 2, 3], expected: 6},{args: [1, 2, 3, 4], expected: 10}];@@ -751,7 +749,7 @@ To tweak what's considered "slow", you can use the `slow()` method:```jsdescribe('something slow', function() {- this.slow(300000); // five minutes+ this.slow(300000); // five minutesit('should take long enough for me to go make a sandwich', function() {// ...@@ -769,14 +767,14 @@ Suite-level timeouts may be applied to entire test "suites", or disabled via `thdescribe('a suite of tests', function() {this.timeout(500);- it('should take less than 500ms', function(done){+ it('should take less than 500ms', function(done) {setTimeout(done, 300);});- it('should take less than 500ms as well', function(done){+ it('should take less than 500ms as well', function(done) {setTimeout(done, 250);});-})+});```### Test-level@@ -784,7 +782,7 @@ describe('a suite of tests', function() {Test-specific timeouts may also be applied, or the use of `this.timeout(0)` to disable timeouts all together:```js-it('should take less than 500ms', function(done){+it('should take less than 500ms', function(done) {this.timeout(500);setTimeout(done, 300);});@@ -809,7 +807,7 @@ Again, use `this.timeout(0)` to disable the timeout for a hook.## Diffs-Mocha supports the `err.expected` and `err.actual` properties of any thrown `AssertionError`s from an assertion library. Mocha will attempt to display the difference between what was expected, and what the assertion actually saw. Here's an example of a "string" diff:+Mocha supports the `err.expected` and `err.actual` properties of any thrown `AssertionError`s from an assertion library. Mocha will attempt to display the difference between what was expected, and what the assertion actually saw. Here's an example of a "string" diff:{:class="screenshot" lazyload="on"}@@ -902,19 +900,19 @@ Mocha Resources### `--allow-uncaught`-By default, Mocha will attempt to trap uncaught exceptions thrown from running tests and report these as test failures. Use `--allow-uncaught` to disable this behavior and allow uncaught exceptions to propagate. Will typically cause the process to crash.+By default, Mocha will attempt to trap uncaught exceptions thrown from running tests and report these as test failures. Use `--allow-uncaught` to disable this behavior and allow uncaught exceptions to propagate. Will typically cause the process to crash.This flag is useful when debugging particularly difficult-to-track exceptions.### `--async-only, -A`-Enforce a rule that tests must be written in "async" style, meaning each test provides a `done` callback or returns a `Promise`. Non-compliant tests will be marked as failures.+Enforce a rule that tests must be written in "async" style, meaning each test provides a `done` callback or returns a `Promise`. Non-compliant tests will be marked as failures.### `--bail, -b`Causes Mocha to stop running tests after the first test failure it encounters. Corresponding `after()` and `afterEach()` hooks are executed for potential cleanup.-`--bail` does *not* imply `--exit`.+`--bail` does _not_ imply `--exit`.### `--check-leaks`@@ -922,21 +920,21 @@ Use this option to have Mocha check for global variables that are leaked while r### `--compilers`-> *`--compilers` was removed in v6.0.0. See [further explanation and workarounds](https://github.com/mochajs/mocha/wiki/compilers-deprecation).*+> _`--compilers` was removed in v6.0.0. See [further explanation and workarounds](https://github.com/mochajs/mocha/wiki/compilers-deprecation)._### `--exit`-> *Updated in v4.0.0.*+> _Updated in v4.0.0._TL;DR: If your tests hang after an upgrade to Mocha v4.0.0 or newer, use `--exit` for a quick (though not necessarily recommended) fix.-*Prior to* version v4.0.0, *by default*, Mocha would force its own process to exit once it was finished executing all tests. This behavior enables a set of potential problems; it's indicative of tests (or fixtures, harnesses, code under test, etc.) which don't clean up after themselves properly. Ultimately, "dirty" tests can (but not always) lead to *false positive* or *false negative* results.+_Prior to_ version v4.0.0, _by default_, Mocha would force its own process to exit once it was finished executing all tests. This behavior enables a set of potential problems; it's indicative of tests (or fixtures, harnesses, code under test, etc.) which don't clean up after themselves properly. Ultimately, "dirty" tests can (but not always) lead to _false positive_ or _false negative_ results.-"Hanging" most often manifests itself if a server is still listening on a port, or a socket is still open, etc. It can also be something like a runaway `setInterval()`, or even an errant `Promise` that never fulfilled.+"Hanging" most often manifests itself if a server is still listening on a port, or a socket is still open, etc. It can also be something like a runaway `setInterval()`, or even an errant `Promise` that never fulfilled.-The *default behavior* in v4.0.0 is `--no-exit`, where previously it was `--exit`.+The _default behavior_ in v4.0.0 (and newer) is `--no-exit`, where previously it was `--exit`.-**The easiest way to "fix" the issue is to simply pass `--exit` to the Mocha process.** It *can* be time-consuming to debug--because it's not always obvious where the problem is--but it *is* recommended to do so.+**The easiest way to "fix" the issue is to simply pass `--exit` to the Mocha process.** It _can_ be time-consuming to debug--because it's not always obvious where the problem is--but it _is_ recommended to do so.To ensure your tests aren't leaving messes around, here are some ideas to get started:@@ -953,13 +951,13 @@ Enforce a rule that tests may not be exclusive (use of e.g., `describe.only()` o### `--forbid-pending`-Enforce a rule that tests may not be skipped (use of e.g., `describe.skip()`, `it.skip()`, or `this.skip()` anywhere is disallowed).+Enforce a rule that tests may not be skipped (use of e.g., `describe.skip()`, `it.skip()`, or `this.skip()` anywhere is disallowed).`--forbid-pending` causes Mocha to fail when a skipped ("pending") test or suite is encountered, and it will abort further test execution.### `--global <variable-name>`-> *Updated in v6.0.0; the option is `--global` and `--globals` is now an alias.*+> _Updated in v6.0.0; the option is `--global` and `--globals` is now an alias._Define a global variable name. For example, suppose your app deliberately exposes a global named `app` and `YUI`, you may want to add `--global app --global YUI`.@@ -967,7 +965,7 @@ Define a global variable name. For example, suppose your app deliberately expose`--global` can accept a comma-delimited list; `--global app,YUI` is equivalent to `--global app --global YUI`.-By using this option in conjunction with `--check-leaks`, you can specify a whitelist of known global variables that you *expect* to leak into global scope.+By using this option in conjunction with `--check-leaks`, you can specify a whitelist of known global variables that you _expect_ to leak into global scope.### `--retries <n>`@@ -977,21 +975,21 @@ Mocha does not retry test failures by default.### `--slow <ms>, -s <ms>`-Specify the "slow" test threshold in milliseconds. Mocha uses this to highlight test cases that are taking too long. "Slow" tests are not considered failures.+Specify the "slow" test threshold in milliseconds. Mocha uses this to highlight test cases that are taking too long. "Slow" tests are not considered failures.-Note: A test that executes for *half* of the "slow" time will be highlighted *in yellow* with the default `spec` reporter; a test that executes for entire "slow" time will be highlighted *in red*.+Note: A test that executes for _half_ of the "slow" time will be highlighted _in yellow_ with the default `spec` reporter; a test that executes for entire "slow" time will be highlighted _in red_.### `--timeout <ms>, -t <ms>`-> *Update in v6.0.0: `--no-timeout` is implied when invoking Mocha using debug flags. It is equivalent to `--timeout 0`. `--timeout 99999999` is no longer needed.*+> _Update in v6.0.0: `--no-timeout` is implied when invoking Mocha using debug flags. It is equivalent to `--timeout 0`. `--timeout 99999999` is no longer needed._-Specifies the test case timeout, defaulting to two (2) seconds (2000 milliseconds). Tests taking longer than this amount of time will be marked as failed.+Specifies the test case timeout, defaulting to two (2) seconds (2000 milliseconds). Tests taking longer than this amount of time will be marked as failed.To override you may pass the timeout in milliseconds, or a value with the `s` suffix, e.g., `--timeout 2s` and `--timeout 2000` are equivalent.To disable timeouts, use `--no-timeout`.-Note: synchronous (blocking) tests are also bound by the timeout, but they will not complete until the code stops blocking. Infinite loops will still be infinite loops!+Note: synchronous (blocking) tests are also bound by the timeout, but they will not complete until the code stops blocking. Infinite loops will still be infinite loops!### `--ui <name>, -u <name>`@@ -999,9 +997,9 @@ The `--ui` option lets you specify the interface to use, defaulting to `bdd`.### `--color, -c, --colors`-> *Updated in v6.0.0. `--colors` is now an alias for `--color`.*+> _Updated in v6.0.0. `--colors` is now an alias for `--color`._-"Force" color output to be enabled, or alternatively force it to be disabled via `--no-color`. By default, Mocha uses [supports-color](https://npm.im/supports-color) to decide.+"Force" color output to be enabled, or alternatively force it to be disabled via `--no-color`. By default, Mocha uses [supports-color](https://npm.im/supports-color) to decide.In some cases, color output will be explicitly suppressed by certain reporters outputting in a machine-readable format.@@ -1017,7 +1015,7 @@ Mocha's own diff output does not conform to any known standards, and is designed### `--full-trace`-Enable "full" stack traces. By default, Mocha attempts to distill stack traces into less noisy (though still useful) output.+Enable "full" stack traces. By default, Mocha attempts to distill stack traces into less noisy (though still useful) output.This flag is helpful when debugging a suspected issue within Mocha or Node.js itself.@@ -1043,7 +1041,7 @@ Allows use of third-party reporters. For example, [mocha-lcov-reporter](https://### `--reporter-option <option>, -O <option>, --reporter-options <option>`-> *Updated in v6.0.0. Can be specified multiple times. `--reporter-options` is now an alias for `--reporter-option`.*+> _Updated in v6.0.0. Can be specified multiple times. `--reporter-options` is now an alias for `--reporter-option`._Provide options specific to a reporter in `<key>=<value>` format, e.g., `--reporter tap --reporter-option tapVersion=13`.@@ -1053,7 +1051,7 @@ Can be specified as a comma-delimited list.### `--config <path>`-> *New in v6.0.0.*+> _New in v6.0.0._Specify an explicit path to a [configuration file](#configuring-mocha-node-js).@@ -1061,7 +1059,7 @@ By default, Mocha will search for a config file if `--config` is not specified;### `--opts <path>`-> *Updated in v6.0.0; added `--no-opts`.*+> _Updated in v6.0.0; added `--no-opts`._Specify a path to [`mocha.opts`](#mochaopts).@@ -1069,9 +1067,9 @@ By default, Mocha looks for a `mocha.opts` in `test/mocha.opts`; use `--no-opts`### `--package <path>`-> *New in v6.0.0.*+> _New in v6.0.0._-Specify an explicit path to a [`package.json` file](#configuring-mocha-node-js) (ostensibly containing configuration in a `mocha` property).+Specify an explicit path to a [`package.json` file](#configuring-mocha-node-js) (ostensibly containing configuration in a `mocha` property).By default, Mocha looks for a `package.json` in the current working directory or nearest ancestor, and will use the first file found (regardless of whether it contains a `mocha` property); to suppress `package.json` lookup, use `--no-package`.@@ -1079,29 +1077,29 @@ By default, Mocha looks for a `package.json` in the current working directory orExplicitly exclude one or more files, directories or "globs" that would otherwise be loaded.-Files specified using `--file` *are not affected* by this option.+Files specified using `--file` _are not affected_ by this option.Can be specified multiple times.### `--extension <ext>, --watch-extensions <ext>`-> *Updated in v6.0.0. Previously `--watch-extensions`, but now expanded to affect general test file loading behavior. `--watch-extensions` is now an alias*+> _Updated in v6.0.0. Previously `--watch-extensions`, but now expanded to affect general test file loading behavior. `--watch-extensions` is now an alias_-Files having this extension will be considered test files. Defaults to `js`.+Files having this extension will be considered test files. Defaults to `js`.Affects `--watch` behavior.-Specifying `--extension` will *remove* `.js` as a test file extension; use `--extension js` to re-add it. For example, to load `.mjs` and `.js` test files, you must supply `--extension mjs --extension js`.+Specifying `--extension` will _remove_ `.js` as a test file extension; use `--extension js` to re-add it. For example, to load `.mjs` and `.js` test files, you must supply `--extension mjs --extension js`.### `--file <file/directory/glob>`-Explicitly *include* a test file to be loaded before other test files files. Multiple uses of `--file` are allowed, and will be loaded in order given.+Explicitly _include_ a test file to be loaded before other test files files. Multiple uses of `--file` are allowed, and will be loaded in order given.Useful if you want to declare, for example, hooks to be run before every test across all other test files.Files specified this way are not affected by `--sort` or `--recursive`.-Files specified in this way should contain one or more suites, tests or hooks. If this is not the case, consider `--require` instead.+Files specified in this way should contain one or more suites, tests or hooks. If this is not the case, consider `--require` instead.### `--recursive`@@ -1111,7 +1109,7 @@ See `--extension` for defining which files are considered test files.### `--require <module>, -r <module>`-Require a module before loading the user interface or test files. This is useful for:+Require a module before loading the user interface or test files. This is useful for:- Test harnesses- Assertion libraries that augment built-ins or global scope (such as [should.js](https://npm.im/should.js))@@ -1130,11 +1128,11 @@ Sort test files (by absolute path) using [Array.prototype.sort](https://developeExecutes tests on changes to JavaScript in the current working directory (and once initially).-By default, only files with extension `.js` are watched. Use `--extension` to change this behavior.+By default, only files with extension `.js` are watched. Use `--extension` to change this behavior.### `--fgrep <string>, -f <string>`-> *BREAKING CHANGE in v6.0.0; now mutually exclusive with `--grep`.*+> _BREAKING CHANGE in v6.0.0; now mutually exclusive with `--grep`._Cause Mocha to only run tests having titles containing the given `string`.@@ -1142,7 +1140,7 @@ Mutually exclusive with `--grep`.### `--grep <regexp>, -g <regexp>`-> *BREAKING CHANGE in v6.0.0; now mutually exclusive with `--fgrep`.*+> _BREAKING CHANGE in v6.0.0; now mutually exclusive with `--fgrep`._Cause Mocha to only run tests matching the given `regexp`, which is internally compiled to a [RegExp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Regexp).@@ -1170,16 +1168,13 @@ Mutually exclusive with `--fgrep`.### `--invert`-Use the *inverse* of the match specified by `--grep` or `fgrep`.+Use the _inverse_ of the match specified by `--grep` or `fgrep`.Requires either `--grep` or `--fgrep` (but not both).### `--debug, --inspect, --debug-brk, --inspect-brk, debug, inspect`-> *BREAKING CHANGE in v6.0.0; `-d` is no longer an alias for `--debug`.*-> *Other updates in v6.0.0:*-> *In versions of Node.js implementing `--inspect` and `--inspect-brk`, `--debug` and `--debug-brk` are respectively aliases for these two options.*-> *Likewise, `debug` (not `--debug`) is an alias for `inspect` (not `--inspect`) in Node.js versions where `debug` is deprecated.*+> _BREAKING CHANGE in v6.0.0; `-d` is no longer an alias for `--debug`._ > _Other updates in v6.0.0:_ > _In versions of Node.js implementing `--inspect` and `--inspect-brk`, `--debug` and `--debug-brk` are respectively aliases for these two options._ > _Likewise, `debug` (not `--debug`) is an alias for `inspect` (not `--inspect`) in Node.js versions where `debug` is deprecated._Enables Node.js' debugger or inspector.@@ -1193,11 +1188,11 @@ Implies `--no-timeout`.### About Option Types-> *Updated in v6.0.0.*+> _Updated in v6.0.0._-Each flag annotated of type `[boolean]` in Mocha's `--help` output can be *negated* by prepending `--no-` to the flag name. For example, `--no-color` will disable Mocha's color output, which is enabled by default.+Each flag annotated of type `[boolean]` in Mocha's `--help` output can be _negated_ by prepending `--no-` to the flag name. For example, `--no-color` will disable Mocha's color output, which is enabled by default.-Unless otherwise noted, *all* boolean flags default to `false`.+Unless otherwise noted, _all_ boolean flags default to `false`.### About `node` Flags@@ -1215,7 +1210,7 @@ V8 flags can be defined in Mocha's [configuration](#configuring-mocha-nodejs).## Interfaces-Mocha's "interface" system allows developers to choose their style of DSL. Mocha has **BDD**, **TDD**, **Exports**, **QUnit** and **Require**-style interfaces.+Mocha's "interface" system allows developers to choose their style of DSL. Mocha has **BDD**, **TDD**, **Exports**, **QUnit** and **Require**-style interfaces.### BDD@@ -1226,29 +1221,29 @@ The **BDD** interface provides `describe()`, `context()`, `it()`, `specify()`, `> All of the previous examples were written using the **BDD** interface.```js- describe('Array', function() {- before(function() {- // ...- });+describe('Array', function() {+ before(function() {+ // ...+ });- describe('#indexOf()', function() {- context('when not present', function() {- it('should not throw an error', function() {- (function() {- [1,2,3].indexOf(4);- }).should.not.throw();- });- it('should return -1', function() {- [1,2,3].indexOf(4).should.equal(-1);- });+ describe('#indexOf()', function() {+ context('when not present', function() {+ it('should not throw an error', function() {+ (function() {+ [1, 2, 3].indexOf(4);+ }.should.not.throw());});- context('when present', function() {- it('should return the index where the element first appears in the array', function() {- [1,2,3].indexOf(3).should.equal(2);- });+ it('should return -1', function() {+ [1, 2, 3].indexOf(4).should.equal(-1);+ });+ });+ context('when present', function() {+ it('should return the index where the element first appears in the array', function() {+ [1, 2, 3].indexOf(3).should.equal(2);});});});+});```### TDD@@ -1263,7 +1258,7 @@ suite('Array', function() {suite('#indexOf()', function() {test('should return -1 when not present', function() {- assert.equal(-1, [1,2,3].indexOf(4));+ assert.equal(-1, [1, 2, 3].indexOf(4));});});});@@ -1279,10 +1274,10 @@ module.exports = {// ...},- 'Array': {+ Array: {'#indexOf()': {'should return -1 when not present': function() {- [1,2,3].indexOf(4).should.equal(-1);+ [1, 2, 3].indexOf(4).should.equal(-1);}}}@@ -1301,12 +1296,12 @@ function ok(expr, msg) {suite('Array');test('#length', function() {- var arr = [1,2,3];+ var arr = [1, 2, 3];ok(arr.length == 3);});test('#indexOf()', function() {- var arr = [1,2,3];+ var arr = [1, 2, 3];ok(arr.indexOf(1) == 0);ok(arr.indexOf(2) == 1);ok(arr.indexOf(3) == 2);@@ -1323,7 +1318,7 @@ test('#length', function() {The `require` interface allows you to require the `describe` and friend words directly using `require` and call them whatever you want. This interface is also useful if you want to avoid global variables in your tests.-*Note*: The `require` interface cannot be run via the `node` executable, and must be run via `mocha`.+_Note_: The `require` interface cannot be run via the `node` executable, and must be run via `mocha`.```jsvar testCase = require('mocha').describe;@@ -1338,7 +1333,7 @@ testCase('Array', function() {testCase('#indexOf()', function() {assertions('should return -1 when not present', function() {- assert.equal([1,2,3].indexOf(4), -1);+ assert.equal([1, 2, 3].indexOf(4), -1);});});});@@ -1350,14 +1345,14 @@ Mocha reporters adjust to the terminal window, and always disable ANSI-escape co### Spec-This is the default reporter. The "spec" reporter outputs a hierarchical view nested just as the test cases are.+This is the default reporter. The "spec" reporter outputs a hierarchical view nested just as the test cases are.{:class="screenshot" lazyload="on"}{:class="screenshot" lazyload="on"}### Dot Matrix-The dot matrix (or "dot") reporter is simply a series of characters which represent test cases. Failures highlight in red exclamation marks (`!`), pending tests with a blue comma (`,`), and slow tests as yellow. Good if you prefer minimal output.+The dot matrix (or "dot") reporter is simply a series of characters which represent test cases. Failures highlight in red exclamation marks (`!`), pending tests with a blue comma (`,`), and slow tests as yellow. Good if you prefer minimal output.{:class="screenshot" lazyload="on"}@@ -1412,7 +1407,7 @@ The "min" reporter displays the summary only, while still outputting errors on f### Doc-The "doc" reporter outputs a hierarchical HTML body representation of your tests. Wrap it with a header, footer, and some styling, then you have some fantastic documentation!+The "doc" reporter outputs a hierarchical HTML body representation of your tests. Wrap it with a header, footer, and some styling, then you have some fantastic documentation!{:class="screenshot" lazyload="on"}@@ -1422,8 +1417,8 @@ For example, suppose you have the following JavaScript:describe('Array', function() {describe('#indexOf()', function() {it('should return -1 when the value is not present', function() {- [1,2,3].indexOf(5).should.equal(-1);- [1,2,3].indexOf(0).should.equal(-1);+ [1, 2, 3].indexOf(5).should.equal(-1);+ [1, 2, 3].indexOf(0).should.equal(-1);});});});@@ -1438,9 +1433,11 @@ The command `mocha --reporter doc array` would yield:<section class="suite"><h1>#indexOf()</h1><dl>- <dt>should return -1 when the value is not present</dt>- <dd><pre><code>[1,2,3].indexOf(5).should.equal(-1);-[1,2,3].indexOf(0).should.equal(-1);</code></pre></dd>+ <dt>should return -1 when the value is not present</dt>+ <dd>+ <pre><code>[1,2,3].indexOf(5).should.equal(-1);+[1,2,3].indexOf(0).should.equal(-1);</code></pre>+ </dd></dl></section></dl>@@ -1461,9 +1458,9 @@ The "markdown" reporter generates a markdown TOC and body for your test suite. T### XUnit-The `xunit` reporter is also available. It outputs an XUnit-compatible XML document, often applicable in CI servers.+The `xunit` reporter is also available. It outputs an XUnit-compatible XML document, often applicable in CI servers.-By default, it will output to the console. To write directly to a file, use `--reporter-options output=filename.xml`.+By default, it will output to the console. To write directly to a file, use `--reporter-options output=filename.xml`.### Third-Party Reporters@@ -1479,46 +1476,46 @@ Mocha runs in the browser. Every release of Mocha will have new builds of `./moc### Browser-specific methods- The following method(s) *only* function in a browser context:+The following method(s) _only_ function in a browser context:- `mocha.allowUncaught()` : If called, uncaught errors will not be absorbed by the error handler.+`mocha.allowUncaught()` : If called, uncaught errors will not be absorbed by the error handler.A typical setup might look something like the following, where we call `mocha.setup('bdd')` to use the **BDD** interface before loading the test scripts, running them `onload` with `mocha.run()`.```html<html>-<head>- <meta charset="utf-8">- <title>Mocha Tests</title>- <link rel="stylesheet" href="https://unpkg.com/mocha/mocha.css" />-</head>-<body>- <div id="mocha"></div>-- <script src="https://unpkg.com/chai/chai.js"></script>- <script src="https://unpkg.com/mocha/mocha.js"></script>-- <script class="mocha-init">- mocha.setup('bdd');- mocha.checkLeaks();- </script>- <script src="test.array.js"></script>- <script src="test.object.js"></script>- <script src="test.xhr.js"></script>- <script class="mocha-exec">- mocha.run();- </script>-</body>+ <head>+ <meta charset="utf-8" />+ <title>Mocha Tests</title>+ <link rel="stylesheet" href="https://unpkg.com/mocha/mocha.css" />+ </head>+ <body>+ <div id="mocha"></div>++ <script src="https://unpkg.com/chai/chai.js"></script>+ <script src="https://unpkg.com/mocha/mocha.js"></script>++ <script class="mocha-init">+ mocha.setup('bdd');+ mocha.checkLeaks();+ </script>+ <script src="test.array.js"></script>+ <script src="test.object.js"></script>+ <script src="test.xhr.js"></script>+ <script class="mocha-exec">+ mocha.run();+ </script>+ </body></html>```### Grep-The browser may use the `--grep` as functionality. Append a query-string to your URL: `?grep=api`.+The browser may use the `--grep` as functionality. Append a query-string to your URL: `?grep=api`.### Browser Configuration-Mocha options can be set via `mocha.setup()`. Examples:+Mocha options can be set via `mocha.setup()`. Examples:```js// Use "tdd" interface. This is a shortcut to setting the interface;@@ -1540,13 +1537,13 @@ mocha.setup({### Browser-specific Option(s)-The following option(s) *only* function in a browser context:+The following option(s) _only_ function in a browser context:`noHighlighting`: If set to `true`, do not attempt to use syntax highlighting on output test code.### Reporting-The "HTML" reporter is what you see when running Mocha in the browser. It looks like this:+The "HTML" reporter is what you see when running Mocha in the browser. It looks like this:{:class="screenshot" lazyload="on"}@@ -1570,7 +1567,7 @@ notification should appear informing you whether your tests passed or failed.In order to use desktop notifications with the command-line interface (CLI),you **must** first install some platform-specific prerequisite software.-Instructions for doing so can be found [here][Growl-install].+Instructions for doing so can be found [here][growl-install].Enable Mocha's desktop notifications as follows:@@ -1596,8 +1593,8 @@ tests as shown below:<html><head><title>Mocha</title>- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">- <meta name="viewport" content="width=device-width, initial-scale=1.0">+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><link rel="stylesheet" href="https://unpkg.com/mocha/mocha.css" /></head><body>@@ -1605,7 +1602,7 @@ tests as shown below:<script src="https://unpkg.com/mocha/mocha.js"></script><script class="mocha-init">mocha.setup('bdd');- mocha.growl(); // <-- Enables web notifications+ mocha.growl(); // <-- Enables web notifications</script><script src="tests.js"></script><script class="mocha-exec">@@ -1617,20 +1614,20 @@ tests as shown below:## Configuring Mocha (Node.js)-> *New in v6.0.0*+> _New in v6.0.0_In addition to supporting the legacy [`mocha.opts`](#mochaopts) run-control format, Mocha now supports configuration files, typical of modern command-line tools, in several formats:- **JavaScript**: Create a `.mocharc.js` in your project's root directory, and export an object (`module.exports = {/* ... */}`) containing your configuration.- **YAML**: Create a `.mocharc.yaml` (or `.mocharc.yml`) in your project's root directory.-- **JSON**: Create a `.mocharc.json` in your project's root directory. Comments--while not valid JSON--are allowed in this file, and will be ignored by Mocha.+- **JSON**: Create a `.mocharc.json` in your project's root directory. Comments--while not valid JSON--are allowed in this file, and will be ignored by Mocha.- **`package.json`**: Create a `mocha` property in your project's `package.json`.Mocha suggests using one of the above strategies for configuration instead of the legacy `mocha.opts` format.### Custom Locations-You can specify a custom location for your configuration file with the `--config <path>` option. Mocha will use the file's extension to determine how to parse the file, and will assume JSON if unknown.+You can specify a custom location for your configuration file with the `--config <path>` option. Mocha will use the file's extension to determine how to parse the file, and will assume JSON if unknown.You can specify a custom `package.json` location as well, using the `--package <path>` option.@@ -1640,7 +1637,7 @@ To skip looking for config files, use `--no-config`. Likewise, use `--no-package### Priorities-If no custom path was given, and if there are multiple configuration files in the same directory, Mocha will search for--and use--only one. The priority is:+If no custom path was given, and if there are multiple configuration files in the same directory, Mocha will search for--and use--only one. The priority is:1. `.mocharc.js`1. `.mocharc.yaml`@@ -1649,18 +1646,18 @@ If no custom path was given, and if there are multiple configuration files in th### Merging-Mocha will also *merge* any options found in `package.json` *and* `mocha.opts` into its run-time configuration. In case of conflict, the priority is:+Mocha will also _merge_ any options found in `package.json` _and_ `mocha.opts` into its run-time configuration. In case of conflict, the priority is:1. Arguments specified on command-line1. Configuration file (`.mocharc.js`, `.mocharc.yml`, etc.)1. `mocha` property of `package.json`1. `mocha.opts`-Options which can safely be repeated (e.g., `--require`) will be *concatenated*, with higher-priorty configuration sources appearing earlier in the list. For example, a `.mocharc.json` containing `"require": "bar"`, coupled with execution of `mocha --require foo`, would cause Mocha to require `foo`, then `bar`, in that order.+Options which can safely be repeated (e.g., `--require`) will be _concatenated_, with higher-priorty configuration sources appearing earlier in the list. For example, a `.mocharc.json` containing `"require": "bar"`, coupled with execution of `mocha --require foo`, would cause Mocha to require `foo`, then `bar`, in that order.### Extending Configuration-Configurations can inherit from other modules using the `extends` keyword. See [here](http://yargs.js.org/docs/#api-configobject-extends-keyword) for more information.+Configurations can inherit from other modules using the `extends` keyword. See [here](http://yargs.js.org/docs/#api-configobject-extends-keyword) for more information.### Configuration Format@@ -1669,13 +1666,13 @@ Configurations can inherit from other modules using the `extends` keyword. See- For options containing a dash (`-`), the option name can be specified using camelCase.- Aliases are valid names, e.g., `R` instead of `reporter`.- Test files can be specified using `spec`, e.g., `"spec": "test/**/*.spec.js"`.-- Flags to `node` are *also* supported in configuration files, like in `mocha.opts`. Use caution, as these can vary between versions of Node.js!+- Flags to `node` are _also_ supported in configuration files, like in `mocha.opts`. Use caution, as these can vary between versions of Node.js!**For more configuration examples, see the [`example/config` directory on GitHub.](https://github.com/mochajs/mocha/tree/master/example/config)**## `mocha.opts`-> *Updated in v6.0.0; `mocha.opts` is now considered "legacy"--though not yet deprecated--and we recommend using a configuration file instead.*+> _Updated in v6.0.0; `mocha.opts` is now considered "legacy"--though not yet deprecated--and we recommend using a configuration file instead._Mocha will attempt to load `"./test/mocha.opts"` as a run-control file of sorts.@@ -1724,21 +1721,24 @@ Some shells support recursive matching by using the `**` wildcard in a glob. Bas$ mocha "./spec/**/*.js"```-*Note*: Double quotes around the glob are recommended for portability.+_Note_: Double quotes around the glob are recommended for portability.## Error Codes-List of codes associated with Errors thrown inside Mocha. Following NodeJS practices.+> _New in v6.0.0_++When Mocha itself throws exception, the associated `Error` will have a `code` property. Where applicable, consumers should check the `code` property instead of string-matching against the `message` property. The following table describes these error codes:-| Code | Meaning |-| ------------- | ------------- |-| ERR_MOCHA_INVALID_ARG_TYPE | argument of the wrong type was passed to Mocha's API |-| ERR_MOCHA_INVALID_ARG_VALUE | invalid or unsupported value was passed for a given argument |-| ERR_MOCHA_INVALID_INTERFACE | interface specified in options not found |-| ERR_MOCHA_INVALID_REPORTER | reporter specified in options not found |-| ERR_MOCHA_NO_FILES_MATCH_PATTERN | file/s of test could not be found |-| ERR_MOCHA_NOT_SUPPORTED | type of output specified was not supported |-| ERR_MOCHA_UNDEFINED_ERROR | an error was thrown but no details were specified |+| Code | Description |+| -------------------------------- | ------------------------------------------------------------ |+| ERR_MOCHA_INVALID_ARG | argument is invalid |+| ERR_MOCHA_INVALID_ARG_TYPE | argument of the wrong type was passed to Mocha's API |+| ERR_MOCHA_INVALID_ARG_VALUE | invalid or unsupported value was passed for a given argument |+| ERR_MOCHA_INVALID_EXCEPTION | a falsy or otherwise underspecified exception was thrown |+| ERR_MOCHA_INVALID_INTERFACE | interface specified in options not found |+| ERR_MOCHA_INVALID_REPORTER | reporter specified in options not found |+| ERR_MOCHA_NO_FILES_MATCH_PATTERN | file/s of test could not be found |+| ERR_MOCHA_UNSUPPORTED | requested behavior, option, or parameter is unsupported |## Editor Plugins@@ -1809,21 +1809,22 @@ $ REPORTER=nyan npm test## More Information-In addition to chatting with us on [Gitter][Gitter-mocha], for additional information such as using-spies, mocking, and shared behaviours be sure to check out the [Mocha Wiki][Mocha-wiki] on GitHub.-For discussions join the [Google Group][Google-mocha]. For a running example of Mocha, view+In addition to chatting with us on [Gitter][gitter-mocha], for additional information such as using+spies, mocking, and shared behaviours be sure to check out the [Mocha Wiki][mocha-wiki] on GitHub.+For discussions join the [Google Group][google-mocha]. For a running example of Mocha, view[example/tests.html](example/tests.html). For the JavaScript API, view the [API documentation](api/)or the [source](https://github.com/mochajs/mocha/blob/master/lib/mocha.js).-[//]: # (Cross reference section)--[Gitter-mocha]: https://gitter.im/mochajs/mocha-[Google-mocha]: https://groups.google.com/group/mochajs-[Growl]: http://growl.info/-[Growl-install]: https://github.com/mochajs/mocha/wiki/Growl-Notifications-[Mocha-website]: https://mochajs.org/-[Mocha-wiki]: https://github.com/mochajs/mocha/wiki+[//]: # 'Cross reference section'+[gitter-mocha]: https://gitter.im/mochajs/mocha+[google-mocha]: https://groups.google.com/group/mochajs+[growl]: http://growl.info/+[growl-install]: https://github.com/mochajs/mocha/wiki/Growl-Notifications+[mocha-website]: https://mochajs.org/+[mocha-wiki]: https://github.com/mochajs/mocha/wiki<!-- AUTO-GENERATED-CONTENT:START (manifest:template=[Gitter]: ${gitter}) -->-[Gitter]: https://gitter.im/mochajs/mocha++[gitter]: https://gitter.im/mochajs/mocha+<!-- AUTO-GENERATED-CONTENT:END -->diff --git a/karma.conf.js b/karma.conf.jsindex 14f0be2b..82e934bb 100644--- a/karma.conf.js+++ b/karma.conf.js@@ -156,6 +156,7 @@ module.exports = config => {require.resolve('unexpected/unexpected'),{pattern: require.resolve('unexpected/unexpected.js.map'), included: false},require.resolve('unexpected-sinon'),+ require.resolve('unexpected-eventemitter/dist/unexpected-eventemitter.js'),require.resolve('./test/browser-specific/setup'));diff --git a/lib/cli/run.js b/lib/cli/run.jsindex 1d8a26d8..9fadeb4f 100644--- a/lib/cli/run.js+++ b/lib/cli/run.js@@ -8,8 +8,8 @@*/const Mocha = require('../mocha');-const ansi = require('ansi-colors');const {+ createUnsupportedError,createInvalidArgumentValueError,createMissingArgumentError} = require('../errors');@@ -268,9 +268,9 @@ exports.builder = yargs =>}if (argv.compilers) {- throw createInvalidArgumentValueError(+ throw createUnsupportedError(`--compilers is DEPRECATED and no longer supported.- See ${ansi.cyan('https://git.io/vdcSr')} for migration information.`+ See https://git.io/vdcSr for migration information.`);}diff --git a/lib/errors.js b/lib/errors.jsindex 90d0b92d..fafee70e 100644--- a/lib/errors.js+++ b/lib/errors.js@@ -7,7 +7,7 @@*//**- * Creates an error object used when no files to be tested could be found using specified pattern.+ * Creates an error object to be thrown when no files to be tested could be found using specified pattern.** @public* @param {string} message - Error message to be displayed.@@ -22,7 +22,7 @@ function createNoFilesMatchPatternError(message, pattern) {}/**- * Creates an error object used when the reporter specified in the options was not found.+ * Creates an error object to be thrown when the reporter specified in the options was not found.** @public* @param {string} message - Error message to be displayed.@@ -37,7 +37,7 @@ function createInvalidReporterError(message, reporter) {}/**- * Creates an error object used when the interface specified in the options was not found.+ * Creates an error object to be thrown when the interface specified in the options was not found.** @public* @param {string} message - Error message to be displayed.@@ -52,20 +52,20 @@ function createInvalidInterfaceError(message, ui) {}/**- * Creates an error object used when the type of output specified was not supported.+ * Creates an error object to be thrown when a behavior, option, or parameter is unsupported.** @public* @param {string} message - Error message to be displayed.* @returns {Error} instance detailing the error condition*/-function createNotSupportedError(message) {+function createUnsupportedError(message) {var err = new Error(message);- err.code = 'ERR_MOCHA_NOT_SUPPORTED';+ err.code = 'ERR_MOCHA_UNSUPPORTED';return err;}/**- * Creates an error object used when an argument is missing.+ * Creates an error object to be thrown when an argument is missing.** @public* @param {string} message - Error message to be displayed.@@ -78,7 +78,7 @@ function createMissingArgumentError(message, argument, expected) {}/**- * Creates an error object used when an argument did not use the supported type+ * Creates an error object to be thrown when an argument did not use the supported type** @public* @param {string} message - Error message to be displayed.@@ -96,7 +96,7 @@ function createInvalidArgumentTypeError(message, argument, expected) {}/**- * Creates an error object used when an argument did not use the supported value+ * Creates an error object to be thrown when an argument did not use the supported value** @public* @param {string} message - Error message to be displayed.@@ -115,25 +115,27 @@ function createInvalidArgumentValueError(message, argument, value, reason) {}/**- * Creates an error object used when an error was thrown but no details were specified.+ * Creates an error object to be thrown when an exception was caught, but the `Error` is falsy or undefined.** @public* @param {string} message - Error message to be displayed.* @returns {Error} instance detailing the error condition*/-function createUndefinedError(message) {+function createInvalidExceptionError(message, value) {var err = new Error(message);- err.code = 'ERR_MOCHA_UNDEFINED_ERROR';+ err.code = 'ERR_MOCHA_INVALID_EXCEPTION';+ err.valueType = typeof value;+ err.value = value;return err;}module.exports = {createInvalidArgumentTypeError: createInvalidArgumentTypeError,createInvalidArgumentValueError: createInvalidArgumentValueError,+ createInvalidExceptionError: createInvalidExceptionError,createInvalidInterfaceError: createInvalidInterfaceError,createInvalidReporterError: createInvalidReporterError,createMissingArgumentError: createMissingArgumentError,createNoFilesMatchPatternError: createNoFilesMatchPatternError,- createNotSupportedError: createNotSupportedError,- createUndefinedError: createUndefinedError+ createUnsupportedError: createUnsupportedError};diff --git a/lib/reporters/xunit.js b/lib/reporters/xunit.jsindex faccdaf7..7fb03aed 100644--- a/lib/reporters/xunit.js+++ b/lib/reporters/xunit.js@@ -12,6 +12,7 @@ var fs = require('fs');var mkdirp = require('mkdirp');var path = require('path');var errors = require('../errors');+var createUnsupportedError = errors.createUnsupportedError;var constants = require('../runner').constants;var EVENT_TEST_PASS = constants.EVENT_TEST_PASS;var EVENT_TEST_FAIL = constants.EVENT_TEST_FAIL;@@ -20,7 +21,6 @@ var EVENT_TEST_PENDING = constants.EVENT_TEST_PENDING;var STATE_FAILED = require('../runnable').constants.STATE_FAILED;var inherits = utils.inherits;var escape = utils.escape;-var createNotSupportedError = errors.createNotSupportedError;/*** Save timer references to avoid Sinon interfering (see GH-237).@@ -58,7 +58,7 @@ function XUnit(runner, options) {if (options && options.reporterOptions) {if (options.reporterOptions.output) {if (!fs.createWriteStream) {- throw createNotSupportedError('file output not supported in browser');+ throw createUnsupportedError('file output not supported in browser');}mkdirp.sync(path.dirname(options.reporterOptions.output));diff --git a/lib/runnable.js b/lib/runnable.jsindex 2509d199..026ab06b 100644--- a/lib/runnable.js+++ b/lib/runnable.js@@ -5,6 +5,8 @@ var Pending = require('./pending');var debug = require('debug')('mocha:runnable');var milliseconds = require('ms');var utils = require('./utils');+var createInvalidExceptionError = require('./errors')+ .createInvalidExceptionError;/*** Save timer references to avoid Sinon interfering (see GH-237).@@ -355,7 +357,7 @@ Runnable.prototype.run = function(fn) {callFnAsync(this.fn);} catch (err) {emitted = true;- done(utils.getError(err));+ done(Runnable.toValueOrError(err));}return;}@@ -378,7 +380,7 @@ Runnable.prototype.run = function(fn) {}} catch (err) {emitted = true;- done(utils.getError(err));+ done(Runnable.toValueOrError(err));}function callFn(fn) {@@ -462,7 +464,8 @@ var constants = utils.defineConstants(* @static* @alias constants* @enum {string}- */ {+ */+ {/*** Value of `state` prop when a `Runnable` has failed*/@@ -474,4 +477,20 @@ var constants = utils.defineConstants(});+/**+ * Given `value`, return identity if truthy, otherwise create an "invalid exception" error and return that.+ * @param {*} [value] - Value to return, if present+ * @returns {*|Error} `value`, otherwise an `Error`+ * @private+ */+Runnable.toValueOrError = function(value) {+ return (+ value ||+ createInvalidExceptionError(+ 'Runnable failed with falsy or undefined exception. Please throw an Error instead.',+ value+ )+ );+};+Runnable.constants = constants;diff --git a/lib/runner.js b/lib/runner.jsindex 018c71b1..d9784a96 100644--- a/lib/runner.js+++ b/lib/runner.js@@ -17,7 +17,8 @@ var STATE_PASSED = Runnable.constants.STATE_PASSED;var stackFilter = utils.stackTraceFilter();var stringify = utils.stringify;var type = utils.type;-var undefinedError = utils.undefinedError;+var createInvalidExceptionError = require('./errors')+ .createInvalidExceptionError;/*** Non-enumerable globals.@@ -771,18 +772,13 @@ Runner.prototype.runSuite = function(suite, fn) {*/Runner.prototype.uncaught = function(err) {if (err) {- debug(- 'uncaught exception %s',- err ===- function() {- return this;- }.call(err)- ? err.message || err- : err- );+ debug('uncaught exception %O', err);} else {- debug('uncaught undefined exception');- err = undefinedError();+ debug('uncaught undefined/falsy exception');+ err = createInvalidExceptionError(+ 'Caught falsy/undefined exception which would otherwise be uncaught. No stack trace found; try a debugger',+ err+ );}if (!isError(err)) {@@ -827,6 +823,7 @@ Runner.prototype.uncaught = function(err) {this.hookUp(HOOK_TYPE_AFTER_EACH, this.next);return;}+ debug(runnable);// recover from hooksvar errSuite = this.suite;diff --git a/lib/utils.js b/lib/utils.jsindex c6e7245b..51d77668 100644--- a/lib/utils.js+++ b/lib/utils.js@@ -18,7 +18,6 @@ var he = require('he');var errors = require('./errors');var createNoFilesMatchPatternError = errors.createNoFilesMatchPatternError;var createMissingArgumentError = errors.createMissingArgumentError;-var createUndefinedError = errors.createUndefinedError;/*** Ignored directories.@@ -580,29 +579,6 @@ exports.lookupFiles = function lookupFiles(filepath, extensions, recursive) {return files;};-/**- * Generate an undefined error with a message warning the user.- *- * @return {Error}- */--exports.undefinedError = function() {- return createUndefinedError(- 'Caught undefined error, did you throw without specifying what?'- );-};--/**- * Generate an undefined error if `err` is not defined.- *- * @param {Error} err- * @return {Error}- */--exports.getError = function(err) {- return err || exports.undefinedError();-};-/*** process.emitWarning or a polyfill* @see https://nodejs.org/api/process.html#process_process_emitwarning_warning_optionsdiff --git a/package-lock.json b/package-lock.jsonindex 8ecbb86a..e631bc15 100644--- a/package-lock.json+++ b/package-lock.json@@ -20963,6 +20963,12 @@"integrity": "sha1-SaysdTsFVt7WAlIQ7pYYIwfSssk=","dev": true},+ "unexpected-eventemitter": {+ "version": "1.1.3",+ "resolved": "https://registry.npmjs.org/unexpected-eventemitter/-/unexpected-eventemitter-1.1.3.tgz",+ "integrity": "sha512-30MfVuCOCSEvUzNUErYZ3ZzLiPOgADcJsyxi+0Z5bhwgI/Yv4xHR/2v/YEe2alaEXDdkteCQ4gLBfa5/J2iTPA==",+ "dev": true+ },"unexpected-sinon": {"version": "10.10.1","resolved": "https://registry.npmjs.org/unexpected-sinon/-/unexpected-sinon-10.10.1.tgz",diff --git a/package-scripts.js b/package-scripts.jsindex 391b28be..30e4294b 100644--- a/package-scripts.js+++ b/package-scripts.js@@ -115,7 +115,7 @@ module.exports = {integration: {script: test('integration',- '--timeout 10000 --slow 3750 "test/integration/*.spec.js"'+ '--timeout 10000 --slow 3750 "test/integration/**/*.spec.js"'),description: 'Run Node.js integration tests',hiddenFromHelp: truediff --git a/package.json b/package.jsonindex 1067be24..06748809 100644--- a/package.json+++ b/package.json@@ -560,6 +560,7 @@"through2": "^3.0.0","to-vfile": "^5.0.2","unexpected": "^10.39.2",+ "unexpected-eventemitter": "^1.1.3","unexpected-sinon": "^10.10.1","uslug": "^1.0.4","watchify": "^3.7.0"diff --git a/test/browser-specific/setup.js b/test/browser-specific/setup.jsindex d14c9e78..31f5c823 100644--- a/test/browser-specific/setup.js+++ b/test/browser-specific/setup.js@@ -4,4 +4,5 @@ process.stdout = require('browser-stdout')();global.expect = global.weknowhow.expect.clone()- .use(global.weknowhow.unexpectedSinon);+ .use(global.weknowhow.unexpectedSinon)+ .use(global.unexpectedEventEmitter);diff --git a/test/integration/helpers.js b/test/integration/helpers.jsindex 41fe542f..b4393de2 100644--- a/test/integration/helpers.js+++ b/test/integration/helpers.js@@ -174,7 +174,16 @@ module.exports = {*/resolveFixturePath: resolveFixturePath,- toJSONRunResult: toJSONRunResult+ toJSONRunResult: toJSONRunResult,++ /**+ * Given a regexp-like string, escape it so it can be used with the `RegExp` constructor+ * @param {string} str - string to be escaped+ * @returns {string} Escaped string+ */+ escapeRegExp: function escapeRegExp(str) {+ return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string+ }};/**diff --git a/test/integration/options.spec.js b/test/integration/options.spec.jsdeleted file mode 100644index f3336c0f..00000000--- a/test/integration/options.spec.js+++ /dev/null@@ -1,16 +0,0 @@-'use strict';--/**- * Tests for cmdline options.- * Provides umbrella for all spec files in the "options" subdirectory.- */--var path = require('path');-var utils = require('../../lib/utils');--describe('options', function() {- var specDir = path.join(__dirname, 'options');- var specs = utils.lookupFiles(specDir, ['js']).sort();-- specs.forEach(require);-});diff --git a/test/integration/options/interfaces.spec.js b/test/integration/options/interfaces.spec.jsnew file mode 100644index 00000000..7c58b89d--- /dev/null+++ b/test/integration/options/interfaces.spec.js@@ -0,0 +1,37 @@+'use strict';++var helpers = require('../helpers');+var invokeMocha = helpers.invokeMocha;+var escapeRegExp = helpers.escapeRegExp;+var interfaces = require('../../../lib/mocha').interfaces;++describe('--interfaces', function() {+ it('should dump a list of all interfaces with descriptions', function(done) {+ var expected = Object.keys(interfaces)+ .filter(function(name) {+ return /^[a-z]/.test(name);+ })+ .map(function(name) {+ return {+ name: escapeRegExp(name),+ description: escapeRegExp(interfaces[name].description)+ };+ });++ invokeMocha(['--interfaces'], function(err, result) {+ if (err) {+ return done(err);+ }++ expect(result.code, 'to be', 0);+ expected.forEach(function(ui) {+ expect(+ result.output,+ 'to match',+ new RegExp(ui.name + '\\s*-\\s*' + ui.description)+ );+ });+ done();+ });+ });+});diff --git a/test/integration/options/reporter-option.spec.js b/test/integration/options/reporter-option.spec.jsnew file mode 100644index 00000000..50d84ca5--- /dev/null+++ b/test/integration/options/reporter-option.spec.js@@ -0,0 +1,25 @@+'use strict';++var runMocha = require('../helpers').runMocha;++describe('--reporter-option', function() {+ describe('when given options w/ invalid format', function() {+ it('should display an error', function(done) {+ runMocha(+ 'passing.fixture.js',+ ['--reporter-option', 'foo=bar=baz'],+ function(err, res) {+ if (err) {+ return done(err);+ }+ expect(res, 'to have failed').and(+ 'to contain output',+ /invalid reporter option/i+ );+ done();+ },+ 'pipe'+ );+ });+ });+});diff --git a/test/integration/options/reporters.spec.js b/test/integration/options/reporters.spec.jsnew file mode 100644index 00000000..650c65ed--- /dev/null+++ b/test/integration/options/reporters.spec.js@@ -0,0 +1,40 @@+'use strict';++var helpers = require('../helpers');+var invokeMocha = helpers.invokeMocha;+var escapeRegExp = helpers.escapeRegExp;+var reporters = require('../../../lib/mocha').reporters;++describe('--reporters', function() {+ it('should dump a list of all reporters with descriptions', function(done) {+ var expected = Object.keys(reporters)+ .filter(function(name) {+ return (+ /^[a-z]/.test(name) &&+ !(reporters[name].abstract || reporters[name].browserOnly)+ );+ })+ .map(function(name) {+ return {+ name: escapeRegExp(name),+ description: escapeRegExp(reporters[name].description)+ };+ });++ invokeMocha(['--reporters'], function(err, result) {+ if (err) {+ return done(err);+ }++ expect(result.code, 'to be', 0);+ expected.forEach(function(reporter) {+ expect(+ result.output,+ 'to match',+ new RegExp(reporter.name + '\\s*-\\s*' + reporter.description)+ );+ });+ done();+ });+ });+});diff --git a/test/integration/show-plugins.spec.js b/test/integration/show-plugins.spec.jsdeleted file mode 100644index 54a56f7d..00000000--- a/test/integration/show-plugins.spec.js+++ /dev/null@@ -1,76 +0,0 @@-'use strict';--var invokeMocha = require('./helpers').invokeMocha;-var Mocha = require('../../lib/mocha');-var reporters = Mocha.reporters;-var interfaces = Mocha.interfaces;--// thanks MDN-function escapeRegExp(str) {- return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string-}--describe('--reporters', function() {- it('should dump a list of all reporters with descriptions', function(done) {- var expected = Object.keys(reporters)- .filter(function(name) {- return (- /^[a-z]/.test(name) &&- !(reporters[name].abstract || reporters[name].browserOnly)- );- })- .map(function(name) {- return {- name: escapeRegExp(name),- description: escapeRegExp(reporters[name].description)- };- });-- invokeMocha(['--reporters'], function(err, result) {- if (err) {- return done(err);- }-- expect(result.code, 'to be', 0);- expected.forEach(function(reporter) {- expect(- result.output,- 'to match',- new RegExp(reporter.name + '\\s*-\\s*' + reporter.description)- );- });- done();- });- });-});--describe('--interfaces', function() {- it('should dump a list of all interfaces with descriptions', function(done) {- var expected = Object.keys(interfaces)- .filter(function(name) {- return /^[a-z]/.test(name);- })- .map(function(name) {- return {- name: escapeRegExp(name),- description: escapeRegExp(interfaces[name].description)- };- });-- invokeMocha(['--interfaces'], function(err, result) {- if (err) {- return done(err);- }-- expect(result.code, 'to be', 0);- expected.forEach(function(ui) {- expect(- result.output,- 'to match',- new RegExp(ui.name + '\\s*-\\s*' + ui.description)- );- });- done();- });- });-});diff --git a/test/reporters/helpers.js b/test/reporters/helpers.jsindex a507f25c..5cb21a53 100644--- a/test/reporters/helpers.js+++ b/test/reporters/helpers.js@@ -1,7 +1,7 @@'use strict';var errors = require('../../lib/errors');-var createNotSupportedError = errors.createNotSupportedError;+var createUnsupportedError = errors.createUnsupportedError;/*This function prevents the constant use of creating a runnerEvent.runStr is the argument that defines the runnerEvent.@@ -118,7 +118,7 @@ function createRunnerFunction(runStr, ifStr1, ifStr2, ifStr3, arg1, arg2) {}};default:- throw createNotSupportedError(+ throw createUnsupportedError('This function does not support the runner string specified.');}diff --git a/test/setup.js b/test/setup.jsindex a29e2ebb..1732ae9d 100644--- a/test/setup.js+++ b/test/setup.js@@ -2,5 +2,8 @@var unexpected = require('unexpected');global.expect = require('./assertions').mixinMochaAssertions(- unexpected.clone().use(require('unexpected-sinon'))+ unexpected+ .clone()+ .use(require('unexpected-sinon'))+ .use(require('unexpected-eventemitter')));diff --git a/test/unit/runnable.spec.js b/test/unit/runnable.spec.jsindex 94df5f56..f912bbaf 100644--- a/test/unit/runnable.spec.js+++ b/test/unit/runnable.spec.js@@ -1,7 +1,6 @@'use strict';var Mocha = require('../../lib/mocha');-var utils = Mocha.utils;var Runnable = Mocha.Runnable;var Suite = Mocha.Suite;var sinon = require('sinon');@@ -419,7 +418,7 @@ describe('Runnable(title, fn)', function() {});runnable.run(function(err) {- expect(err.message, 'to be', utils.undefinedError().message);+ expect(err.message, 'to be', Runnable.toValueOrError().message);done();});});@@ -713,4 +712,16 @@ describe('Runnable(title, fn)', function() {}, 20);});});++ describe('static method', function() {+ describe('toValueOrError', function() {+ it('should return identity if parameter is truthy', function() {+ expect(Runnable.toValueOrError('foo'), 'to be', 'foo');+ });++ it('should return an Error if parameter is falsy', function() {+ expect(Runnable.toValueOrError(null), 'to be an', Error);+ });+ });+ });});diff --git a/test/unit/runner.spec.js b/test/unit/runner.spec.jsindex 6c04f93f..f48144ee 100644--- a/test/unit/runner.spec.js+++ b/test/unit/runner.spec.js@@ -1,12 +1,13 @@'use strict';+var path = require('path');+var sinon = require('sinon');var Mocha = require('../../lib/mocha');var Suite = Mocha.Suite;var Runner = Mocha.Runner;var Test = Mocha.Test;var Runnable = Mocha.Runnable;var Hook = Mocha.Hook;-var path = require('path');var noop = Mocha.utils.noop;var EVENT_TEST_FAIL = Runner.constants.EVENT_TEST_FAIL;var EVENT_TEST_RETRY = Runner.constants.EVENT_TEST_RETRY;@@ -14,12 +15,18 @@ var EVENT_RUN_END = Runner.constants.EVENT_RUN_END;var STATE_FAILED = Runnable.constants.STATE_FAILED;describe('Runner', function() {+ var sandbox;var suite;var runner;beforeEach(function() {suite = new Suite('Suite', 'root');runner = new Runner(suite);+ sandbox = sinon.createSandbox();+ });++ afterEach(function() {+ sandbox.restore();});describe('.grep()', function() {@@ -606,4 +613,314 @@ describe('Runner', function() {expect(runner.abort(), 'to be', runner);});});++ describe('uncaught()', function() {+ beforeEach(function() {+ sandbox.stub(runner, 'fail');+ });++ describe('when provided an object argument', function() {+ describe('when argument is not an Error', function() {+ var err;+ beforeEach(function() {+ err = {whatever: 'yolo'};+ });++ it('should fail with a transient Runnable and a new Error coerced from the object', function() {+ runner.uncaught(err);++ expect(runner.fail, 'to have all calls satisfying', [+ expect.it('to be a', Runnable).and('to satisfy', {+ parent: runner.suite,+ title: /uncaught error outside test suite/i+ }),+ expect.it('to be an', Error).and('to satisfy', {+ message: /throw an error/i,+ uncaught: true+ })+ ]).and('was called once');+ });+ });++ describe('when argument is an Error', function() {+ var err;+ beforeEach(function() {+ err = new Error('sorry dave');+ });++ it('should add the "uncaught" property to the Error', function() {+ runner.uncaught(err);+ expect(err, 'to have property', 'uncaught', true);+ });++ describe('when no Runnables are running', function() {+ beforeEach(function() {+ delete runner.currentRunnable;+ });++ it('should fail with a transient Runnable and the error', function() {+ runner.uncaught(err);++ expect(runner.fail, 'to have all calls satisfying', [+ expect.it('to be a', Runnable).and('to satisfy', {+ parent: runner.suite,+ title: /uncaught error outside test suite/i+ }),+ err+ ]).and('was called once');+ });++ describe('when Runner has already started', function() {+ beforeEach(function() {+ runner.started = true;+ });++ it('should not emit start/end events', function() {+ expect(+ function() {+ runner.uncaught(err);+ },+ 'not to emit from',+ runner,+ 'start'+ ).and('not to emit from', runner, 'end');+ });+ });++ describe('when Runner has not already started', function() {+ beforeEach(function() {+ runner.started = false;+ });++ it('should emit start/end events for the benefit of reporters', function() {+ expect(+ function() {+ runner.uncaught(err);+ },+ 'to emit from',+ runner,+ 'start'+ ).and('to emit from', runner, 'end');+ });+ });+ });++ describe('when a Runnable is running or has run', function() {+ var runnable;+ beforeEach(function() {+ runnable = new Runnable();+ runnable.parent = runner.suite;+ sandbox.stub(runnable, 'clearTimeout');+ runner.currentRunnable = runnable;+ runner.nextSuite = sandbox.spy();+ });++ afterEach(function() {+ delete runner.nextSuite;+ });++ it('should clear any pending timeouts', function() {+ runner.uncaught(err);+ expect(runnable.clearTimeout, 'was called times', 1);+ });++ describe('when current Runnable has already failed', function() {+ beforeEach(function() {+ sandbox.stub(runnable, 'isFailed').returns(true);+ });++ it('should not attempt to fail again', function() {+ runner.uncaught(err);+ expect(runner.fail, 'was not called');+ });+ });++ describe('when current Runnable has been marked pending', function() {+ beforeEach(function() {+ sandbox.stub(runnable, 'isPending').returns(true);+ });++ it('should not attempt to fail', function() {+ runner.uncaught(err);+ expect(runner.fail, 'was not called');+ });+ });++ describe('when the current Runnable has already passed', function() {+ beforeEach(function() {+ sandbox.stub(runnable, 'isPassed').returns(true);+ });++ it('should fail with the current Runnable and the error', function() {+ runner.uncaught(err);++ expect(runner.fail, 'to have all calls satisfying', [+ expect.it('to be', runnable),+ err+ ]).and('was called once');+ });++ it('should notify run has ended', function() {+ expect(+ function() {+ runner.uncaught(err);+ },+ 'to emit from',+ runner,+ 'end'+ );+ });+ });++ describe('when the current Runnable is currently running', function() {+ describe('when the current Runnable is a Test', function() {+ beforeEach(function() {+ runnable = new Test('goomba', noop);+ runnable.parent = runner.suite;+ runner.currentRunnable = runnable;+ sandbox.stub(runner, 'hookUp');+ runner.next = sandbox.spy();+ });++ afterEach(function() {+ delete runner.next;+ });++ it('should fail with the current Runnable and the error', function() {+ runner.uncaught(err);++ expect(runner.fail, 'to have all calls satisfying', [+ expect.it('to be', runnable),+ err+ ]).and('was called once');+ });++ it('should notify test has ended', function() {+ expect(+ function() {+ runner.uncaught(err);+ },+ 'to emit from',+ runner,+ 'test end',+ runnable+ );+ });++ it('should not notify run has ended', function() {+ expect(+ function() {+ runner.uncaught(err);+ },+ 'not to emit from',+ runner,+ 'end'+ );+ });++ it('should call any remaining "after each" hooks', function() {+ runner.uncaught(err);+ expect(runner.hookUp, 'to have all calls satisfying', [+ 'afterEach',+ expect.it('to be', runner.next)+ ]).and('was called once');+ });+ });++ describe('when the current Runnable is a "before all" or "after all" hook', function() {+ beforeEach(function() {+ runnable = new Hook('', noop);+ runnable.parent = runner.suite;+ runner.currentRunnable = runnable;+ });++ it('should continue to the next suite', function() {+ runner.uncaught(err);+ expect(runner.nextSuite, 'to have all calls satisfying', [+ runner.suite+ ]).and('was called once');+ });++ it('should not notify run has ended', function() {+ expect(+ function() {+ runner.uncaught(err);+ },+ 'not to emit from',+ runner,+ 'end'+ );+ });+ });++ describe('when the current Runnable is a "before each" hook', function() {+ beforeEach(function() {+ runnable = new Hook('before each', noop);+ runnable.parent = runner.suite;+ runner.currentRunnable = runnable;+ runner.hookErr = sandbox.spy();+ });++ afterEach(function() {+ delete runner.hookErr;+ });++ it('should associate its failure with the current test', function() {+ runner.uncaught(err);+ expect(runner.hookErr, 'to have all calls satisfying', [+ err,+ runner.suite,+ false+ ]).and('was called once');+ });++ it('should not notify run has ended', function() {+ expect(+ function() {+ runner.uncaught(err);+ },+ 'not to emit from',+ runner,+ 'end'+ );+ });+ });++ describe('when the current Runnable is an "after each" hook', function() {+ beforeEach(function() {+ runnable = new Hook('after each', noop);+ runnable.parent = runner.suite;+ runner.currentRunnable = runnable;+ runner.hookErr = sandbox.spy();+ });++ afterEach(function() {+ delete runner.hookErr;+ });++ it('should associate its failure with the current test', function() {+ runner.uncaught(err);+ expect(runner.hookErr, 'to have all calls satisfying', [+ err,+ runner.suite,+ true+ ]).and('was called once');+ });++ it('should not notify run has ended', function() {+ expect(+ function() {+ runner.uncaught(err);+ },+ 'not to emit from',+ runner,+ 'end'+ );+ });+ });+ });+ });+ });+ });+ });});