mocha 5.1.1 → 6.0.0

package/lib/stats-collector.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * Provides a factory function for a {@link StatsCollector} object.
+ * @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.
+ *
+ * @public
+ * @typedef {Object} StatsCollector
+ * @property {number} suites - integer count of suites run.
+ * @property {number} tests - integer count of tests run.
+ * @property {number} passes - integer count of passing tests.
+ * @property {number} pending - integer count of pending tests.
+ * @property {number} failures - integer count of failed tests.
+ * @property {Date} start - time when testing began.
+ * @property {Date} end - time when testing concluded.
+ * @property {number} duration - number of msecs that testing took.
+ */
+
+var Date = global.Date;
+
+/**
+ * Provides stats such as test duration, number of tests passed / failed etc., by listening for events emitted by `runner`.
+ *
+ * @private
+ * @param {Runner} runner - Runner instance
+ * @throws {TypeError} If falsy `runner`
+ */
+function createStatsCollector(runner) {
+  /**
+   * @type StatsCollector
+   */
+  var stats = {
+    suites: 0,
+    tests: 0,
+    passes: 0,
+    pending: 0,
+    failures: 0
+  };
+
+  if (!runner) {
+    throw new TypeError('Missing runner argument');
+  }
+
+  runner.stats = stats;
+
+  runner.once(EVENT_RUN_BEGIN, function() {
+    stats.start = new Date();
+  });
+  runner.on(EVENT_SUITE_BEGIN, function(suite) {
+    suite.root || stats.suites++;
+  });
+  runner.on(EVENT_TEST_PASS, function() {
+    stats.passes++;
+  });
+  runner.on(EVENT_TEST_FAIL, function() {
+    stats.failures++;
+  });
+  runner.on(EVENT_TEST_PENDING, function() {
+    stats.pending++;
+  });
+  runner.on(EVENT_TEST_END, function() {
+    stats.tests++;
+  });
+  runner.once(EVENT_RUN_END, function() {
+    stats.end = new Date();
+    stats.duration = stats.end - stats.start;
+  });
+}
+
+module.exports = createStatsCollector;

package/lib/suite.js

@@ -1,7 +1,4 @@
 'use strict';
-/**
- * @module Suite
- */
 
 /**
  * Module dependencies.
@@ -11,7 +8,9 @@ var Hook = require('./hook');
 var utils = require('./utils');
 var inherits = utils.inherits;
 var debug = require('debug')('mocha:suite');
-var milliseconds = require('./ms');
+var milliseconds = require('ms');
+var errors = require('./errors');
+var createInvalidArgumentTypeError = errors.createInvalidArgumentTypeError;
 
 /**
  * Expose `Suite`.
@@ -20,18 +19,14 @@ var milliseconds = require('./ms');
 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
- * @api 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();
@@ -40,20 +35,28 @@ 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 new Error('Suite `title` should be a "string" but "' + typeof title + '" was given instead.');
+    throw createInvalidArgumentTypeError(
+      'Suite argument "title" must be a string. Received type "' +
+        typeof title +
+        '"',
+      'title',
+      'string'
+    );
   }
   this.title = title;
-  function Context () {}
+  function Context() {}
   Context.prototype = parentContext;
   this.ctx = new Context();
   this.suites = [];
@@ -63,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;
@@ -72,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'
+      );
+    }
+  });
 }
 
 /**
@@ -82,10 +95,10 @@ inherits(Suite, EventEmitter);
 /**
  * Return a clone of this `Suite`.
  *
- * @api private
+ * @private
  * @return {Suite}
  */
-Suite.prototype.clone = function () {
+Suite.prototype.clone = function() {
   var suite = new Suite(this.title);
   debug('clone');
   suite.ctx = this.ctx;
@@ -100,11 +113,11 @@ Suite.prototype.clone = function () {
 /**
  * Set or get timeout `ms` or short-hand such as "2s".
  *
- * @api private
+ * @private
  * @param {number|string} ms
  * @return {Suite|number} for chaining
  */
-Suite.prototype.timeout = function (ms) {
+Suite.prototype.timeout = function(ms) {
   if (!arguments.length) {
     return this._timeout;
   }
@@ -122,11 +135,11 @@ Suite.prototype.timeout = function (ms) {
 /**
  * Set or get number of times to retry a failed test.
  *
- * @api private
+ * @private
  * @param {number|string} n
  * @return {Suite|number} for chaining
  */
-Suite.prototype.retries = function (n) {
+Suite.prototype.retries = function(n) {
   if (!arguments.length) {
     return this._retries;
   }
@@ -136,13 +149,13 @@ Suite.prototype.retries = function (n) {
 };
 
 /**
-  * Set or get timeout to `enabled`.
-  *
-  * @api private
-  * @param {boolean} enabled
-  * @return {Suite|boolean} self or enabled
-  */
-Suite.prototype.enableTimeouts = function (enabled) {
+ * Set or get timeout to `enabled`.
+ *
+ * @private
+ * @param {boolean} enabled
+ * @return {Suite|boolean} self or enabled
+ */
+Suite.prototype.enableTimeouts = function(enabled) {
   if (!arguments.length) {
     return this._enableTimeouts;
   }
@@ -154,11 +167,11 @@ Suite.prototype.enableTimeouts = function (enabled) {
 /**
  * Set or get slow `ms` or short-hand such as "2s".
  *
- * @api private
+ * @private
  * @param {number|string} ms
  * @return {Suite|number} for chaining
  */
-Suite.prototype.slow = function (ms) {
+Suite.prototype.slow = function(ms) {
   if (!arguments.length) {
     return this._slow;
   }
@@ -173,11 +186,11 @@ Suite.prototype.slow = function (ms) {
 /**
  * Set or get whether to bail after first error.
  *
- * @api private
+ * @private
  * @param {boolean} bail
  * @return {Suite|number} for chaining
  */
-Suite.prototype.bail = function (bail) {
+Suite.prototype.bail = function(bail) {
   if (!arguments.length) {
     return this._bail;
   }
@@ -189,9 +202,9 @@ Suite.prototype.bail = function (bail) {
 /**
  * Check if this suite or its parent suite is marked as pending.
  *
- * @api private
+ * @private
  */
-Suite.prototype.isPending = function () {
+Suite.prototype.isPending = function() {
   return this.pending || (this.parent && this.parent.isPending());
 };
 
@@ -202,7 +215,7 @@ Suite.prototype.isPending = function () {
  * @param {Function} fn - Hook callback
  * @returns {Hook} A new hook
  */
-Suite.prototype._createHook = function (title, fn) {
+Suite.prototype._createHook = function(title, fn) {
   var hook = new Hook(title, fn);
   hook.parent = this;
   hook.timeout(this.timeout());
@@ -217,12 +230,12 @@ Suite.prototype._createHook = function (title, fn) {
 /**
  * Run `fn(test[, done])` before running tests.
  *
- * @api private
+ * @private
  * @param {string} title
  * @param {Function} fn
  * @return {Suite} for chaining
  */
-Suite.prototype.beforeAll = function (title, fn) {
+Suite.prototype.beforeAll = function(title, fn) {
   if (this.isPending()) {
     return this;
   }
@@ -234,19 +247,19 @@ 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;
 };
 
 /**
  * Run `fn(test[, done])` after running tests.
  *
- * @api private
+ * @private
  * @param {string} title
  * @param {Function} fn
  * @return {Suite} for chaining
  */
-Suite.prototype.afterAll = function (title, fn) {
+Suite.prototype.afterAll = function(title, fn) {
   if (this.isPending()) {
     return this;
   }
@@ -258,19 +271,19 @@ 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;
 };
 
 /**
  * Run `fn(test[, done])` before each test case.
  *
- * @api private
+ * @private
  * @param {string} title
  * @param {Function} fn
  * @return {Suite} for chaining
  */
-Suite.prototype.beforeEach = function (title, fn) {
+Suite.prototype.beforeEach = function(title, fn) {
   if (this.isPending()) {
     return this;
   }
@@ -282,19 +295,19 @@ 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;
 };
 
 /**
  * Run `fn(test[, done])` after each test case.
  *
- * @api private
+ * @private
  * @param {string} title
  * @param {Function} fn
  * @return {Suite} for chaining
  */
-Suite.prototype.afterEach = function (title, fn) {
+Suite.prototype.afterEach = function(title, fn) {
   if (this.isPending()) {
     return this;
   }
@@ -306,37 +319,38 @@ 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;
 };
 
 /**
  * Add a test `suite`.
  *
- * @api private
+ * @private
  * @param {Suite} suite
  * @return {Suite} for chaining
  */
-Suite.prototype.addSuite = function (suite) {
+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;
 };
 
 /**
  * Add a `test` to this suite.
  *
- * @api private
+ * @private
  * @param {Test} test
  * @return {Suite} for chaining
  */
-Suite.prototype.addTest = function (test) {
+Suite.prototype.addTest = function(test) {
   test.parent = this;
   test.timeout(this.timeout());
   test.retries(this.retries());
@@ -344,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;
 };
 
@@ -352,12 +366,11 @@ Suite.prototype.addTest = function (test) {
  * Return the full title generated by recursively concatenating the parent's
  * full title.
  *
- * @memberof Mocha.Suite
+ * @memberof Suite
  * @public
- * @api public
  * @return {string}
  */
-Suite.prototype.fullTitle = function () {
+Suite.prototype.fullTitle = function() {
   return this.titlePath().join(' ');
 };
 
@@ -365,12 +378,11 @@ Suite.prototype.fullTitle = function () {
  * Return the title path generated by recursively concatenating the parent's
  * title path.
  *
- * @memberof Mocha.Suite
+ * @memberof Suite
  * @public
- * @api public
  * @return {string}
  */
-Suite.prototype.titlePath = function () {
+Suite.prototype.titlePath = function() {
   var result = [];
   if (this.parent) {
     result = result.concat(this.parent.titlePath());
@@ -384,28 +396,29 @@ Suite.prototype.titlePath = function () {
 /**
  * Return the total number of tests.
  *
- * @memberof Mocha.Suite
+ * @memberof Suite
  * @public
- * @api public
  * @return {number}
  */
-Suite.prototype.total = function () {
-  return this.suites.reduce(function (sum, suite) {
-    return sum + suite.total();
-  }, 0) + this.tests.length;
+Suite.prototype.total = function() {
+  return (
+    this.suites.reduce(function(sum, suite) {
+      return sum + suite.total();
+    }, 0) + this.tests.length
+  );
 };
 
 /**
  * Iterates through each suite recursively to find all tests. Applies a
  * function in the format `fn(test)`.
  *
- * @api private
+ * @private
  * @param {Function} fn
  * @return {Suite}
  */
-Suite.prototype.eachTest = function (fn) {
+Suite.prototype.eachTest = function(fn) {
   this.tests.forEach(fn);
-  this.suites.forEach(function (suite) {
+  this.suites.forEach(function(suite) {
     suite.eachTest(fn);
   });
   return this;
@@ -413,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 () {
+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;