mocha 5.0.4 → 5.2.0

package/lib/suite.js

@@ -1,9 +1,11 @@
 'use strict';
+/**
+ * @module Suite
+ */
 
 /**
  * Module dependencies.
  */
-
 var EventEmitter = require('events').EventEmitter;
 var Hook = require('./hook');
 var utils = require('./utils');
@@ -22,12 +24,14 @@ exports = module.exports = Suite;
  * with the same title is already present, that suite is returned to provide
  * nicer reporter and more flexible meta-testing.
  *
+ * @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();
@@ -36,18 +40,24 @@ exports.create = function (parent, title) {
 };
 
 /**
- * Initialize a new `Suite` with the given `title` and `ctx`.
+ * Initialize a new `Suite` with the given `title` and `ctx`. Derived from [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
  *
- * @api private
+ * @memberof Mocha
+ * @public
+ * @class
  * @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 new Error(
+      'Suite `title` should be a "string" but "' +
+        typeof title +
+        '" was given instead.'
+    );
   }
   this.title = title;
-  function Context () {}
+  function Context() {}
   Context.prototype = parentContext;
   this.ctx = new Context();
   this.suites = [];
@@ -79,7 +89,7 @@ inherits(Suite, EventEmitter);
  * @api private
  * @return {Suite}
  */
-Suite.prototype.clone = function () {
+Suite.prototype.clone = function() {
   var suite = new Suite(this.title);
   debug('clone');
   suite.ctx = this.ctx;
@@ -98,7 +108,7 @@ Suite.prototype.clone = function () {
  * @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;
   }
@@ -120,7 +130,7 @@ Suite.prototype.timeout = function (ms) {
  * @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;
   }
@@ -130,13 +140,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`.
+ *
+ * @api private
+ * @param {boolean} enabled
+ * @return {Suite|boolean} self or enabled
+ */
+Suite.prototype.enableTimeouts = function(enabled) {
   if (!arguments.length) {
     return this._enableTimeouts;
   }
@@ -152,7 +162,7 @@ Suite.prototype.enableTimeouts = function (enabled) {
  * @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;
   }
@@ -171,7 +181,7 @@ Suite.prototype.slow = function (ms) {
  * @param {boolean} bail
  * @return {Suite|number} for chaining
  */
-Suite.prototype.bail = function (bail) {
+Suite.prototype.bail = function(bail) {
   if (!arguments.length) {
     return this._bail;
   }
@@ -185,10 +195,29 @@ Suite.prototype.bail = function (bail) {
  *
  * @api private
  */
-Suite.prototype.isPending = function () {
+Suite.prototype.isPending = function() {
   return this.pending || (this.parent && this.parent.isPending());
 };
 
+/**
+ * Generic hook-creator.
+ * @private
+ * @param {string} title - Title of hook
+ * @param {Function} fn - Hook callback
+ * @returns {Hook} A new hook
+ */
+Suite.prototype._createHook = function(title, fn) {
+  var hook = new Hook(title, fn);
+  hook.parent = this;
+  hook.timeout(this.timeout());
+  hook.retries(this.retries());
+  hook.enableTimeouts(this.enableTimeouts());
+  hook.slow(this.slow());
+  hook.ctx = this.ctx;
+  hook.file = this.file;
+  return hook;
+};
+
 /**
  * Run `fn(test[, done])` before running tests.
  *
@@ -197,7 +226,7 @@ Suite.prototype.isPending = function () {
  * @param {Function} fn
  * @return {Suite} for chaining
  */
-Suite.prototype.beforeAll = function (title, fn) {
+Suite.prototype.beforeAll = function(title, fn) {
   if (this.isPending()) {
     return this;
   }
@@ -207,13 +236,7 @@ Suite.prototype.beforeAll = function (title, fn) {
   }
   title = '"before all" hook' + (title ? ': ' + title : '');
 
-  var hook = new Hook(title, fn);
-  hook.parent = this;
-  hook.timeout(this.timeout());
-  hook.retries(this.retries());
-  hook.enableTimeouts(this.enableTimeouts());
-  hook.slow(this.slow());
-  hook.ctx = this.ctx;
+  var hook = this._createHook(title, fn);
   this._beforeAll.push(hook);
   this.emit('beforeAll', hook);
   return this;
@@ -227,7 +250,7 @@ Suite.prototype.beforeAll = function (title, fn) {
  * @param {Function} fn
  * @return {Suite} for chaining
  */
-Suite.prototype.afterAll = function (title, fn) {
+Suite.prototype.afterAll = function(title, fn) {
   if (this.isPending()) {
     return this;
   }
@@ -237,13 +260,7 @@ Suite.prototype.afterAll = function (title, fn) {
   }
   title = '"after all" hook' + (title ? ': ' + title : '');
 
-  var hook = new Hook(title, fn);
-  hook.parent = this;
-  hook.timeout(this.timeout());
-  hook.retries(this.retries());
-  hook.enableTimeouts(this.enableTimeouts());
-  hook.slow(this.slow());
-  hook.ctx = this.ctx;
+  var hook = this._createHook(title, fn);
   this._afterAll.push(hook);
   this.emit('afterAll', hook);
   return this;
@@ -257,7 +274,7 @@ Suite.prototype.afterAll = function (title, fn) {
  * @param {Function} fn
  * @return {Suite} for chaining
  */
-Suite.prototype.beforeEach = function (title, fn) {
+Suite.prototype.beforeEach = function(title, fn) {
   if (this.isPending()) {
     return this;
   }
@@ -267,13 +284,7 @@ Suite.prototype.beforeEach = function (title, fn) {
   }
   title = '"before each" hook' + (title ? ': ' + title : '');
 
-  var hook = new Hook(title, fn);
-  hook.parent = this;
-  hook.timeout(this.timeout());
-  hook.retries(this.retries());
-  hook.enableTimeouts(this.enableTimeouts());
-  hook.slow(this.slow());
-  hook.ctx = this.ctx;
+  var hook = this._createHook(title, fn);
   this._beforeEach.push(hook);
   this.emit('beforeEach', hook);
   return this;
@@ -287,7 +298,7 @@ Suite.prototype.beforeEach = function (title, fn) {
  * @param {Function} fn
  * @return {Suite} for chaining
  */
-Suite.prototype.afterEach = function (title, fn) {
+Suite.prototype.afterEach = function(title, fn) {
   if (this.isPending()) {
     return this;
   }
@@ -297,13 +308,7 @@ Suite.prototype.afterEach = function (title, fn) {
   }
   title = '"after each" hook' + (title ? ': ' + title : '');
 
-  var hook = new Hook(title, fn);
-  hook.parent = this;
-  hook.timeout(this.timeout());
-  hook.retries(this.retries());
-  hook.enableTimeouts(this.enableTimeouts());
-  hook.slow(this.slow());
-  hook.ctx = this.ctx;
+  var hook = this._createHook(title, fn);
   this._afterEach.push(hook);
   this.emit('afterEach', hook);
   return this;
@@ -316,7 +321,7 @@ Suite.prototype.afterEach = function (title, fn) {
  * @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());
@@ -335,7 +340,7 @@ Suite.prototype.addSuite = function (suite) {
  * @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());
@@ -351,10 +356,12 @@ Suite.prototype.addTest = function (test) {
  * Return the full title generated by recursively concatenating the parent's
  * full title.
  *
+ * @memberof Mocha.Suite
+ * @public
  * @api public
  * @return {string}
  */
-Suite.prototype.fullTitle = function () {
+Suite.prototype.fullTitle = function() {
   return this.titlePath().join(' ');
 };
 
@@ -362,10 +369,12 @@ Suite.prototype.fullTitle = function () {
  * Return the title path generated by recursively concatenating the parent's
  * title path.
  *
+ * @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());
@@ -379,13 +388,17 @@ Suite.prototype.titlePath = function () {
 /**
  * Return the total number of tests.
  *
+ * @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
+  );
 };
 
 /**
@@ -396,9 +409,9 @@ Suite.prototype.total = function () {
  * @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;
@@ -407,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,25 @@
 'use strict';
-
-/**
- * Module dependencies.
- */
-
 var Runnable = require('./runnable');
 var utils = require('./utils');
 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 new Error(
+      'Test `title` should be a "string" but "' +
+        typeof title +
+        '" was given instead.'
+    );
   }
   Runnable.call(this, title, fn);
   this.pending = !fn;
@@ -35,7 +31,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());