mocha 5.1.0 → 6.0.0-1

package/lib/stats-collector.js

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+ * Provides a factory function for a {@link StatsCollector} object.
+ * @private
+ * @module
+ */
+
+/**
+ * Test statistics collector.
+ *
+ * @private
+ * @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('start', function() {
+    stats.start = new Date();
+  });
+
+  runner.on('suite', function(suite) {
+    suite.root || stats.suites++;
+  });
+
+  runner.on('pass', function() {
+    stats.passes++;
+  });
+
+  runner.on('fail', function() {
+    stats.failures++;
+  });
+
+  runner.on('pending', function() {
+    stats.pending++;
+  });
+
+  runner.on('test end', function() {
+    stats.tests++;
+  });
+
+  runner.once('end', function() {
+    stats.end = new Date();
+    stats.duration = stats.end - stats.start;
+  });
+}
+
+module.exports = createStatsCollector;

package/lib/suite.js

@@ -11,7 +11,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`.
@@ -26,12 +28,11 @@ exports = module.exports = Suite;
  *
  * @memberof Mocha
  * @public
- * @api public
  * @param {Suite} parent
  * @param {string} title
  * @return {Suite}
  */
-exports.create = function (parent, title) {
+exports.create = function(parent, title) {
   var suite = new Suite(title, parent.ctx);
   suite.parent = parent;
   title = suite.fullTitle();
@@ -48,12 +49,18 @@ exports.create = function (parent, title) {
  * @param {string} title
  * @param {Context} parentContext
  */
-function Suite (title, parentContext) {
+function Suite(title, parentContext) {
   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 = [];
@@ -82,10 +89,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 +107,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 +129,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 +143,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 +161,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 +180,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 +196,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 +209,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 +224,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;
   }
@@ -241,12 +248,12 @@ Suite.prototype.beforeAll = function (title, fn) {
 /**
  * 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;
   }
@@ -265,12 +272,12 @@ Suite.prototype.afterAll = function (title, fn) {
 /**
  * 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;
   }
@@ -289,12 +296,12 @@ Suite.prototype.beforeEach = function (title, fn) {
 /**
  * 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;
   }
@@ -313,11 +320,11 @@ Suite.prototype.afterEach = function (title, fn) {
 /**
  * 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.timeout(this.timeout());
   suite.retries(this.retries());
@@ -332,11 +339,11 @@ Suite.prototype.addSuite = function (suite) {
 /**
  * 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());
@@ -354,10 +361,9 @@ Suite.prototype.addTest = function (test) {
  *
  * @memberof Mocha.Suite
  * @public
- * @api public
  * @return {string}
  */
-Suite.prototype.fullTitle = function () {
+Suite.prototype.fullTitle = function() {
   return this.titlePath().join(' ');
 };
 
@@ -367,10 +373,9 @@ Suite.prototype.fullTitle = function () {
  *
  * @memberof Mocha.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());
@@ -386,26 +391,27 @@ Suite.prototype.titlePath = function () {
  *
  * @memberof Mocha.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;
@@ -414,7 +420,7 @@ Suite.prototype.eachTest = function (fn) {
 /**
  * This will run the root suite if we happen to be running in delayed mode.
  */
-Suite.prototype.run = function run () {
+Suite.prototype.run = function run() {
   if (this.root) {
     this.emit('run');
   }

package/lib/test.js

@@ -1,29 +1,29 @@
 'use strict';
-
-/**
- * Module dependencies.
- */
-
 var Runnable = require('./runnable');
 var utils = require('./utils');
+var errors = require('./errors');
+var createInvalidArgumentTypeError = errors.createInvalidArgumentTypeError;
 var isString = utils.isString;
 
-/**
- * Expose `Test`.
- */
-
 module.exports = Test;
 
 /**
  * Initialize a new `Test` with the given `title` and callback `fn`.
  *
- * @api private
+ * @class
+ * @extends Runnable
  * @param {String} title
  * @param {Function} fn
  */
-function Test (title, fn) {
+function Test(title, fn) {
   if (!isString(title)) {
-    throw new Error('Test `title` should be a "string" but "' + typeof title + '" was given instead.');
+    throw createInvalidArgumentTypeError(
+      'Test argument "title" should be a string. Received type "' +
+        typeof title +
+        '"',
+      'title',
+      'string'
+    );
   }
   Runnable.call(this, title, fn);
   this.pending = !fn;
@@ -35,7 +35,7 @@ function Test (title, fn) {
  */
 utils.inherits(Test, Runnable);
 
-Test.prototype.clone = function () {
+Test.prototype.clone = function() {
   var test = new Test(this.title, this.fn);
   test.timeout(this.timeout());
   test.slow(this.slow());