mocha 6.0.0-1 → 6.0.0

package/lib/stats-collector.js

@@ -2,14 +2,22 @@
 
 /**
  * Provides a factory function for a {@link StatsCollector} object.
- * @private
  * @module
  */
 
+var constants = require('./runner').constants;
+var EVENT_TEST_PASS = constants.EVENT_TEST_PASS;
+var EVENT_TEST_FAIL = constants.EVENT_TEST_FAIL;
+var EVENT_SUITE_BEGIN = constants.EVENT_SUITE_BEGIN;
+var EVENT_RUN_BEGIN = constants.EVENT_RUN_BEGIN;
+var EVENT_TEST_PENDING = constants.EVENT_TEST_PENDING;
+var EVENT_RUN_END = constants.EVENT_RUN_END;
+var EVENT_TEST_END = constants.EVENT_TEST_END;
+
 /**
  * Test statistics collector.
  *
- * @private
+ * @public
  * @typedef {Object} StatsCollector
  * @property {number} suites - integer count of suites run.
  * @property {number} tests - integer count of tests run.
@@ -48,31 +56,25 @@ function createStatsCollector(runner) {
 
   runner.stats = stats;
 
-  runner.once('start', function() {
+  runner.once(EVENT_RUN_BEGIN, function() {
     stats.start = new Date();
   });
-
-  runner.on('suite', function(suite) {
+  runner.on(EVENT_SUITE_BEGIN, function(suite) {
     suite.root || stats.suites++;
   });
-
-  runner.on('pass', function() {
+  runner.on(EVENT_TEST_PASS, function() {
     stats.passes++;
   });
-
-  runner.on('fail', function() {
+  runner.on(EVENT_TEST_FAIL, function() {
     stats.failures++;
   });
-
-  runner.on('pending', function() {
+  runner.on(EVENT_TEST_PENDING, function() {
     stats.pending++;
   });
-
-  runner.on('test end', function() {
+  runner.on(EVENT_TEST_END, function() {
     stats.tests++;
   });
-
-  runner.once('end', function() {
+  runner.once(EVENT_RUN_END, function() {
     stats.end = new Date();
     stats.duration = stats.end - stats.start;
   });

package/lib/suite.js

@@ -1,7 +1,4 @@
 'use strict';
-/**
- * @module Suite
- */
 
 /**
  * Module dependencies.
@@ -22,17 +19,14 @@ var createInvalidArgumentTypeError = errors.createInvalidArgumentTypeError;
 exports = module.exports = Suite;
 
 /**
- * Create a new `Suite` with the given `title` and parent `Suite`. When a suite
- * with the same title is already present, that suite is returned to provide
- * nicer reporter and more flexible meta-testing.
+ * Create a new `Suite` with the given `title` and parent `Suite`.
  *
- * @memberof Mocha
  * @public
- * @param {Suite} parent
- * @param {string} title
+ * @param {Suite} parent - Parent suite (required!)
+ * @param {string} title - Title
  * @return {Suite}
  */
-exports.create = function(parent, title) {
+Suite.create = function(parent, title) {
   var suite = new Suite(title, parent.ctx);
   suite.parent = parent;
   title = suite.fullTitle();
@@ -41,15 +35,17 @@ exports.create = function(parent, title) {
 };
 
 /**
- * Initialize a new `Suite` with the given `title` and `ctx`. Derived from [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
+ * Constructs a new `Suite` instance with the given `title`, `ctx`, and `isRoot`.
  *
- * @memberof Mocha
  * @public
  * @class
- * @param {string} title
- * @param {Context} parentContext
+ * @extends EventEmitter
+ * @see {@link https://nodejs.org/api/events.html#events_class_eventemitter|EventEmitter}
+ * @param {string} title - Suite title.
+ * @param {Context} parentContext - Parent context instance.
+ * @param {boolean} [isRoot=false] - Whether this is the root suite.
  */
-function Suite(title, parentContext) {
+function Suite(title, parentContext, isRoot) {
   if (!utils.isString(title)) {
     throw createInvalidArgumentTypeError(
       'Suite argument "title" must be a string. Received type "' +
@@ -70,7 +66,7 @@ function Suite(title, parentContext) {
   this._beforeAll = [];
   this._afterEach = [];
   this._afterAll = [];
-  this.root = !title;
+  this.root = isRoot === true;
   this._timeout = 2000;
   this._enableTimeouts = true;
   this._slow = 75;
@@ -79,6 +75,16 @@ function Suite(title, parentContext) {
   this._onlyTests = [];
   this._onlySuites = [];
   this.delayed = false;
+
+  this.on('newListener', function(event) {
+    if (deprecatedEvents[event]) {
+      utils.deprecate(
+        'Event "' +
+          event +
+          '" is deprecated.  Please let the Mocha team know about your use case: https://git.io/v6Lwm'
+      );
+    }
+  });
 }
 
 /**
@@ -241,7 +247,7 @@ Suite.prototype.beforeAll = function(title, fn) {
 
   var hook = this._createHook(title, fn);
   this._beforeAll.push(hook);
-  this.emit('beforeAll', hook);
+  this.emit(constants.EVENT_SUITE_ADD_HOOK_BEFORE_ALL, hook);
   return this;
 };
 
@@ -265,7 +271,7 @@ Suite.prototype.afterAll = function(title, fn) {
 
   var hook = this._createHook(title, fn);
   this._afterAll.push(hook);
-  this.emit('afterAll', hook);
+  this.emit(constants.EVENT_SUITE_ADD_HOOK_AFTER_ALL, hook);
   return this;
 };
 
@@ -289,7 +295,7 @@ Suite.prototype.beforeEach = function(title, fn) {
 
   var hook = this._createHook(title, fn);
   this._beforeEach.push(hook);
-  this.emit('beforeEach', hook);
+  this.emit(constants.EVENT_SUITE_ADD_HOOK_BEFORE_EACH, hook);
   return this;
 };
 
@@ -313,7 +319,7 @@ Suite.prototype.afterEach = function(title, fn) {
 
   var hook = this._createHook(title, fn);
   this._afterEach.push(hook);
-  this.emit('afterEach', hook);
+  this.emit(constants.EVENT_SUITE_ADD_HOOK_AFTER_EACH, hook);
   return this;
 };
 
@@ -326,13 +332,14 @@ Suite.prototype.afterEach = function(title, fn) {
  */
 Suite.prototype.addSuite = function(suite) {
   suite.parent = this;
+  suite.root = false;
   suite.timeout(this.timeout());
   suite.retries(this.retries());
   suite.enableTimeouts(this.enableTimeouts());
   suite.slow(this.slow());
   suite.bail(this.bail());
   this.suites.push(suite);
-  this.emit('suite', suite);
+  this.emit(constants.EVENT_SUITE_ADD_SUITE, suite);
   return this;
 };
 
@@ -351,7 +358,7 @@ Suite.prototype.addTest = function(test) {
   test.slow(this.slow());
   test.ctx = this.ctx;
   this.tests.push(test);
-  this.emit('test', test);
+  this.emit(constants.EVENT_SUITE_ADD_TEST, test);
   return this;
 };
 
@@ -359,7 +366,7 @@ Suite.prototype.addTest = function(test) {
  * Return the full title generated by recursively concatenating the parent's
  * full title.
  *
- * @memberof Mocha.Suite
+ * @memberof Suite
  * @public
  * @return {string}
  */
@@ -371,7 +378,7 @@ Suite.prototype.fullTitle = function() {
  * Return the title path generated by recursively concatenating the parent's
  * title path.
  *
- * @memberof Mocha.Suite
+ * @memberof Suite
  * @public
  * @return {string}
  */
@@ -389,7 +396,7 @@ Suite.prototype.titlePath = function() {
 /**
  * Return the total number of tests.
  *
- * @memberof Mocha.Suite
+ * @memberof Suite
  * @public
  * @return {number}
  */
@@ -419,9 +426,215 @@ Suite.prototype.eachTest = function(fn) {
 
 /**
  * This will run the root suite if we happen to be running in delayed mode.
+ * @private
  */
 Suite.prototype.run = function run() {
   if (this.root) {
-    this.emit('run');
+    this.emit(constants.EVENT_ROOT_SUITE_RUN);
+  }
+};
+
+/**
+ * Determines whether a suite has an `only` test or suite as a descendant.
+ *
+ * @private
+ * @returns {Boolean}
+ */
+Suite.prototype.hasOnly = function hasOnly() {
+  return (
+    this._onlyTests.length > 0 ||
+    this._onlySuites.length > 0 ||
+    this.suites.some(function(suite) {
+      return suite.hasOnly();
+    })
+  );
+};
+
+/**
+ * Filter suites based on `isOnly` logic.
+ *
+ * @private
+ * @returns {Boolean}
+ */
+Suite.prototype.filterOnly = function filterOnly() {
+  if (this._onlyTests.length) {
+    // If the suite contains `only` tests, run those and ignore any nested suites.
+    this.tests = this._onlyTests;
+    this.suites = [];
+  } else {
+    // Otherwise, do not run any of the tests in this suite.
+    this.tests = [];
+    this._onlySuites.forEach(function(onlySuite) {
+      // If there are other `only` tests/suites nested in the current `only` suite, then filter that `only` suite.
+      // Otherwise, all of the tests on this `only` suite should be run, so don't filter it.
+      if (onlySuite.hasOnly()) {
+        onlySuite.filterOnly();
+      }
+    });
+    // Run the `only` suites, as well as any other suites that have `only` tests/suites as descendants.
+    var onlySuites = this._onlySuites;
+    this.suites = this.suites.filter(function(childSuite) {
+      return onlySuites.indexOf(childSuite) !== -1 || childSuite.filterOnly();
+    });
   }
+  // Keep the suite only if there is something to run
+  return this.tests.length > 0 || this.suites.length > 0;
 };
+
+/**
+ * Adds a suite to the list of subsuites marked `only`.
+ *
+ * @private
+ * @param {Suite} suite
+ */
+Suite.prototype.appendOnlySuite = function(suite) {
+  this._onlySuites.push(suite);
+};
+
+/**
+ * Adds a test to the list of tests marked `only`.
+ *
+ * @private
+ * @param {Test} test
+ */
+Suite.prototype.appendOnlyTest = function(test) {
+  this._onlyTests.push(test);
+};
+
+/**
+ * Returns the array of hooks by hook name; see `HOOK_TYPE_*` constants.
+ * @private
+ */
+Suite.prototype.getHooks = function getHooks(name) {
+  return this['_' + name];
+};
+
+/**
+ * Cleans up the references to all the deferred functions
+ * (before/after/beforeEach/afterEach) and tests of a Suite.
+ * These must be deleted otherwise a memory leak can happen,
+ * as those functions may reference variables from closures,
+ * thus those variables can never be garbage collected as long
+ * as the deferred functions exist.
+ *
+ * @private
+ */
+Suite.prototype.cleanReferences = function cleanReferences() {
+  function cleanArrReferences(arr) {
+    for (var i = 0; i < arr.length; i++) {
+      delete arr[i].fn;
+    }
+  }
+
+  if (Array.isArray(this._beforeAll)) {
+    cleanArrReferences(this._beforeAll);
+  }
+
+  if (Array.isArray(this._beforeEach)) {
+    cleanArrReferences(this._beforeEach);
+  }
+
+  if (Array.isArray(this._afterAll)) {
+    cleanArrReferences(this._afterAll);
+  }
+
+  if (Array.isArray(this._afterEach)) {
+    cleanArrReferences(this._afterEach);
+  }
+
+  for (var i = 0; i < this.tests.length; i++) {
+    delete this.tests[i].fn;
+  }
+};
+
+var constants = utils.defineConstants(
+  /**
+   * {@link Suite}-related constants.
+   * @public
+   * @memberof Suite
+   * @alias constants
+   * @readonly
+   * @static
+   * @enum {string}
+   */
+  {
+    /**
+     * Event emitted after a test file has been loaded Not emitted in browser.
+     */
+    EVENT_FILE_POST_REQUIRE: 'post-require',
+    /**
+     * Event emitted before a test file has been loaded. In browser, this is emitted once an interface has been selected.
+     */
+    EVENT_FILE_PRE_REQUIRE: 'pre-require',
+    /**
+     * Event emitted immediately after a test file has been loaded. Not emitted in browser.
+     */
+    EVENT_FILE_REQUIRE: 'require',
+    /**
+     * Event emitted when `global.run()` is called (use with `delay` option)
+     */
+    EVENT_ROOT_SUITE_RUN: 'run',
+
+    /**
+     * Namespace for collection of a `Suite`'s "after all" hooks
+     */
+    HOOK_TYPE_AFTER_ALL: 'afterAll',
+    /**
+     * Namespace for collection of a `Suite`'s "after each" hooks
+     */
+    HOOK_TYPE_AFTER_EACH: 'afterEach',
+    /**
+     * Namespace for collection of a `Suite`'s "before all" hooks
+     */
+    HOOK_TYPE_BEFORE_ALL: 'beforeAll',
+    /**
+     * Namespace for collection of a `Suite`'s "before all" hooks
+     */
+    HOOK_TYPE_BEFORE_EACH: 'beforeEach',
+
+    // the following events are all deprecated
+
+    /**
+     * Emitted after an "after all" `Hook` has been added to a `Suite`. Deprecated
+     */
+    EVENT_SUITE_ADD_HOOK_AFTER_ALL: 'afterAll',
+    /**
+     * Emitted after an "after each" `Hook` has been added to a `Suite` Deprecated
+     */
+    EVENT_SUITE_ADD_HOOK_AFTER_EACH: 'afterEach',
+    /**
+     * Emitted after an "before all" `Hook` has been added to a `Suite` Deprecated
+     */
+    EVENT_SUITE_ADD_HOOK_BEFORE_ALL: 'beforeAll',
+    /**
+     * Emitted after an "before each" `Hook` has been added to a `Suite` Deprecated
+     */
+    EVENT_SUITE_ADD_HOOK_BEFORE_EACH: 'beforeEach',
+    /**
+     * Emitted after a child `Suite` has been added to a `Suite`. Deprecated
+     */
+    EVENT_SUITE_ADD_SUITE: 'suite',
+    /**
+     * Emitted after a `Test` has been added to a `Suite`. Deprecated
+     */
+    EVENT_SUITE_ADD_TEST: 'test'
+  }
+);
+
+/**
+ * @summary There are no known use cases for these events.
+ * @desc This is a `Set`-like object having all keys being the constant's string value and the value being `true`.
+ * @todo Remove eventually
+ * @type {Object<string,boolean>}
+ * @ignore
+ */
+var deprecatedEvents = Object.keys(constants)
+  .filter(function(constant) {
+    return constant.substring(0, 15) === 'EVENT_SUITE_ADD';
+  })
+  .reduce(function(acc, constant) {
+    acc[constants[constant]] = true;
+    return acc;
+  }, utils.createMap());
+
+Suite.constants = constants;

package/lib/test.js

@@ -10,10 +10,11 @@ module.exports = Test;
 /**
  * Initialize a new `Test` with the given `title` and callback `fn`.
  *
+ * @public
  * @class
  * @extends Runnable
- * @param {String} title
- * @param {Function} fn
+ * @param {String} title - Test title (required)
+ * @param {Function} [fn] - Test callback.  If omitted, the Test is considered "pending"
  */
 function Test(title, fn) {
   if (!isString(title)) {