mocha 7.1.2 → 7.2.0

package/CHANGELOG.md

@@ -1,3 +1,34 @@
+# 7.2.0 / 2020-05-22
+
+## :tada: Enhancements
+
+- [#4234](https://github.com/mochajs/mocha/issues/4234): Add ability to run tests in a mocha instance multiple times ([**@nicojs**](https://github.com/nicojs))
+- [#4219](https://github.com/mochajs/mocha/issues/4219): Exposing filename in JSON, doc, and json-stream reporters ([**@Daniel0113**](https://github.com/Daniel0113))
+- [#4244](https://github.com/mochajs/mocha/issues/4244): Add Root Hook Plugins ([**@boneskull**](https://github.com/boneskull))
+
+## :bug: Fixes
+
+- [#4258](https://github.com/mochajs/mocha/issues/4258): Fix missing dot in name of configuration file ([**@sonicdoe**](https://github.com/sonicdoe))
+- [#4194](https://github.com/mochajs/mocha/issues/4194): Check if module.paths really exists ([**@ematipico**](https://github.com/ematipico))
+- [#4256](https://github.com/mochajs/mocha/issues/4256): `--forbid-only` does not recognize `it.only` when `before` crashes ([**@arvidOtt**](https://github.com/arvidOtt))
+- [#4152](https://github.com/mochajs/mocha/issues/4152): Bug with multiple async done() calls ([**@boneskull**](https://github.com/boneskull))
+- [#4275](https://github.com/mochajs/mocha/issues/4275): Improper warnings for invalid reporters ([**@boneskull**](https://github.com/boneskull))
+- [#4288](https://github.com/mochajs/mocha/issues/4288): Broken hook.spec.js test for IE11 ([**@boneskull**](https://github.com/boneskull))
+
+## :book: Documentation
+
+- [#4081](https://github.com/mochajs/mocha/issues/4081): Insufficient white space for API docs in view on mobile ([**@HyunSangHan**](https://github.com/HyunSangHan))
+- [#4255](https://github.com/mochajs/mocha/issues/4255): Update mocha-docdash for UI fixes on API docs ([**@craigtaub**](https://github.com/craigtaub))
+- [#4235](https://github.com/mochajs/mocha/issues/4235): Enable emoji on website; enable normal ul elements ([**@boneskull**](https://github.com/boneskull))
+- [#4272](https://github.com/mochajs/mocha/issues/4272): Fetch sponsors at build time, show ALL non-skeevy sponsors ([**@boneskull**](https://github.com/boneskull))
+
+## :nut_and_bolt: Other
+
+- [#4249](https://github.com/mochajs/mocha/issues/4249): Refactoring improving encapsulation ([**@arvidOtt**](https://github.com/arvidOtt))
+- [#4242](https://github.com/mochajs/mocha/issues/4242): CI add job names, add Node.js v14 to matrix ([**@boneskull**](https://github.com/boneskull))
+- [#4237](https://github.com/mochajs/mocha/issues/4237): Refactor validatePlugins to throw coded errors ([**@boneskull**](https://github.com/boneskull))
+- [#4236](https://github.com/mochajs/mocha/issues/4236): Better debug output ([**@boneskull**](https://github.com/boneskull))
+
 # 7.1.2 / 2020-04-26
 
 ## :nut_and_bolt: Other
@@ -546,7 +577,7 @@ This release fixes a class of tests which report as _false positives_. **Certain
 
 - [#3226](https://github.com/mochajs/mocha/issues/3226): Do not swallow errors that are thrown asynchronously from passing tests ([@boneskull](https://github.com/boneskull)). Example:
 
-  \```js
+  \`\`\`js
   it('should actually fail, sorry!', function (done) {
   // passing assertion
   assert(true === true);
@@ -559,7 +590,7 @@ This release fixes a class of tests which report as _false positives_. **Certain
   throw new Error('chaos!');
   }, 100);
   });
-  \```
+  \`\`\`
 
   Previously to this version, Mocha would have _silently swallowed_ the `chaos!` exception, and you wouldn't know. Well, _now you know_. Mocha cannot recover from this gracefully, so it will exit with a nonzero code.
 

package/bin/mocha

@@ -34,7 +34,7 @@ debug('loaded opts', opts);
  */
 const disableTimeouts = value => {
   if (impliesNoTimeouts(value)) {
-    debug(`option "${value}" disabled timeouts`);
+    debug('option %s disabled timeouts', value);
     mochaArgs.timeout = 0;
     delete mochaArgs.timeouts;
     delete mochaArgs.t;
@@ -108,7 +108,11 @@ if (Object.keys(nodeArgs).length) {
     unparse(mochaArgs, {alias: aliases})
   );
 
-  debug(`exec ${process.execPath} w/ args:`, args);
+  debug(
+    'forking child process via command: %s %s',
+    process.execPath,
+    args.join(' ')
+  );
 
   const proc = spawn(process.execPath, args, {
     stdio: 'inherit'
@@ -130,5 +134,6 @@ if (Object.keys(nodeArgs).length) {
     proc.kill('SIGTERM'); // if that didn't work, we're probably in an infinite loop, so make it die.
   });
 } else {
+  debug('running Mocha in-process');
   require('../lib/cli/cli').main(unparse(mochaArgs, {alias: aliases}));
 }

package/browser-entry.js

@@ -52,6 +52,17 @@ process.removeListener = function(e, fn) {
   }
 };
 
+/**
+ * Implements listenerCount for 'uncaughtException'.
+ */
+
+process.listenerCount = function(name) {
+  if (name === 'uncaughtException') {
+    return uncaughtExceptionHandlers.length;
+  }
+  return 0;
+};
+
 /**
  * Implements uncaughtException listener.
  */

package/lib/cli/cli.js

@@ -19,6 +19,7 @@ const {loadOptions, YARGS_PARSER_CONFIG} = require('./options');
 const commands = require('./commands');
 const ansi = require('ansi-colors');
 const {repository, homepage, version, gitter} = require('../../package.json');
+const {cwd} = require('../utils');
 
 /**
  * - Accepts an `Array` of arguments
@@ -30,7 +31,9 @@ const {repository, homepage, version, gitter} = require('../../package.json');
 exports.main = (argv = process.argv.slice(2)) => {
   debug('entered main with raw args', argv);
   // ensure we can require() from current working directory
-  module.paths.push(process.cwd(), path.resolve('node_modules'));
+  if (typeof module.paths !== 'undefined') {
+    module.paths.push(cwd(), path.resolve('node_modules'));
+  }
 
   Error.stackTraceLimit = Infinity; // configurable via --stack-trace-limit?
 

package/lib/cli/collect-files.js

@@ -5,6 +5,7 @@ const ansi = require('ansi-colors');
 const debug = require('debug')('mocha:cli:run:helpers');
 const minimatch = require('minimatch');
 const utils = require('../utils');
+const {NO_FILES_MATCH_PATTERN} = require('../errors').constants;
 
 /**
  * Exports a function that collects test files from CLI parameters.
@@ -34,7 +35,7 @@ module.exports = ({ignore, extension, file, recursive, sort, spec} = {}) => {
     try {
       newFiles = utils.lookupFiles(arg, extension, recursive);
     } catch (err) {
-      if (err.code === 'ERR_MOCHA_NO_FILES_MATCH_PATTERN') {
+      if (err.code === NO_FILES_MATCH_PATTERN) {
         unmatched.push({message: err.message, pattern: err.pattern});
         return;
       }

package/lib/cli/config.js

@@ -12,6 +12,7 @@ const fs = require('fs');
 const path = require('path');
 const debug = require('debug')('mocha:cli:config');
 const findUp = require('find-up');
+const utils = require('../utils');
 
 /**
  * These are the valid config files, in order of precedence;
@@ -43,11 +44,11 @@ const parsers = (exports.parsers = {
   js: filepath => {
     const cwdFilepath = path.resolve(filepath);
     try {
-      debug(`parsers: load using cwd-relative path: "${cwdFilepath}"`);
+      debug('parsers: load using cwd-relative path: "%s"', cwdFilepath);
       return require(cwdFilepath);
     } catch (err) {
       if (isModuleNotFoundError(err)) {
-        debug(`parsers: retry load as module-relative path: "${filepath}"`);
+        debug('parsers: retry load as module-relative path: "%s"', filepath);
         return require(filepath);
       } else {
         throw err; // rethrow
@@ -70,7 +71,7 @@ const parsers = (exports.parsers = {
  */
 exports.loadConfig = filepath => {
   let config = {};
-  debug(`loadConfig: "${filepath}"`);
+  debug('loadConfig: trying to parse config at %s', filepath);
 
   const ext = path.extname(filepath);
   try {
@@ -93,10 +94,10 @@ exports.loadConfig = filepath => {
  * @param {string} [cwd] - Current working directory
  * @returns {string|null} Filepath to config, if found
  */
-exports.findConfig = (cwd = process.cwd()) => {
+exports.findConfig = (cwd = utils.cwd()) => {
   const filepath = findUp.sync(exports.CONFIG_FILES, {cwd});
   if (filepath) {
-    debug(`findConfig: found "${filepath}"`);
+    debug('findConfig: found config file %s', filepath);
   }
   return filepath;
 };

package/lib/cli/options.js

@@ -244,16 +244,16 @@ const loadPkgRc = (args = {}) => {
     try {
       const pkg = JSON.parse(fs.readFileSync(filepath, 'utf8'));
       if (pkg.mocha) {
-        debug(`'mocha' prop of package.json parsed:`, pkg.mocha);
+        debug('`mocha` prop of package.json parsed: %O', pkg.mocha);
         result = pkg.mocha;
       } else {
-        debug(`no config found in ${filepath}`);
+        debug('no config found in %s', filepath);
       }
     } catch (err) {
       if (args.package) {
         throw new Error(`Unable to read/parse ${filepath}: ${err}`);
       }
-      debug(`failed to read default package.json at ${filepath}; ignoring`);
+      debug('failed to read default package.json at %s; ignoring', filepath);
     }
   }
   return result;

package/lib/cli/run-helpers.js

@@ -12,8 +12,9 @@ const path = require('path');
 const debug = require('debug')('mocha:cli:run:helpers');
 const watchRun = require('./watch-run');
 const collectFiles = require('./collect-files');
-
-const cwd = (exports.cwd = process.cwd());
+const {type} = require('../utils');
+const {format} = require('util');
+const {createInvalidPluginError, createUnsupportedError} = require('../errors');
 
 /**
  * Exits Mocha when tests + code under test has finished execution (default)
@@ -73,20 +74,60 @@ exports.list = str =>
   Array.isArray(str) ? exports.list(str.join(',')) : str.split(/ *, */);
 
 /**
- * `require()` the modules as required by `--require <require>`
+ * `require()` the modules as required by `--require <require>`.
+ *
+ * Returns array of `mochaHooks` exports, if any.
  * @param {string[]} requires - Modules to require
+ * @returns {Promise<MochaRootHookObject|MochaRootHookFunction>} Any root hooks
  * @private
  */
-exports.handleRequires = (requires = []) => {
-  requires.forEach(mod => {
+exports.handleRequires = async (requires = []) =>
+  requires.reduce((acc, mod) => {
     let modpath = mod;
-    if (fs.existsSync(mod, {cwd}) || fs.existsSync(`${mod}.js`, {cwd})) {
+    // this is relative to cwd
+    if (fs.existsSync(mod) || fs.existsSync(`${mod}.js`)) {
       modpath = path.resolve(mod);
-      debug(`resolved ${mod} to ${modpath}`);
+      debug('resolved required file %s to %s', mod, modpath);
     }
-    require(modpath);
-    debug(`loaded require "${mod}"`);
-  });
+    const requiredModule = require(modpath);
+    if (type(requiredModule) === 'object' && requiredModule.mochaHooks) {
+      const mochaHooksType = type(requiredModule.mochaHooks);
+      if (/function$/.test(mochaHooksType) || mochaHooksType === 'object') {
+        debug('found root hooks in required file %s', mod);
+        acc.push(requiredModule.mochaHooks);
+      } else {
+        throw createUnsupportedError(
+          'mochaHooks must be an object or a function returning (or fulfilling with) an object'
+        );
+      }
+    }
+    debug('loaded required module "%s"', mod);
+    return acc;
+  }, []);
+
+/**
+ * Loads root hooks as exported via `mochaHooks` from required files.
+ * These can be sync/async functions returning objects, or just objects.
+ * Flattens to a single object.
+ * @param {Array<MochaRootHookObject|MochaRootHookFunction>} rootHooks - Array of root hooks
+ * @private
+ * @returns {MochaRootHookObject}
+ */
+exports.loadRootHooks = async rootHooks => {
+  const rootHookObjects = await Promise.all(
+    rootHooks.map(async hook => (/function$/.test(type(hook)) ? hook() : hook))
+  );
+
+  return rootHookObjects.reduce(
+    (acc, hook) => {
+      acc.beforeAll = acc.beforeAll.concat(hook.beforeAll || []);
+      acc.beforeEach = acc.beforeEach.concat(hook.beforeEach || []);
+      acc.afterAll = acc.afterAll.concat(hook.afterAll || []);
+      acc.afterEach = acc.afterEach.concat(hook.afterEach || []);
+      return acc;
+    },
+    {beforeAll: [], beforeEach: [], afterAll: [], afterEach: []}
+  );
 };
 
 /**
@@ -101,9 +142,10 @@ exports.handleRequires = (requires = []) => {
  */
 const singleRun = async (mocha, {exit}, fileCollectParams) => {
   const files = collectFiles(fileCollectParams);
-  debug('running tests with files', files);
+  debug('single run with %d file(s)', files.length);
   mocha.files = files;
 
+  // handles ESM modules
   await mocha.loadFilesAsync();
   return mocha.run(exit ? exitMocha : exitMochaLater);
 };
@@ -146,35 +188,52 @@ exports.runMocha = async (mocha, options) => {
 };
 
 /**
- * Used for `--reporter` and `--ui`.  Ensures there's only one, and asserts
- * that it actually exists.
- * @todo XXX This must get run after requires are processed, as it'll prevent
- * interfaces from loading.
+ * Used for `--reporter` and `--ui`.  Ensures there's only one, and asserts that
+ * it actually exists. This must be run _after_ requires are processed (see
+ * {@link handleRequires}), as it'll prevent interfaces from loading otherwise.
  * @param {Object} opts - Options object
- * @param {string} key - Resolvable module name or path
- * @param {Object} [map] - An object perhaps having key `key`
+ * @param {"reporter"|"interface"} pluginType - Type of plugin.
+ * @param {Object} [map] - An object perhaps having key `key`. Used as a cache
+ * of sorts; `Mocha.reporters` is one, where each key corresponds to a reporter
+ * name
  * @private
  */
-exports.validatePlugin = (opts, key, map = {}) => {
-  if (Array.isArray(opts[key])) {
-    throw new TypeError(`"--${key} <${key}>" can only be specified once`);
+exports.validatePlugin = (opts, pluginType, map = {}) => {
+  /**
+   * This should be a unique identifier; either a string (present in `map`),
+   * or a resolvable (via `require.resolve`) module ID/path.
+   * @type {string}
+   */
+  const pluginId = opts[pluginType];
+
+  if (Array.isArray(pluginId)) {
+    throw createInvalidPluginError(
+      `"--${pluginType}" can only be specified once`,
+      pluginType
+    );
   }
 
-  const unknownError = () => new Error(`Unknown "${key}": ${opts[key]}`);
+  const unknownError = err =>
+    createInvalidPluginError(
+      format('Could not load %s "%s":\n\n %O', pluginType, pluginId, err),
+      pluginType,
+      pluginId
+    );
 
-  if (!map[opts[key]]) {
+  // if this exists, then it's already loaded, so nothing more to do.
+  if (!map[pluginId]) {
     try {
-      opts[key] = require(opts[key]);
+      opts[pluginType] = require(pluginId);
     } catch (err) {
       if (err.code === 'MODULE_NOT_FOUND') {
         // Try to load reporters from a path (absolute or relative)
         try {
-          opts[key] = require(path.resolve(process.cwd(), opts[key]));
+          opts[pluginType] = require(path.resolve(pluginId));
         } catch (err) {
-          throw unknownError();
+          throw unknownError(err);
         }
       } else {
-        throw unknownError();
+        throw unknownError(err);
       }
     }
   }

package/lib/cli/run.js

@@ -18,6 +18,7 @@ const {
   list,
   handleRequires,
   validatePlugin,
+  loadRootHooks,
   runMocha
 } = require('./run-helpers');
 const {ONE_AND_DONES, ONE_AND_DONE_ARGS} = require('./one-and-dones');
@@ -285,12 +286,24 @@ exports.builder = yargs =>
         );
       }
 
+      if (argv.opts) {
+        throw createUnsupportedError(
+          `--opts: configuring Mocha via 'mocha.opts' is DEPRECATED and no longer supported.
+          Please use a configuration file instead.`
+        );
+      }
+
+      return true;
+    })
+    .middleware(async argv => {
       // load requires first, because it can impact "plugin" validation
-      handleRequires(argv.require);
+      const rawRootHooks = await handleRequires(argv.require);
       validatePlugin(argv, 'reporter', Mocha.reporters);
       validatePlugin(argv, 'ui', Mocha.interfaces);
 
-      return true;
+      if (rawRootHooks.length) {
+        argv.rootHooks = await loadRootHooks(rawRootHooks);
+      }
     })
     .array(types.array)
     .boolean(types.boolean)

package/lib/errors.js

@@ -1,10 +1,73 @@
 'use strict';
+
+var format = require('util').format;
+
 /**
+ * Factory functions to create throwable error objects
  * @module Errors
  */
+
 /**
- * Factory functions to create throwable error objects
+ * When Mocha throw exceptions (or otherwise errors), it attempts to assign a
+ * `code` property to the `Error` object, for easier handling.  These are the
+ * potential values of `code`.
  */
+var constants = {
+  /**
+   * An unrecoverable error.
+   */
+  FATAL: 'ERR_MOCHA_FATAL',
+
+  /**
+   * The type of an argument to a function call is invalid
+   */
+  INVALID_ARG_TYPE: 'ERR_MOCHA_INVALID_ARG_TYPE',
+
+  /**
+   * The value of an argument to a function call is invalid
+   */
+  INVALID_ARG_VALUE: 'ERR_MOCHA_INVALID_ARG_VALUE',
+
+  /**
+   * Something was thrown, but it wasn't an `Error`
+   */
+  INVALID_EXCEPTION: 'ERR_MOCHA_INVALID_EXCEPTION',
+
+  /**
+   * An interface (e.g., `Mocha.interfaces`) is unknown or invalid
+   */
+  INVALID_INTERFACE: 'ERR_MOCHA_INVALID_INTERFACE',
+
+  /**
+   * A reporter (.e.g, `Mocha.reporters`) is unknown or invalid
+   */
+  INVALID_REPORTER: 'ERR_MOCHA_INVALID_REPORTER',
+
+  /**
+   * `done()` was called twice in a `Test` or `Hook` callback
+   */
+  MULTIPLE_DONE: 'ERR_MOCHA_MULTIPLE_DONE',
+
+  /**
+   * No files matched the pattern provided by the user
+   */
+  NO_FILES_MATCH_PATTERN: 'ERR_MOCHA_NO_FILES_MATCH_PATTERN',
+
+  /**
+   * Known, but unsupported behavior of some kind
+   */
+  UNSUPPORTED: 'ERR_MOCHA_UNSUPPORTED',
+
+  /**
+   * Invalid state transition occuring in `Mocha` instance
+   */
+  INSTANCE_ALREADY_RUNNING: 'ERR_MOCHA_INSTANCE_ALREADY_RUNNING',
+
+  /**
+   * Invalid state transition occuring in `Mocha` instance
+   */
+  INSTANCE_ALREADY_DISPOSED: 'ERR_MOCHA_INSTANCE_ALREADY_DISPOSED'
+};
 
 /**
  * Creates an error object to be thrown when no files to be tested could be found using specified pattern.
@@ -16,7 +79,7 @@
  */
 function createNoFilesMatchPatternError(message, pattern) {
   var err = new Error(message);
-  err.code = 'ERR_MOCHA_NO_FILES_MATCH_PATTERN';
+  err.code = constants.NO_FILES_MATCH_PATTERN;
   err.pattern = pattern;
   return err;
 }
@@ -31,7 +94,7 @@ function createNoFilesMatchPatternError(message, pattern) {
  */
 function createInvalidReporterError(message, reporter) {
   var err = new TypeError(message);
-  err.code = 'ERR_MOCHA_INVALID_REPORTER';
+  err.code = constants.INVALID_REPORTER;
   err.reporter = reporter;
   return err;
 }
@@ -46,7 +109,7 @@ function createInvalidReporterError(message, reporter) {
  */
 function createInvalidInterfaceError(message, ui) {
   var err = new Error(message);
-  err.code = 'ERR_MOCHA_INVALID_INTERFACE';
+  err.code = constants.INVALID_INTERFACE;
   err.interface = ui;
   return err;
 }
@@ -60,7 +123,7 @@ function createInvalidInterfaceError(message, ui) {
  */
 function createUnsupportedError(message) {
   var err = new Error(message);
-  err.code = 'ERR_MOCHA_UNSUPPORTED';
+  err.code = constants.UNSUPPORTED;
   return err;
 }
 
@@ -88,7 +151,7 @@ function createMissingArgumentError(message, argument, expected) {
  */
 function createInvalidArgumentTypeError(message, argument, expected) {
   var err = new TypeError(message);
-  err.code = 'ERR_MOCHA_INVALID_ARG_TYPE';
+  err.code = constants.INVALID_ARG_TYPE;
   err.argument = argument;
   err.expected = expected;
   err.actual = typeof argument;
@@ -107,7 +170,7 @@ function createInvalidArgumentTypeError(message, argument, expected) {
  */
 function createInvalidArgumentValueError(message, argument, value, reason) {
   var err = new TypeError(message);
-  err.code = 'ERR_MOCHA_INVALID_ARG_VALUE';
+  err.code = constants.INVALID_ARG_VALUE;
   err.argument = argument;
   err.value = value;
   err.reason = typeof reason !== 'undefined' ? reason : 'is invalid';
@@ -123,12 +186,113 @@ function createInvalidArgumentValueError(message, argument, value, reason) {
  */
 function createInvalidExceptionError(message, value) {
   var err = new Error(message);
-  err.code = 'ERR_MOCHA_INVALID_EXCEPTION';
+  err.code = constants.INVALID_EXCEPTION;
+  err.valueType = typeof value;
+  err.value = value;
+  return err;
+}
+
+/**
+ * Creates an error object to be thrown when an unrecoverable error occurs.
+ *
+ * @public
+ * @param {string} message - Error message to be displayed.
+ * @returns {Error} instance detailing the error condition
+ */
+function createFatalError(message, value) {
+  var err = new Error(message);
+  err.code = constants.FATAL;
   err.valueType = typeof value;
   err.value = value;
   return err;
 }
 
+/**
+ * Dynamically creates a plugin-type-specific error based on plugin type
+ * @param {string} message - Error message
+ * @param {"reporter"|"interface"} pluginType - Plugin type. Future: expand as needed
+ * @param {string} [pluginId] - Name/path of plugin, if any
+ * @throws When `pluginType` is not known
+ * @public
+ * @returns {Error}
+ */
+function createInvalidPluginError(message, pluginType, pluginId) {
+  switch (pluginType) {
+    case 'reporter':
+      return createInvalidReporterError(message, pluginId);
+    case 'interface':
+      return createInvalidInterfaceError(message, pluginId);
+    default:
+      throw new Error('unknown pluginType "' + pluginType + '"');
+  }
+}
+
+/**
+ * Creates an error object to be thrown when a mocha object's `run` method is executed while it is already disposed.
+ * @param {string} message The error message to be displayed.
+ * @param {boolean} cleanReferencesAfterRun the value of `cleanReferencesAfterRun`
+ * @param {Mocha} instance the mocha instance that throw this error
+ */
+function createMochaInstanceAlreadyDisposedError(
+  message,
+  cleanReferencesAfterRun,
+  instance
+) {
+  var err = new Error(message);
+  err.code = constants.INSTANCE_ALREADY_DISPOSED;
+  err.cleanReferencesAfterRun = cleanReferencesAfterRun;
+  err.instance = instance;
+  return err;
+}
+
+/**
+ * Creates an error object to be thrown when a mocha object's `run` method is called while a test run is in progress.
+ * @param {string} message The error message to be displayed.
+ */
+function createMochaInstanceAlreadyRunningError(message, instance) {
+  var err = new Error(message);
+  err.code = constants.INSTANCE_ALREADY_RUNNING;
+  err.instance = instance;
+  return err;
+}
+
+/*
+ * Creates an error object to be thrown when done() is called multiple times in a test
+ *
+ * @public
+ * @param {Runnable} runnable - Original runnable
+ * @param {Error} [originalErr] - Original error, if any
+ * @returns {Error} instance detailing the error condition
+ */
+function createMultipleDoneError(runnable, originalErr) {
+  var title;
+  try {
+    title = format('<%s>', runnable.fullTitle());
+    if (runnable.parent.root) {
+      title += ' (of root suite)';
+    }
+  } catch (ignored) {
+    title = format('<%s> (of unknown suite)', runnable.title);
+  }
+  var message = format(
+    'done() called multiple times in %s %s',
+    runnable.type ? runnable.type : 'unknown runnable',
+    title
+  );
+  if (runnable.file) {
+    message += format(' of file %s', runnable.file);
+  }
+  if (originalErr) {
+    message += format('; in addition, done() received error: %s', originalErr);
+  }
+
+  var err = new Error(message);
+  err.code = constants.MULTIPLE_DONE;
+  err.valueType = typeof originalErr;
+  err.value = originalErr;
+  return err;
+}
+
 module.exports = {
   createInvalidArgumentTypeError: createInvalidArgumentTypeError,
   createInvalidArgumentValueError: createInvalidArgumentValueError,
@@ -137,5 +301,11 @@ module.exports = {
   createInvalidReporterError: createInvalidReporterError,
   createMissingArgumentError: createMissingArgumentError,
   createNoFilesMatchPatternError: createNoFilesMatchPatternError,
-  createUnsupportedError: createUnsupportedError
+  createUnsupportedError: createUnsupportedError,
+  createInvalidPluginError: createInvalidPluginError,
+  createMochaInstanceAlreadyDisposedError: createMochaInstanceAlreadyDisposedError,
+  createMochaInstanceAlreadyRunningError: createMochaInstanceAlreadyRunningError,
+  createFatalError: createFatalError,
+  createMultipleDoneError: createMultipleDoneError,
+  constants: constants
 };

package/lib/hook.js

@@ -27,6 +27,14 @@ function Hook(title, fn) {
  */
 inherits(Hook, Runnable);
 
+/**
+ * Resets the state for a next run.
+ */
+Hook.prototype.reset = function() {
+  Runnable.prototype.reset.call(this);
+  delete this._error;
+};
+
 /**
  * Get or set the test `err`.
  *