Merge branch 'master' into issue/2529-retryable-fail-event

docs/README.md

@@ -22,8 +22,8 @@
 
 - The content lives in `docs/index.md`; everything else is markup, scripts, assets, etc.
 - This file (`docs/README.md`) should *not* be included in the build.
-- `docs/index.md` may be mutated upon build, depending on what `scripts/docs-update-toc.js` does.  If it updates the table of contents (because of your changes), **you must commit `docs/index.md`**.
-- `docs/_site/` is where the generated static site lives (and is what you see at [mochajs.org](https://mochajs.org)).  It is *not* under version control.
+- `docs/_dist` and `docs/api` are where the deployed site lives.  `docs/_site` is essentially a build step.  These three directories are *not* under version control.
+- See `package-scripts.js` for details on what the builds are actually doing; especially see [markdown-magic](https://npm.im/markdown-magic) for how we're dynamically inserting information into `docs/index.md`.
 
 ## License
 

docs/index.md

@@ -815,85 +815,87 @@ Mocha supports the `err.expected` and `err.actual` properties of any thrown `Ass
 <!-- AUTO-GENERATED-CONTENT:START (usage:executable=bin/mocha) -->
 
 ```plain
+
 mocha [spec..]
 
 Run tests with Mocha
 
 Commands
-mocha debug [spec..]  Run tests with Mocha                           [default]
-mocha init <path>     create a client-side Mocha setup at <path>
+  mocha debug [spec..]  Run tests with Mocha                           [default]
+  mocha init <path>     create a client-side Mocha setup at <path>
 
 Rules & Behavior
---allow-uncaught           Allow uncaught errors to propagate        [boolean]
---async-only, -A           Require all tests to use a callback (async) or
-return a Promise                          [boolean]
---bail, -b                 Abort ("bail") after first test failure   [boolean]
---check-leaks              Check for global variable leaks           [boolean]
---delay                    Delay initial execution of root suite
---exit                     Force Mocha to quit after tests complete  [boolean]
---forbid-only              Fail if exclusive test(s) encountered     [boolean]
---forbid-pending           Fail if pending test(s) encountered       [boolean]
---global, --globals        List of allowed global variables            [array]
---retries                  Retry failed tests this many times         [number]
---slow, -s                 Specify "slow" test threshold (in milliseconds)
-[number] [default: 75]
---timeout, -t, --timeouts  Specify test timeout threshold (in milliseconds)
-[number] [default: 2000]
---ui, -u                   Specify user interface    [string] [default: "bdd"]
+  --allow-uncaught           Allow uncaught errors to propagate        [boolean]
+  --async-only, -A           Require all tests to use a callback (async) or
+                             return a Promise                          [boolean]
+  --bail, -b                 Abort ("bail") after first test failure   [boolean]
+  --check-leaks              Check for global variable leaks           [boolean]
+  --delay                    Delay initial execution of root suite
+  --exit                     Force Mocha to quit after tests complete  [boolean]
+  --forbid-only              Fail if exclusive test(s) encountered     [boolean]
+  --forbid-pending           Fail if pending test(s) encountered       [boolean]
+  --global, --globals        List of allowed global variables            [array]
+  --retries                  Retry failed tests this many times         [number]
+  --slow, -s                 Specify "slow" test threshold (in milliseconds)
+                                                          [number] [default: 75]
+  --timeout, -t, --timeouts  Specify test timeout threshold (in milliseconds)
+                                                        [number] [default: 2000]
+  --ui, -u                   Specify user interface    [string] [default: "bdd"]
 
 Reporting & Output
---color, -c, --colors                     Force-enable color output  [boolean]
---diff                                    Show diff on failure
-[boolean] [default: true]
---full-trace                              Display full stack traces  [boolean]
---growl, -G                               Enable Growl notifications [boolean]
---inline-diffs                            Display actual/expected differences
-inline within each string  [boolean]
---reporter, -R                            Specify reporter to use
-[string] [default: "spec"]
---reporter-option, --reporter-options,    Reporter-specific options
--O                                        (<k=v,[k1=v1,..]>)           [array]
+  --color, -c, --colors                     Force-enable color output  [boolean]
+  --diff                                    Show diff on failure
+                                                       [boolean] [default: true]
+  --full-trace                              Display full stack traces  [boolean]
+  --growl, -G                               Enable Growl notifications [boolean]
+  --inline-diffs                            Display actual/expected differences
+                                            inline within each string  [boolean]
+  --reporter, -R                            Specify reporter to use
+                                                      [string] [default: "spec"]
+  --reporter-option, --reporter-options,    Reporter-specific options
+  -O                                        (<k=v,[k1=v1,..]>)           [array]
 
 Configuration
---config   Path to config file                    [default: (nearest rc file)]
---opts     Path to `mocha.opts`        [string] [default: "./test/mocha.opts"]
---package  Path to package.json for config                            [string]
+  --config   Path to config file                    [default: (nearest rc file)]
+  --opts     Path to `mocha.opts`        [string] [default: "./test/mocha.opts"]
+  --package  Path to package.json for config                            [string]
 
 File Handling
---exclude                        Ignore file(s) or glob pattern(s)
-[array] [default: (none)]
---extension, --watch-extensions  File extension(s) to load and/or watch
-[array] [default: js]
---file                           Specify file(s) to be loaded prior to root
-suite execution     [array] [default: (none)]
---recursive                      Look for tests in subdirectories    [boolean]
---require, -r                    Require module      [array] [default: (none)]
---sort, -S                       Sort test files
---watch, -w                      Watch files in the current working directory
-for changes                         [boolean]
+  --exclude                        Ignore file(s) or glob pattern(s)
+                                                       [array] [default: (none)]
+  --extension, --watch-extensions  File extension(s) to load and/or watch
+                                                           [array] [default: js]
+  --file                           Specify file(s) to be loaded prior to root
+                                   suite execution     [array] [default: (none)]
+  --recursive                      Look for tests in subdirectories    [boolean]
+  --require, -r                    Require module      [array] [default: (none)]
+  --sort, -S                       Sort test files
+  --watch, -w                      Watch files in the current working directory
+                                   for changes                         [boolean]
 
 Test Filters
---fgrep, -f   Only run tests containing this string                   [string]
---grep, -g    Only run tests matching this string or regexp           [string]
---invert, -i  Inverts --grep and --fgrep matches                     [boolean]
+  --fgrep, -f   Only run tests containing this string                   [string]
+  --grep, -g    Only run tests matching this string or regexp           [string]
+  --invert, -i  Inverts --grep and --fgrep matches                     [boolean]
 
 Positional Arguments
-spec  One or more files, directories, or globs to test
-[array] [default: ["test/"]]
+  spec  One or more files, directories, or globs to test
+                                                    [array] [default: ["test/"]]
 
 Other Options
---help, -h     Show usage information & exit                         [boolean]
---version, -V  Show version number & exit                            [boolean]
---interfaces   List built-in user interfaces & exit
---reporters    List built-in reporters & exit
+  --help, -h     Show usage information & exit                         [boolean]
+  --version, -V  Show version number & exit                            [boolean]
+  --interfaces   List built-in user interfaces & exit
+  --reporters    List built-in reporters & exit
 
 Mocha Resources
-Chat: https://gitter.im/mochajs/mocha/
-GitHub: https://github.com/mochajs/mocha.git
-Docs: https://mochajs.org/
+    Chat: https://gitter.im/mochajs/mocha
+  GitHub: https://github.com/mochajs/mocha.git
+    Docs: https://mochajs.org/
+
 ```
 
-<!-- usagestop -->
+<!-- AUTO-GENERATED-CONTENT:END -->
 
 ### `--allow-uncaught`
 

lib/runner.js

@@ -597,17 +597,9 @@ Runner.prototype.runTests = function(suite, fn) {
         }
 
         test.state = 'passed';
-
-        // For supporting conditional fail in afterEach hook,
-        // run emit pass after an afterEach hook.
-        // See, https://github.com/mochajs/mocha/wiki/HOW-TO:-Conditionally-fail-a-test-after-completion
-        self.hookUp('afterEach', function(err, errSuite) {
-          if (test.state === 'passed') {
-            self.emit('pass', test);
-          }
-          self.emit('test end', test);
-          next(err, errSuite);
-        });
+        self.emit('pass', test);
+        self.emit('test end', test);
+        self.hookUp('afterEach', next);
       });
     });
   }

lib/stats-collector.js

@@ -1,8 +1,15 @@
 'use strict';
 
+/**
+ * Provides a factory function for a {@link StatsCollector} object.
+ * @private
+ * @module
+ */
+
 /**
  * Test statistics collector.
  *
+ * @private
  * @typedef {Object} StatsCollector
  * @property {number} suites - integer count of suites run.
  * @property {number} tests - integer count of tests run.
@@ -15,14 +22,16 @@
  */
 
 /**
- * Provides stats such as test duration,
- * number of tests passed / failed etc.
+ * Provides stats such as test duration, number of tests passed / failed etc., by listening for events emitted by `runner`.
  *
- * @public
- * @memberof Mocha
- * @param {Runner} runner
+ * @private
+ * @param {Runner} runner - Runner instance
+ * @throws {TypeError} If falsy `runner`
  */
 function createStatsCollector(runner) {
+  /**
+   * @type StatsCollector
+   */
   var stats = {
     suites: 0,
     tests: 0,

lib/utils.js

@@ -688,7 +688,11 @@ exports.stackTraceFilter = function() {
  * @returns {boolean} Whether or not `value` is a Promise
  */
 exports.isPromise = function isPromise(value) {
-  return typeof value === 'object' && typeof value.then === 'function';
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof value.then === 'function'
+  );
 };
 
 /**