mocha 7.0.1 → 7.2.0

package/CHANGELOG.md

@@ -1,3 +1,87 @@
+# 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
+
+- [#4251](https://github.com/mochajs/mocha/issues/4251): Prevent karma-mocha from stalling ([**@juergba**](https://github.com/juergba))
+- [#4222](https://github.com/mochajs/mocha/issues/4222): Update dependency mkdirp to v0.5.5 ([**@outsideris**](https://github.com/outsideris))
+
+## :book: Documentation
+
+- [#4208](https://github.com/mochajs/mocha/issues/4208): Add Wallaby logo to site ([**@boneskull**](https://github.com/boneskull))
+
+# 7.1.1 / 2020-03-18
+
+## :lock: Security Fixes
+
+- [#4204](https://github.com/mochajs/mocha/issues/4204): Update dependencies mkdirp, yargs-parser and yargs ([**@juergba**](https://github.com/juergba))
+
+## :bug: Fixes
+
+- [#3660](https://github.com/mochajs/mocha/issues/3660): Fix `runner` listening to `start` and `end` events ([**@juergba**](https://github.com/juergba))
+
+## :book: Documentation
+
+- [#4190](https://github.com/mochajs/mocha/issues/4190): Show Netlify badge on footer ([**@outsideris**](https://github.com/outsideris))
+
+# 7.1.0 / 2020-02-26
+
+## :tada: Enhancements
+
+[#4038](https://github.com/mochajs/mocha/issues/4038): Add Node.js native ESM support ([**@giltayar**](https://github.com/giltayar))
+
+Mocha supports writing your test files as ES modules:
+
+- Node.js only v12.11.0 and above
+- Node.js below v13.2.0, you must set `--experimental-modules` option
+- current limitations: please check our [documentation](https://mochajs.org/#nodejs-native-esm-support)
+- for programmatic usage: see [API: loadFilesAsync()](https://mochajs.org/api/mocha#loadFilesAsync)
+
+**Note:** Node.JS native [ECMAScript Modules](https://nodejs.org/api/esm.html) implementation has status: **Stability: 1 - Experimental**
+
+## :bug: Fixes
+
+- [#4181](https://github.com/mochajs/mocha/issues/4181): Programmatic API cannot access retried test objects ([**@juergba**](https://github.com/juergba))
+- [#4174](https://github.com/mochajs/mocha/issues/4174): Browser: fix `allowUncaught` option ([**@juergba**](https://github.com/juergba))
+
+## :book: Documentation
+
+- [#4058](https://github.com/mochajs/mocha/issues/4058): Manage author list in AUTHORS instead of `package.json` ([**@outsideris**](https://github.com/outsideris))
+
+## :nut_and_bolt: Other
+
+- [#4138](https://github.com/mochajs/mocha/issues/4138): Upgrade ESLint v6.8 ([**@kaicataldo**](https://github.com/kaicataldo))
+
 # 7.0.1 / 2020-01-25
 
 ## :bug: Fixes
@@ -493,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);
@@ -506,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.
  */
@@ -60,7 +71,7 @@ process.on = function(e, fn) {
   if (e === 'uncaughtException') {
     global.onerror = function(err, url, line) {
       fn(new Error(err + ' (' + url + ':' + line + ')'));
-      return !mocha.allowUncaught;
+      return !mocha.options.allowUncaught;
     };
     uncaughtExceptionHandlers.push(fn);
   }
@@ -129,7 +140,7 @@ mocha.setup = function(opts) {
     opts = {ui: opts};
   }
   for (var opt in opts) {
-    if (opts.hasOwnProperty(opt)) {
+    if (Object.prototype.hasOwnProperty.call(opts, opt)) {
       this[opt](opts[opt]);
     }
   }

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;
@@ -21,6 +22,7 @@ const findUp = require('find-up');
  * @private
  */
 exports.CONFIG_FILES = [
+  '.mocharc.cjs',
   '.mocharc.js',
   '.mocharc.yaml',
   '.mocharc.yml',
@@ -42,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
@@ -69,13 +71,13 @@ 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 {
     if (ext === '.yml' || ext === '.yaml') {
       config = parsers.yaml(filepath);
-    } else if (ext === '.js') {
+    } else if (ext === '.js' || ext === '.cjs') {
       config = parsers.js(filepath);
     } else {
       config = parsers.json(filepath);
@@ -92,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;
@@ -265,7 +265,7 @@ module.exports.loadPkgRc = loadPkgRc;
  * Priority list:
  *
  * 1. Command-line args
- * 2. RC file (`.mocharc.js`, `.mocharc.ya?ml`, `mocharc.json`)
+ * 2. RC file (`.mocharc.c?js`, `.mocharc.ya?ml`, `mocharc.json`)
  * 3. `mocha` prop of `package.json`
  * 4. `mocha.opts`
  * 5. default configuration (`lib/mocharc.json`)

package/lib/cli/run-helpers.js

@@ -12,10 +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());
-
-exports.watchRun = watchRun;
+const {type} = require('../utils');
+const {format} = require('util');
+const {createInvalidPluginError, createUnsupportedError} = require('../errors');
 
 /**
  * Exits Mocha when tests + code under test has finished execution (default)
@@ -75,36 +74,79 @@ 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: []}
+  );
 };
 
 /**
- * Collect test files and run mocha instance.
+ * Collect and load test files, then run mocha instance.
  * @param {Mocha} mocha - Mocha instance
  * @param {Options} [opts] - Command line options
  * @param {boolean} [opts.exit] - Whether or not to force-exit after tests are complete
  * @param {Object} fileCollectParams - Parameters that control test
  *   file collection. See `lib/cli/collect-files.js`.
- * @returns {Runner}
+ * @returns {Promise<Runner>}
  * @private
  */
-exports.singleRun = (mocha, {exit}, fileCollectParams) => {
+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);
 };
 
@@ -113,8 +155,9 @@ exports.singleRun = (mocha, {exit}, fileCollectParams) => {
  * @param {Mocha} mocha - Mocha instance
  * @param {Object} opts - Command line options
  * @private
+ * @returns {Promise}
  */
-exports.runMocha = (mocha, options) => {
+exports.runMocha = async (mocha, options) => {
   const {
     watch = false,
     extension = [],
@@ -140,40 +183,57 @@ exports.runMocha = (mocha, options) => {
   if (watch) {
     watchRun(mocha, {watchFiles, watchIgnore}, fileCollectParams);
   } else {
-    exports.singleRun(mocha, {exit}, fileCollectParams);
+    await singleRun(mocha, {exit}, fileCollectParams);
   }
 };
 
 /**
- * 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');
@@ -87,7 +88,6 @@ exports.builder = yargs =>
       },
       extension: {
         default: defaults.extension,
-        defaultDescription: 'js',
         description: 'File extension(s) to load',
         group: GROUPS.FILES,
         requiresArg: true,
@@ -286,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)
@@ -299,8 +311,14 @@ exports.builder = yargs =>
     .number(types.number)
     .alias(aliases);
 
-exports.handler = argv => {
+exports.handler = async function(argv) {
   debug('post-yargs config', argv);
   const mocha = new Mocha(argv);
-  runMocha(mocha, argv);
+
+  try {
+    await runMocha(mocha, argv);
+  } catch (err) {
+    console.error('\n' + (err.stack || `Error: ${err.message || err}`));
+    process.exit(1);
+  }
 };