mocha 8.1.1 → 8.2.1

package/lib/runner.js

@@ -8,7 +8,6 @@ var util = require('util');
 var EventEmitter = require('events').EventEmitter;
 var Pending = require('./pending');
 var utils = require('./utils');
-var inherits = utils.inherits;
 var debug = require('debug')('mocha:runner');
 var Runnable = require('./runnable');
 var Suite = require('./suite');
@@ -24,11 +23,14 @@ var dQuote = utils.dQuote;
 var sQuote = utils.sQuote;
 var stackFilter = utils.stackTraceFilter();
 var stringify = utils.stringify;
-var type = utils.type;
-var errors = require('./errors');
-var createInvalidExceptionError = errors.createInvalidExceptionError;
-var createUnsupportedError = errors.createUnsupportedError;
-var createFatalError = errors.createFatalError;
+
+const {
+  createInvalidExceptionError,
+  createUnsupportedError,
+  createFatalError,
+  isMochaError,
+  constants: errorConstants
+} = require('./errors');
 
 /**
  * Non-enumerable globals.
@@ -128,54 +130,82 @@ var constants = utils.defineConstants(
   }
 );
 
-module.exports = Runner;
-
-/**
- * Initialize a `Runner` at the Root {@link Suite}, which represents a hierarchy of {@link Suite|Suites} and {@link Test|Tests}.
- *
- * @extends external:EventEmitter
- * @public
- * @class
- * @param {Suite} suite - Root suite
- * @param {Object|boolean} [opts] - Options. If `boolean`, whether or not to delay execution of root suite until ready (for backwards compatibility).
- * @param {boolean} [opts.delay] - Whether to delay execution of root suite until ready.
- * @param {boolean} [opts.cleanReferencesAfterRun] - Whether to clean references to test fns and hooks when a suite is done.
- */
-function Runner(suite, opts) {
-  if (opts === undefined) {
-    opts = {};
-  }
-  if (typeof opts === 'boolean') {
-    this._delay = opts;
-    opts = {};
-  } else {
-    this._delay = opts.delay;
-  }
-  var self = this;
-  this._globals = [];
-  this._abort = false;
-  this.suite = suite;
-  this._opts = opts;
-  this.state = constants.STATE_IDLE;
-  this.total = suite.total();
-  this.failures = 0;
-  this._eventListeners = [];
-  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;
+class Runner extends EventEmitter {
+  /**
+   * Initialize a `Runner` at the Root {@link Suite}, which represents a hierarchy of {@link Suite|Suites} and {@link Test|Tests}.
+   *
+   * @extends external:EventEmitter
+   * @public
+   * @class
+   * @param {Suite} suite - Root suite
+   * @param {Object|boolean} [opts] - Options. If `boolean`, whether or not to delay execution of root suite until ready (for backwards compatibility).
+   * @param {boolean} [opts.delay] - Whether to delay execution of root suite until ready.
+   * @param {boolean} [opts.cleanReferencesAfterRun] - Whether to clean references to test fns and hooks when a suite is done.
+   */
+  constructor(suite, opts) {
+    super();
+    if (opts === undefined) {
+      opts = {};
     }
-    self.checkGlobals(test);
-  });
-  this.on(constants.EVENT_HOOK_END, function(hook) {
-    self.checkGlobals(hook);
-  });
-  this._defaultGrep = /.*/;
-  this.grep(this._defaultGrep);
-  this.globals(this.globalProps());
-
-  this.uncaught = this._uncaught.bind(this);
+    if (typeof opts === 'boolean') {
+      // TODO: deprecate this
+      this._delay = opts;
+      opts = {};
+    } else {
+      this._delay = opts.delay;
+    }
+    var self = this;
+    this._globals = [];
+    this._abort = false;
+    this.suite = suite;
+    this._opts = opts;
+    this.state = constants.STATE_IDLE;
+    this.total = suite.total();
+    this.failures = 0;
+    /**
+     * @type {Map<EventEmitter,Map<string,Set<EventListener>>>}
+     */
+    this._eventListeners = new Map();
+    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) {
+      self.checkGlobals(hook);
+    });
+    this._defaultGrep = /.*/;
+    this.grep(this._defaultGrep);
+    this.globals(this.globalProps());
+
+    this.uncaught = this._uncaught.bind(this);
+    this.unhandled = (reason, promise) => {
+      if (isMochaError(reason)) {
+        debug(
+          'trapped unhandled rejection coming out of Mocha; forwarding to uncaught handler:',
+          reason
+        );
+        this.uncaught(reason);
+      } else {
+        debug(
+          'trapped unhandled rejection from (probably) user code; re-emitting on process'
+        );
+        this._removeEventListener(
+          process,
+          'unhandledRejection',
+          this.unhandled
+        );
+        try {
+          process.emit('unhandledRejection', reason, promise);
+        } finally {
+          this._addEventListener(process, 'unhandledRejection', this.unhandled);
+        }
+      }
+    };
+  }
 }
 
 /**
@@ -186,11 +216,6 @@ function Runner(suite, opts) {
  */
 Runner.immediately = global.setImmediate || process.nextTick;
 
-/**
- * Inherit from `EventEmitter.prototype`.
- */
-inherits(Runner, EventEmitter);
-
 /**
  * Replacement for `target.on(eventName, listener)` that does bookkeeping to remove them when this runner instance is disposed.
  * @param {EventEmitter} target - The `EventEmitter`
@@ -199,33 +224,62 @@ inherits(Runner, EventEmitter);
  * @private
  */
 Runner.prototype._addEventListener = function(target, eventName, listener) {
+  debug(
+    '_addEventListener(): adding for event %s; %d current listeners',
+    eventName,
+    target.listenerCount(eventName)
+  );
+  /* istanbul ignore next */
+  if (
+    this._eventListeners.has(target) &&
+    this._eventListeners.get(target).has(eventName) &&
+    this._eventListeners
+      .get(target)
+      .get(eventName)
+      .has(listener)
+  ) {
+    debug(
+      'warning: tried to attach duplicate event listener for %s',
+      eventName
+    );
+    return;
+  }
   target.on(eventName, listener);
-  this._eventListeners.push([target, eventName, listener]);
+  const targetListeners = this._eventListeners.has(target)
+    ? this._eventListeners.get(target)
+    : new Map();
+  const targetEventListeners = targetListeners.has(eventName)
+    ? targetListeners.get(eventName)
+    : new Set();
+  targetEventListeners.add(listener);
+  targetListeners.set(eventName, targetEventListeners);
+  this._eventListeners.set(target, targetListeners);
 };
 
 /**
  * Replacement for `target.removeListener(eventName, listener)` that also updates the bookkeeping.
  * @param {EventEmitter} target - The `EventEmitter`
- * @param {string} eventName - The event anme
+ * @param {string} eventName - The event name
  * @param {function} listener - Listener function
  * @private
  */
 Runner.prototype._removeEventListener = function(target, eventName, listener) {
-  var eventListenerIndex = -1;
-  for (var i = 0; i < this._eventListeners.length; i++) {
-    var eventListenerDescriptor = this._eventListeners[i];
-    if (
-      eventListenerDescriptor[0] === target &&
-      eventListenerDescriptor[1] === eventName &&
-      eventListenerDescriptor[2] === listener
-    ) {
-      eventListenerIndex = i;
-      break;
+  target.removeListener(eventName, listener);
+
+  if (this._eventListeners.has(target)) {
+    const targetListeners = this._eventListeners.get(target);
+    if (targetListeners.has(eventName)) {
+      const targetEventListeners = targetListeners.get(eventName);
+      targetEventListeners.delete(listener);
+      if (!targetEventListeners.size) {
+        targetListeners.delete(eventName);
+      }
     }
-  }
-  if (eventListenerIndex !== -1) {
-    var removedListener = this._eventListeners.splice(eventListenerIndex, 1)[0];
-    removedListener[0].removeListener(removedListener[1], removedListener[2]);
+    if (!targetListeners.size) {
+      this._eventListeners.delete(target);
+    }
+  } else {
+    debug('trying to remove listener for untracked object %s', target);
   }
 };
 
@@ -235,12 +289,14 @@ Runner.prototype._removeEventListener = function(target, eventName, listener) {
  */
 Runner.prototype.dispose = function() {
   this.removeAllListeners();
-  this._eventListeners.forEach(function(eventListenerDescriptor) {
-    eventListenerDescriptor[0].removeListener(
-      eventListenerDescriptor[1],
-      eventListenerDescriptor[2]
-    );
+  this._eventListeners.forEach((targetListeners, target) => {
+    targetListeners.forEach((targetEventListeners, eventName) => {
+      targetEventListeners.forEach(listener => {
+        target.removeListener(eventName, listener);
+      });
+    });
   });
+  this._eventListeners.clear();
 };
 
 /**
@@ -384,7 +440,7 @@ Runner.prototype.fail = function(test, err, force) {
     return;
   }
   if (this.state === constants.STATE_STOPPED) {
-    if (err.code === errors.constants.MULTIPLE_DONE) {
+    if (err.code === errorConstants.MULTIPLE_DONE) {
       throw err;
     }
     throw createFatalError(
@@ -976,73 +1032,117 @@ Runner.prototype._uncaught = function(err) {
  * @memberof Runner
  * @param {Function} fn - Callback when finished
  * @param {{files: string[], options: Options}} [opts] - For subclasses
- * @return {Runner} Runner instance.
+ * @returns {Runner} Runner instance.
  */
-Runner.prototype.run = function(fn, opts) {
-  var self = this;
+Runner.prototype.run = function(fn, opts = {}) {
   var rootSuite = this.suite;
+  var options = opts.options || {};
 
+  debug('run(): got options: %O', options);
   fn = fn || function() {};
 
-  function start() {
+  const end = () => {
+    debug('run(): root suite completed; emitting %s', constants.EVENT_RUN_END);
+    this.emit(constants.EVENT_RUN_END);
+  };
+
+  const begin = () => {
+    debug('run(): emitting %s', constants.EVENT_RUN_BEGIN);
+    this.emit(constants.EVENT_RUN_BEGIN);
+    debug('run(): emitted %s', constants.EVENT_RUN_BEGIN);
+
+    this.runSuite(rootSuite, end);
+  };
+
+  const prepare = () => {
     debug('run(): starting');
     // If there is an `only` filter
     if (rootSuite.hasOnly()) {
       rootSuite.filterOnly();
       debug('run(): filtered exclusive Runnables');
     }
-    self.state = constants.STATE_RUNNING;
-    if (self._delay) {
-      self.emit(constants.EVENT_DELAY_END);
+    this.state = constants.STATE_RUNNING;
+    if (this._delay) {
+      this.emit(constants.EVENT_DELAY_END);
       debug('run(): "delay" ended');
     }
-    debug('run(): emitting %s', constants.EVENT_RUN_BEGIN);
-    self.emit(constants.EVENT_RUN_BEGIN);
-    debug('run(): emitted %s', constants.EVENT_RUN_BEGIN);
 
-    self.runSuite(rootSuite, function() {
-      debug(
-        'run(): root suite completed; emitting %s',
-        constants.EVENT_RUN_END
-      );
-      self.emit(constants.EVENT_RUN_END);
-      debug('run(): emitted %s', constants.EVENT_RUN_END);
-    });
-  }
+    return begin();
+  };
 
   // references cleanup to avoid memory leaks
   if (this._opts.cleanReferencesAfterRun) {
-    this.on(constants.EVENT_SUITE_END, function(suite) {
+    this.on(constants.EVENT_SUITE_END, suite => {
       suite.cleanReferences();
     });
   }
 
   // callback
   this.on(constants.EVENT_RUN_END, function() {
-    self.state = constants.STATE_STOPPED;
-    debug(constants.EVENT_RUN_END);
+    this.state = constants.STATE_STOPPED;
     debug('run(): emitted %s', constants.EVENT_RUN_END);
-    fn(self.failures);
+    fn(this.failures);
   });
 
-  self._removeEventListener(process, 'uncaughtException', self.uncaught);
-  self._addEventListener(process, 'uncaughtException', self.uncaught);
+  this._removeEventListener(process, 'uncaughtException', this.uncaught);
+  this._removeEventListener(process, 'unhandledRejection', this.unhandled);
+  this._addEventListener(process, 'uncaughtException', this.uncaught);
+  this._addEventListener(process, 'unhandledRejection', this.unhandled);
 
   if (this._delay) {
     // for reporters, I guess.
     // might be nice to debounce some dots while we wait.
     this.emit(constants.EVENT_DELAY_BEGIN, rootSuite);
-    rootSuite.once(EVENT_ROOT_SUITE_RUN, start);
+    rootSuite.once(EVENT_ROOT_SUITE_RUN, prepare);
     debug('run(): waiting for green light due to --delay');
   } else {
-    Runner.immediately(function() {
-      start();
-    });
+    Runner.immediately(prepare);
   }
 
   return this;
 };
 
+/**
+ * Toggle partial object linking behavior; used for building object references from
+ * unique ID's. Does nothing in serial mode, because the object references already exist.
+ * Subclasses can implement this (e.g., `ParallelBufferedRunner`)
+ * @abstract
+ * @param {boolean} [value] - If `true`, enable partial object linking, otherwise disable
+ * @returns {Runner}
+ * @chainable
+ * @public
+ * @example
+ * // this reporter needs proper object references when run in parallel mode
+ * class MyReporter() {
+ *   constructor(runner) {
+ *     this.runner.linkPartialObjects(true)
+ *       .on(EVENT_SUITE_BEGIN, suite => {
+           // this Suite may be the same object...
+ *       })
+ *       .on(EVENT_TEST_BEGIN, test => {
+ *         // ...as the `test.parent` property
+ *       });
+ *   }
+ * }
+ */
+Runner.prototype.linkPartialObjects = function(value) {
+  return this;
+};
+
+/*
+ * Like {@link Runner#run}, but does not accept a callback and returns a `Promise` instead of a `Runner`.
+ * This function cannot reject; an `unhandledRejection` event will bubble up to the `process` object instead.
+ * @public
+ * @memberof Runner
+ * @param {Object} [opts] - Options for {@link Runner#run}
+ * @returns {Promise<number>} Failure count
+ */
+Runner.prototype.runAsync = async function runAsync(opts = {}) {
+  return new Promise(resolve => {
+    this.run(resolve, opts);
+  });
+};
+
 /**
  * Cleanly abort execution.
  *
@@ -1057,6 +1157,31 @@ Runner.prototype.abort = function() {
   return this;
 };
 
+/**
+ * Returns `true` if Mocha is running in parallel mode.  For reporters.
+ *
+ * Subclasses should return an appropriate value.
+ * @public
+ * @returns {false}
+ */
+Runner.prototype.isParallelMode = function isParallelMode() {
+  return false;
+};
+
+/**
+ * Configures an alternate reporter for worker processes to use. Subclasses
+ * using worker processes should implement this.
+ * @public
+ * @param {string} path - Absolute path to alternate reporter for worker processes to use
+ * @returns {Runner}
+ * @throws When in serial mode
+ * @chainable
+ * @abstract
+ */
+Runner.prototype.workerReporter = function() {
+  throw createUnsupportedError('workerReporter() not supported in serial mode');
+};
+
 /**
  * Filter leaks with the given globals flagged as `ok`.
  *
@@ -1122,7 +1247,9 @@ function isError(err) {
  */
 function thrown2Error(err) {
   return new Error(
-    'the ' + type(err) + ' ' + stringify(err) + ' was thrown, throw an Error :)'
+    `the ${utils.canonicalType(err)} ${stringify(
+      err
+    )} was thrown, throw an Error :)`
   );
 }
 
@@ -1133,3 +1260,5 @@ Runner.constants = constants;
  * @external EventEmitter
  * @see {@link https://nodejs.org/api/events.html#events_class_eventemitter}
  */
+
+module.exports = Runner;

package/lib/suite.js

@@ -4,14 +4,23 @@
  * Module dependencies.
  * @private
  */
-var EventEmitter = require('events').EventEmitter;
-var Hook = require('./hook');
-var utils = require('./utils');
-var inherits = utils.inherits;
-var debug = require('debug')('mocha:suite');
-var milliseconds = require('ms');
-var errors = require('./errors');
-var createInvalidArgumentTypeError = errors.createInvalidArgumentTypeError;
+const {EventEmitter} = require('events');
+const Hook = require('./hook');
+var {
+  assignNewMochaID,
+  clamp,
+  constants: utilsConstants,
+  createMap,
+  defineConstants,
+  getMochaID,
+  inherits,
+  isString
+} = require('./utils');
+const debug = require('debug')('mocha:suite');
+const milliseconds = require('ms');
+const errors = require('./errors');
+
+const {MOCHA_ID_PROP_NAME} = utilsConstants;
 
 /**
  * Expose `Suite`.
@@ -47,8 +56,8 @@ Suite.create = function(parent, title) {
  * @param {boolean} [isRoot=false] - Whether this is the root suite.
  */
 function Suite(title, parentContext, isRoot) {
-  if (!utils.isString(title)) {
-    throw createInvalidArgumentTypeError(
+  if (!isString(title)) {
+    throw errors.createInvalidArgumentTypeError(
       'Suite argument "title" must be a string. Received type "' +
         typeof title +
         '"',
@@ -74,11 +83,19 @@ function Suite(title, parentContext, isRoot) {
   this._bail = false;
   this._onlyTests = [];
   this._onlySuites = [];
+  assignNewMochaID(this);
+
+  Object.defineProperty(this, 'id', {
+    get() {
+      return getMochaID(this);
+    }
+  });
+
   this.reset();
 
   this.on('newListener', function(event) {
     if (deprecatedEvents[event]) {
-      utils.deprecate(
+      errors.deprecate(
         'Event "' +
           event +
           '" is deprecated.  Please let the Mocha team know about your use case: https://git.io/v6Lwm'
@@ -145,7 +162,7 @@ Suite.prototype.timeout = function(ms) {
   // Clamp to range
   var INT_MAX = Math.pow(2, 31) - 1;
   var range = [0, INT_MAX];
-  ms = utils.clamp(ms, range);
+  ms = clamp(ms, range);
 
   debug('timeout %d', ms);
   this._timeout = parseInt(ms, 10);
@@ -579,11 +596,13 @@ Suite.prototype.serialize = function serialize() {
     $$fullTitle: this.fullTitle(),
     $$isPending: this.isPending(),
     root: this.root,
-    title: this.title
+    title: this.title,
+    id: this.id,
+    parent: this.parent ? {[MOCHA_ID_PROP_NAME]: this.parent.id} : null
   };
 };
 
-var constants = utils.defineConstants(
+var constants = defineConstants(
   /**
    * {@link Suite}-related constants.
    * @public
@@ -671,6 +690,6 @@ var deprecatedEvents = Object.keys(constants)
   .reduce(function(acc, constant) {
     acc[constants[constant]] = true;
     return acc;
-  }, utils.createMap());
+  }, createMap());
 
 Suite.constants = constants;

package/lib/test.js

@@ -5,6 +5,8 @@ var errors = require('./errors');
 var createInvalidArgumentTypeError = errors.createInvalidArgumentTypeError;
 var isString = utils.isString;
 
+const {MOCHA_ID_PROP_NAME} = utils.constants;
+
 module.exports = Test;
 
 /**
@@ -98,12 +100,14 @@ Test.prototype.serialize = function serialize() {
     duration: this.duration,
     err: this.err,
     parent: {
-      $$fullTitle: this.parent.fullTitle()
+      $$fullTitle: this.parent.fullTitle(),
+      [MOCHA_ID_PROP_NAME]: this.parent.id
     },
     speed: this.speed,
     state: this.state,
     title: this.title,
     type: this.type,
-    file: this.file
+    file: this.file,
+    [MOCHA_ID_PROP_NAME]: this.id
   };
 };