mocha 7.0.0 → 7.1.2

package/LICENSE

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2011-2018 JS Foundation and contributors, https://js.foundation
+Copyright (c) 2011-2020 OpenJS Foundation and contributors, https://openjsf.org
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

package/README.md

@@ -100,6 +100,6 @@ Finally, come [chat with the maintainers](https://gitter.im/mochajs/contributors
 
 ## License
 
-[MIT](LICENSE)
+Copyright 2011-2020 OpenJS Foundation and contributors. Licensed [MIT](https://github.com/mochajs/mocha/blob/master/LICENSE).
 
 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha.svg?type=large)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha?ref=badge_large)

package/browser-entry.js

@@ -60,7 +60,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 +129,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/config.js

@@ -21,6 +21,7 @@ const findUp = require('find-up');
  * @private
  */
 exports.CONFIG_FILES = [
+  '.mocharc.cjs',
   '.mocharc.js',
   '.mocharc.yaml',
   '.mocharc.yml',
@@ -75,7 +76,7 @@ exports.loadConfig = 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);

package/lib/cli/options.js

@@ -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

@@ -15,8 +15,6 @@ const collectFiles = require('./collect-files');
 
 const cwd = (exports.cwd = process.cwd());
 
-exports.watchRun = watchRun;
-
 /**
  * Exits Mocha when tests + code under test has finished execution (default)
  * @param {number} code - Exit code; typically # of failures
@@ -92,19 +90,21 @@ exports.handleRequires = (requires = []) => {
 };
 
 /**
- * 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);
   mocha.files = files;
+
+  await mocha.loadFilesAsync();
   return mocha.run(exit ? exitMocha : exitMochaLater);
 };
 
@@ -113,8 +113,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,7 +141,7 @@ exports.runMocha = (mocha, options) => {
   if (watch) {
     watchRun(mocha, {watchFiles, watchIgnore}, fileCollectParams);
   } else {
-    exports.singleRun(mocha, {exit}, fileCollectParams);
+    await singleRun(mocha, {exit}, fileCollectParams);
   }
 };
 

package/lib/cli/run.js

@@ -87,7 +87,6 @@ exports.builder = yargs =>
       },
       extension: {
         default: defaults.extension,
-        defaultDescription: 'js',
         description: 'File extension(s) to load',
         group: GROUPS.FILES,
         requiresArg: true,
@@ -299,8 +298,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);
+  }
 };

package/lib/esm-utils.js

@@ -0,0 +1,31 @@
+const url = require('url');
+const path = require('path');
+
+const requireOrImport = async file => {
+  file = path.resolve(file);
+
+  if (path.extname(file) === '.mjs') {
+    return import(url.pathToFileURL(file));
+  }
+  // This is currently the only known way of figuring out whether a file is CJS or ESM.
+  // If Node.js or the community establish a better procedure for that, we can fix this code.
+  // Another option here would be to always use `import()`, as this also supports CJS, but I would be
+  // wary of using it for _all_ existing test files, till ESM is fully stable.
+  try {
+    return require(file);
+  } catch (err) {
+    if (err.code === 'ERR_REQUIRE_ESM') {
+      return import(url.pathToFileURL(file));
+    } else {
+      throw err;
+    }
+  }
+};
+
+exports.loadFilesAsync = async (files, preLoadFunc, postLoadFunc) => {
+  for (const file of files) {
+    preLoadFunc(file);
+    const result = await requireOrImport(file);
+    postLoadFunc(file, result);
+  }
+};

package/lib/mocha.js

@@ -14,6 +14,7 @@ var utils = require('./utils');
 var mocharc = require('./mocharc.json');
 var errors = require('./errors');
 var Suite = require('./suite');
+var esmUtils = utils.supportsEsModules() ? require('./esm-utils') : undefined;
 var createStatsCollector = require('./stats-collector');
 var createInvalidReporterError = errors.createInvalidReporterError;
 var createInvalidInterfaceError = errors.createInvalidInterfaceError;
@@ -100,7 +101,10 @@ function Mocha(options) {
   this.grep(options.grep)
     .fgrep(options.fgrep)
     .ui(options.ui)
-    .reporter(options.reporter, options.reporterOption)
+    .reporter(
+      options.reporter,
+      options.reporterOption || options.reporterOptions // reporterOptions was previously the only way to specify options to reporter
+    )
     .slow(options.slow)
     .global(options.global);
 
@@ -287,16 +291,18 @@ Mocha.prototype.ui = function(ui) {
 };
 
 /**
- * Loads `files` prior to execution.
+ * Loads `files` prior to execution. Does not support ES Modules.
  *
  * @description
  * The implementation relies on Node's `require` to execute
  * the test interface functions and will be subject to its cache.
+ * Supports only CommonJS modules. To load ES modules, use Mocha#loadFilesAsync.
  *
  * @private
  * @see {@link Mocha#addFile}
  * @see {@link Mocha#run}
  * @see {@link Mocha#unloadFiles}
+ * @see {@link Mocha#loadFilesAsync}
  * @param {Function} [fn] - Callback invoked upon completion.
  */
 Mocha.prototype.loadFiles = function(fn) {
@@ -311,6 +317,49 @@ Mocha.prototype.loadFiles = function(fn) {
   fn && fn();
 };
 
+/**
+ * Loads `files` prior to execution. Supports Node ES Modules.
+ *
+ * @description
+ * The implementation relies on Node's `require` and `import` to execute
+ * the test interface functions and will be subject to its cache.
+ * Supports both CJS and ESM modules.
+ *
+ * @public
+ * @see {@link Mocha#addFile}
+ * @see {@link Mocha#run}
+ * @see {@link Mocha#unloadFiles}
+ * @returns {Promise}
+ * @example
+ *
+ * // loads ESM (and CJS) test files asynchronously, then runs root suite
+ * mocha.loadFilesAsync()
+ *   .then(() => mocha.run(failures => process.exitCode = failures ? 1 : 0))
+ *   .catch(() => process.exitCode = 1);
+ */
+Mocha.prototype.loadFilesAsync = function() {
+  var self = this;
+  var suite = this.suite;
+  this.loadAsync = true;
+
+  if (!esmUtils) {
+    return new Promise(function(resolve) {
+      self.loadFiles(resolve);
+    });
+  }
+
+  return esmUtils.loadFilesAsync(
+    this.files,
+    function(file) {
+      suite.emit(EVENT_FILE_PRE_REQUIRE, global, file, self);
+    },
+    function(file, resultModule) {
+      suite.emit(EVENT_FILE_REQUIRE, resultModule, file, self);
+      suite.emit(EVENT_FILE_POST_REQUIRE, global, file, self);
+    }
+  );
+};
+
 /**
  * Removes a previously loaded file from Node's `require` cache.
  *
@@ -327,8 +376,9 @@ Mocha.unloadFile = function(file) {
  * Unloads `files` from Node's `require` cache.
  *
  * @description
- * This allows files to be "freshly" reloaded, providing the ability
+ * This allows required files to be "freshly" reloaded, providing the ability
  * to reuse a Mocha instance programmatically.
+ * Note: does not clear ESM module files from the cache
  *
  * <strong>Intended for consumers &mdash; not used internally</strong>
  *
@@ -839,10 +889,14 @@ Object.defineProperty(Mocha.prototype, 'version', {
  * @see {@link Mocha#unloadFiles}
  * @see {@link Runner#run}
  * @param {DoneCB} [fn] - Callback invoked when test execution completed.
- * @return {Runner} runner instance
+ * @returns {Runner} runner instance
+ * @example
+ *
+ * // exit with non-zero status if there were test failures
+ * mocha.run(failures => process.exitCode = failures ? 1 : 0);
  */
 Mocha.prototype.run = function(fn) {
-  if (this.files.length) {
+  if (this.files.length && !this.loadAsync) {
     this.loadFiles();
   }
   var suite = this.suite;

package/lib/mocharc.json

@@ -1,6 +1,6 @@
 {
   "diff": true,
-  "extension": ["js"],
+  "extension": ["js", "cjs", "mjs"],
   "opts": "./test/mocha.opts",
   "package": "./package.json",
   "reporter": "spec",

package/lib/runnable.js

@@ -222,31 +222,6 @@ Runnable.prototype.clearTimeout = function() {
   clearTimeout(this.timer);
 };
 
-/**
- * Inspect the runnable void of private properties.
- *
- * @private
- * @return {string}
- */
-Runnable.prototype.inspect = function() {
-  return JSON.stringify(
-    this,
-    function(key, val) {
-      if (key[0] === '_') {
-        return;
-      }
-      if (key === 'parent') {
-        return '#<Suite>';
-      }
-      if (key === 'ctx') {
-        return '#<Context>';
-      }
-      return val;
-    },
-    2
-  );
-};
-
 /**
  * Reset the timeout.
  *
@@ -335,9 +310,18 @@ Runnable.prototype.run = function(fn) {
     fn(err);
   }
 
-  // for .resetTimeout()
+  // for .resetTimeout() and Runner#uncaught()
   this.callback = done;
 
+  if (this.fn && typeof this.fn.call !== 'function') {
+    done(
+      new TypeError(
+        'A runnable must be passed a function as its second argument.'
+      )
+    );
+    return;
+  }
+
   // explicit async with `done` argument
   if (this.async) {
     this.resetTimeout();

package/lib/runner.js

@@ -19,7 +19,6 @@ var EVENT_ROOT_SUITE_RUN = Suite.constants.EVENT_ROOT_SUITE_RUN;
 var STATE_FAILED = Runnable.constants.STATE_FAILED;
 var STATE_PASSED = Runnable.constants.STATE_PASSED;
 var dQuote = utils.dQuote;
-var ngettext = utils.ngettext;
 var sQuote = utils.sQuote;
 var stackFilter = utils.stackTraceFilter();
 var stringify = utils.stringify;
@@ -135,6 +134,11 @@ function Runner(suite, delay) {
   this.total = suite.total();
   this.failures = 0;
   this.on(constants.EVENT_TEST_END, function(test) {
+    if (test.type === 'test' && test.retriedTest() && test.parent) {
+      var idx =
+        test.parent.tests && test.parent.tests.indexOf(test.retriedTest());
+      if (idx > -1) test.parent.tests[idx] = test;
+    }
     self.checkGlobals(test);
   });
   this.on(constants.EVENT_HOOK_END, function(hook) {
@@ -266,12 +270,8 @@ Runner.prototype.checkGlobals = function(test) {
   this._globals = this._globals.concat(leaks);
 
   if (leaks.length) {
-    var format = ngettext(
-      leaks.length,
-      'global leak detected: %s',
-      'global leaks detected: %s'
-    );
-    var error = new Error(util.format(format, leaks.map(sQuote).join(', ')));
+    var msg = 'global leak(s) detected: %s';
+    var error = new Error(util.format(msg, leaks.map(sQuote).join(', ')));
     this.fail(test, error);
   }
 };
@@ -654,7 +654,7 @@ Runner.prototype.runTests = function(suite, fn) {
         self.emit(constants.EVENT_TEST_END, test);
         // skip inner afterEach hooks below errSuite level
         var origSuite = self.suite;
-        self.suite = errSuite;
+        self.suite = errSuite || self.suite;
         return self.hookUp(HOOK_TYPE_AFTER_EACH, function(e, eSuite) {
           self.suite = origSuite;
           next(e, eSuite);
@@ -724,7 +724,6 @@ Runner.prototype.runSuite = function(suite, fn) {
   var i = 0;
   var self = this;
   var total = this.grepTotal(suite);
-  var afterAllHookCalled = false;
 
   debug('run suite %s', suite.fullTitle());
 
@@ -772,21 +771,13 @@ Runner.prototype.runSuite = function(suite, fn) {
     self.suite = suite;
     self.nextSuite = next;
 
-    if (afterAllHookCalled) {
-      fn(errSuite);
-    } else {
-      // mark that the afterAll block has been called once
-      // and so can be skipped if there is an error in it.
-      afterAllHookCalled = true;
+    // remove reference to test
+    delete self.test;
 
-      // remove reference to test
-      delete self.test;
-
-      self.hook(HOOK_TYPE_AFTER_ALL, function() {
-        self.emit(constants.EVENT_SUITE_END, suite);
-        fn(errSuite);
-      });
-    }
+    self.hook(HOOK_TYPE_AFTER_ALL, function() {
+      self.emit(constants.EVENT_SUITE_END, suite);
+      fn(errSuite);
+    });
   }
 
   this.nextSuite = next;
@@ -800,7 +791,7 @@ Runner.prototype.runSuite = function(suite, fn) {
 };
 
 /**
- * Handle uncaught exceptions.
+ * Handle uncaught exceptions within runner.
  *
  * @param {Error} err
  * @private
@@ -809,7 +800,8 @@ Runner.prototype.uncaught = function(err) {
   if (err instanceof Pending) {
     return;
   }
-  if (this.allowUncaught) {
+  // browser does not exit script when throwing in global.onerror()
+  if (this.allowUncaught && !process.browser) {
     throw err;
   }
 
@@ -861,36 +853,24 @@ Runner.prototype.uncaught = function(err) {
 
   // we cannot recover gracefully if a Runnable has already passed
   // then fails asynchronously
-  var alreadyPassed = runnable.isPassed();
-  // this will change the state to "failed" regardless of the current value
-  this.fail(runnable, err);
-  if (!alreadyPassed) {
-    // recover from test
-    if (runnable.type === constants.EVENT_TEST_BEGIN) {
-      this.emit(constants.EVENT_TEST_END, runnable);
-      this.hookUp(HOOK_TYPE_AFTER_EACH, this.next);
-      return;
-    }
+  if (runnable.isPassed()) {
+    this.fail(runnable, err);
+    this.abort();
+  } else {
     debug(runnable);
-
-    // recover from hooks
-    var errSuite = this.suite;
-
-    // XXX how about a less awful way to determine this?
-    // if hook failure is in afterEach block
-    if (runnable.fullTitle().indexOf('after each') > -1) {
-      return this.hookErr(err, errSuite, true);
-    }
-    // if hook failure is in beforeEach block
-    if (runnable.fullTitle().indexOf('before each') > -1) {
-      return this.hookErr(err, errSuite, false);
-    }
-    // if hook failure is in after or before blocks
-    return this.nextSuite(errSuite);
+    return runnable.callback(err);
   }
+};
 
-  // bail
-  this.abort();
+/**
+ * Handle uncaught exceptions after runner's end event.
+ *
+ * @param {Error} err
+ * @private
+ */
+Runner.prototype.uncaughtEnd = function uncaughtEnd(err) {
+  if (err instanceof Pending) return;
+  throw err;
 };
 
 /**
@@ -940,16 +920,12 @@ Runner.prototype.run = function(fn) {
   this.on(constants.EVENT_RUN_END, function() {
     debug(constants.EVENT_RUN_END);
     process.removeListener('uncaughtException', uncaught);
-    process.on('uncaughtException', function(err) {
-      if (err instanceof Pending) {
-        return;
-      }
-      throw err;
-    });
+    process.on('uncaughtException', self.uncaughtEnd);
     fn(self.failures);
   });
 
   // uncaught exception
+  process.removeListener('uncaughtException', self.uncaughtEnd);
   process.on('uncaughtException', uncaught);
 
   if (this._delay) {
@@ -958,7 +934,9 @@ Runner.prototype.run = function(fn) {
     this.emit(constants.EVENT_DELAY_BEGIN, rootSuite);
     rootSuite.once(EVENT_ROOT_SUITE_RUN, start);
   } else {
-    start();
+    Runner.immediately(function() {
+      start();
+    });
   }
 
   return this;

package/lib/test.js

@@ -36,6 +36,18 @@ function Test(title, fn) {
  */
 utils.inherits(Test, Runnable);
 
+/**
+ * Set or get retried test
+ *
+ * @private
+ */
+Test.prototype.retriedTest = function(n) {
+  if (!arguments.length) {
+    return this._retriedTest;
+  }
+  this._retriedTest = n;
+};
+
 Test.prototype.clone = function() {
   var test = new Test(this.title, this.fn);
   test.timeout(this.timeout());
@@ -43,6 +55,7 @@ Test.prototype.clone = function() {
   test.enableTimeouts(this.enableTimeouts());
   test.retries(this.retries());
   test.currentRetry(this.currentRetry());
+  test.retriedTest(this.retriedTest() || this);
   test.globals(this.globals());
   test.parent = this.parent;
   test.file = this.file;

package/lib/utils.js

@@ -753,38 +753,6 @@ exports.dQuote = function(str) {
   return '"' + str + '"';
 };
 
-/**
- * Provides simplistic message translation for dealing with plurality.
- *
- * @description
- * Use this to create messages which need to be singular or plural.
- * Some languages have several plural forms, so _complete_ message clauses
- * are preferable to generating the message on the fly.
- *
- * @private
- * @param {number} n - Non-negative integer
- * @param {string} msg1 - Message to be used in English for `n = 1`
- * @param {string} msg2 - Message to be used in English for `n = 0, 2, 3, ...`
- * @returns {string} message corresponding to value of `n`
- * @example
- * var sprintf = require('util').format;
- * var pkgs = ['one', 'two'];
- * var msg = sprintf(
- *   ngettext(
- *     pkgs.length,
- *     'cannot load package: %s',
- *     'cannot load packages: %s'
- *   ),
- *   pkgs.map(sQuote).join(', ')
- * );
- * console.log(msg); // => cannot load packages: 'one', 'two'
- */
-exports.ngettext = function(n, msg1, msg2) {
-  if (typeof n === 'number' && n >= 0) {
-    return n === 1 ? msg1 : msg2;
-  }
-};
-
 /**
  * It's a noop.
  * @public
@@ -831,3 +799,25 @@ exports.defineConstants = function(obj) {
   }
   return Object.freeze(exports.createMap(obj));
 };
+
+/**
+ * Whether current version of Node support ES modules
+ *
+ * @description
+ * Versions prior to 10 did not support ES Modules, and version 10 has an old incompatibile version of ESM.
+ * This function returns whether Node.JS has ES Module supports that is compatible with Mocha's needs,
+ * which is version >=12.11.
+ *
+ * @returns {Boolean} whether the current version of Node.JS supports ES Modules in a way that is compatible with Mocha
+ */
+exports.supportsEsModules = function() {
+  if (!process.browser && process.versions && process.versions.node) {
+    var versionFields = process.versions.node.split('.');
+    var major = +versionFields[0];
+    var minor = +versionFields[1];
+
+    if (major >= 13 || (major === 12 && minor >= 11)) {
+      return true;
+    }
+  }
+};