mocha 5.0.3 → 5.1.1

package/lib/reporters/json.js.orig

@@ -0,0 +1,128 @@
+'use strict';
+
+/**
+ * Module dependencies.
+ */
+
+var Base = require('./base');
+
+/**
+ * Expose `JSON`.
+ */
+
+exports = module.exports = JSONReporter;
+
+/**
+ * Initialize a new `JSON` reporter.
+ *
+ * @api public
+ * @param {Runner} runner
+ * @param {options} mocha invocation options. Invoking
+ *   `mocha -R --reporter-options output-file=asdf` yields options like:
+ *   { ... reporterOptions: { "output-file": "asdf" } ... }
+ */
+function JSONReporter (runner, options) {
+<<<<<<< HEAD
+=======
+  options = options || {};
+  var reptOptions = options.reporterOptions || {};
+>>>>>>> + json ouput controls: output-file, output-object
+  Base.call(this, runner);
+
+  var self = this;
+  var tests = [];
+  var pending = [];
+  var failures = [];
+  var passes = [];
+
+  runner.on('test end', function (test) {
+    tests.push(test);
+  });
+
+  runner.on('pass', function (test) {
+    passes.push(test);
+  });
+
+  runner.on('fail', function (test) {
+    failures.push(test);
+  });
+
+  runner.on('pending', function (test) {
+    pending.push(test);
+  });
+
+  runner.once('end', function () {
+    var obj = {
+      stats: self.stats,
+      tests: tests.map(clean),
+      pending: pending.map(clean),
+      failures: failures.map(clean),
+      passes: passes.map(clean)
+    };
+
+    runner.testResults = obj;
+<<<<<<< HEAD
+    if ('output-object' in options.reporterOptions) {
+      // Pass to reporter with: reporter("json", {"output-object": myObject})
+      Object.assign(options.reporterOptions['output-object'], obj);
+    } else {
+      var text = JSON.stringify(obj, null, 2);
+      if ('output-file' in options.reporterOptions) {
+        // Direct output with `mocha -R --reporter-options output-file=rpt.json`
+        try {
+          require('fs').writeFileSync(options.reporterOptions['output-file'], text);
+        } catch (e) {
+          console.warn('error writing to ' + options.reporterOptions.output + ':',  e);
+=======
+    if ('output-object' in reptOptions) {
+      // Pass to reporter with: reporter("json", {"output-object": myObject})
+      Object.assign(reptOptions['output-object'], obj);
+    } else {
+      var text = JSON.stringify(obj, null, 2);
+      if ('output-file' in reptOptions) {
+        // Direct output with `mocha -R --reporter-options output-file=rpt.json`
+        try {
+          require('fs').writeFileSync(reptOptions['output-file'], text);
+        } catch (e) {
+          console.warn('error writing to ' + reptOptions.output + ':', e);
+>>>>>>> + json ouput controls: output-file, output-object
+        }
+      } else {
+        process.stdout.write(text);
+      }
+    }
+  });
+}
+
+/**
+ * Return a plain-object representation of `test`
+ * free of cyclic properties etc.
+ *
+ * @api private
+ * @param {Object} test
+ * @return {Object}
+ */
+function clean (test) {
+  return {
+    title: test.title,
+    fullTitle: test.fullTitle(),
+    duration: test.duration,
+    currentRetry: test.currentRetry(),
+    err: errorJSON(test.err || {})
+  };
+}
+
+/**
+ * Transform `error` into a JSON object.
+ *
+ * @api private
+ * @param {Error} err
+ * @return {Object}
+ */
+function errorJSON (err) {
+  var res = {};
+  Object.getOwnPropertyNames(err).forEach(function (key) {
+    res[key] = err[key];
+  }, err);
+  return res;
+}

package/lib/reporters/landing.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module Landing
+ */
 /**
  * Module dependencies.
  */
@@ -36,6 +38,10 @@ Base.colors.runway = 90;
 /**
  * Initialize a new `Landing` reporter.
  *
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
  * @api public
  * @param {Runner} runner
  */

package/lib/reporters/list.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module List
+ */
 /**
  * Module dependencies.
  */
@@ -18,6 +20,10 @@ exports = module.exports = List;
 /**
  * Initialize a new `List` test reporter.
  *
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
  * @api public
  * @param {Runner} runner
  */

package/lib/reporters/markdown.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module Markdown
+ */
 /**
  * Module dependencies.
  */
@@ -22,6 +24,10 @@ exports = module.exports = Markdown;
 /**
  * Initialize a new `Markdown` reporter.
  *
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
  * @api public
  * @param {Runner} runner
  */

package/lib/reporters/min.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module Min
+ */
 /**
  * Module dependencies.
  */
@@ -16,6 +18,10 @@ exports = module.exports = Min;
 /**
  * Initialize a new `Min` minimal test reporter (best used with --watch).
  *
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
  * @api public
  * @param {Runner} runner
  */

package/lib/reporters/nyan.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module Nyan
+ */
 /**
  * Module dependencies.
  */
@@ -18,6 +20,10 @@ exports = module.exports = NyanCat;
  *
  * @param {Runner} runner
  * @api public
+ * @public
+ * @class Nyan
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
  */
 
 function NyanCat (runner) {

package/lib/reporters/progress.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module Progress
+ */
 /**
  * Module dependencies.
  */
@@ -24,6 +26,10 @@ Base.colors.progress = 90;
 /**
  * Initialize a new `Progress` bar test reporter.
  *
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
  * @api public
  * @param {Runner} runner
  * @param {Object} options

package/lib/reporters/spec.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module Spec
+ */
 /**
  * Module dependencies.
  */
@@ -17,6 +19,10 @@ exports = module.exports = Spec;
 /**
  * Initialize a new `Spec` test reporter.
  *
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
  * @api public
  * @param {Runner} runner
  */

package/lib/reporters/tap.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module TAP
+ */
 /**
  * Module dependencies.
  */
@@ -15,6 +17,10 @@ exports = module.exports = TAP;
 /**
  * Initialize a new `TAP` reporter.
  *
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
  * @api public
  * @param {Runner} runner
  */

package/lib/reporters/xunit.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module XUnit
+ */
 /**
  * Module dependencies.
  */
@@ -33,6 +35,10 @@ exports = module.exports = XUnit;
 /**
  * Initialize a new `XUnit` reporter.
  *
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
  * @api public
  * @param {Runner} runner
  */

package/lib/runnable.js

@@ -1,9 +1,10 @@
 'use strict';
-
+/**
+ * @module Runnable
+ */
 /**
  * Module dependencies.
  */
-
 var EventEmitter = require('events').EventEmitter;
 var Pending = require('./pending');
 var debug = require('debug')('mocha:runnable');
@@ -35,13 +36,13 @@ var toString = Object.prototype.toString;
 module.exports = Runnable;
 
 /**
- * Initialize a new `Runnable` with the given `title` and callback `fn`.
+ * Initialize a new `Runnable` with the given `title` and callback `fn`.  Derived from [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
  *
+ * @memberof Mocha
+ * @public
+ * @class
  * @param {String} title
  * @param {Function} fn
- * @api private
- * @param {string} title
- * @param {Function} fn
  */
 function Runnable (title, fn) {
   this.title = title;
@@ -103,7 +104,7 @@ Runnable.prototype.slow = function (ms) {
   if (typeof ms === 'string') {
     ms = milliseconds(ms);
   }
-  debug('timeout %d', ms);
+  debug('slow %d', ms);
   this._slow = ms;
   return this;
 };
@@ -127,6 +128,8 @@ Runnable.prototype.enableTimeouts = function (enabled) {
 /**
  * Halt and mark as pending.
  *
+ * @memberof Mocha.Runnable
+ * @public
  * @api public
  */
 Runnable.prototype.skip = function () {
@@ -188,6 +191,8 @@ Runnable.prototype.currentRetry = function (n) {
  * Return the full title generated by recursively concatenating the parent's
  * full title.
  *
+ * @memberof Mocha.Runnable
+ * @public
  * @api public
  * @return {string}
  */
@@ -198,6 +203,8 @@ Runnable.prototype.fullTitle = function () {
 /**
  * Return the title path generated by concatenating the parent's title path with the title.
  *
+ * @memberof Mocha.Runnable
+ * @public
  * @api public
  * @return {string}
  */
@@ -252,8 +259,7 @@ Runnable.prototype.resetTimeout = function () {
     if (!self._enableTimeouts) {
       return;
     }
-    self.callback(new Error('Timeout of ' + ms +
-      'ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves.'));
+    self.callback(self._timeoutError(ms));
     self.timedOut = true;
   }, ms);
 };
@@ -319,8 +325,7 @@ Runnable.prototype.run = function (fn) {
     self.duration = new Date() - start;
     finished = true;
     if (!err && self.duration > ms && self._enableTimeouts) {
-      err = new Error('Timeout of ' + ms +
-      'ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves.');
+      err = self._timeoutError(ms);
     }
     fn(err);
   }
@@ -417,3 +422,18 @@ Runnable.prototype.run = function (fn) {
     });
   }
 };
+
+/**
+ * Instantiates a "timeout" error
+ *
+ * @param {number} ms - Timeout (in milliseconds)
+ * @returns {Error} a "timeout" error
+ * @private
+ */
+Runnable.prototype._timeoutError = function (ms) {
+  var msg = 'Timeout of ' + ms + 'ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves.';
+  if (this.file) {
+    msg += ' (' + this.file + ')';
+  }
+  return new Error(msg);
+};

package/lib/runner.js

@@ -1,9 +1,11 @@
 'use strict';
 
+/**
+ * @module Runner
+ */
 /**
  * Module dependencies.
  */
-
 var EventEmitter = require('events').EventEmitter;
 var Pending = require('./pending');
 var utils = require('./utils');
@@ -37,7 +39,7 @@ var globals = [
 module.exports = Runner;
 
 /**
- * Initialize a `Runner` for the given `suite`.
+ * Initialize a `Runner` for the given `suite`. Derived from [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
  *
  * Events:
  *
@@ -53,8 +55,11 @@ module.exports = Runner;
  *   - `fail`  (test, err) test failed
  *   - `pending`  (test) test pending
  *
+ * @memberof Mocha
+ * @public
+ * @class
  * @api public
- * @param {Suite} suite Root suite
+ * @param {Suite} [suite] Root suite
  * @param {boolean} [delay] Whether or not to delay execution of root suite
  * until ready.
  */
@@ -95,10 +100,9 @@ inherits(Runner, EventEmitter);
  * Run tests with full titles matching `re`. Updates runner.total
  * with number of tests matched.
  *
- * @param {RegExp} re
- * @param {Boolean} invert
- * @return {Runner} for chaining
  * @api public
+ * @public
+ * @memberof Mocha.Runner
  * @param {RegExp} re
  * @param {boolean} invert
  * @return {Runner} Runner instance.
@@ -115,9 +119,9 @@ Runner.prototype.grep = function (re, invert) {
  * Returns the number of tests matching the grep search for the
  * given suite.
  *
- * @param {Suite} suite
- * @return {Number}
+ * @memberof Mocha.Runner
  * @api public
+ * @public
  * @param {Suite} suite
  * @return {number}
  */
@@ -161,9 +165,9 @@ Runner.prototype.globalProps = function () {
 /**
  * Allow the given `arr` of globals.
  *
- * @param {Array} arr
- * @return {Runner} for chaining
  * @api public
+ * @public
+ * @memberof Mocha.Runner
  * @param {Array} arr
  * @return {Runner} Runner instance.
  */
@@ -265,10 +269,10 @@ Runner.prototype.failHook = function (hook, err) {
     hook.title = hook.originalTitle + ' for "' + hook.ctx.currentTest.title + '"';
   }
 
-  this.fail(hook, err);
   if (this.suite.bail()) {
     this.emit('end');
   }
+  this.fail(hook, err);
 };
 
 /**
@@ -804,9 +808,9 @@ function cleanSuiteReferences (suite) {
  * Run the root suite and invoke `fn(failures)`
  * on completion.
  *
- * @param {Function} fn
- * @return {Runner} for chaining
  * @api public
+ * @public
+ * @memberof Mocha.Runner
  * @param {Function} fn
  * @return {Runner} Runner instance.
  */
@@ -863,6 +867,8 @@ Runner.prototype.run = function (fn) {
 /**
  * Cleanly abort execution.
  *
+ * @memberof Mocha.Runner
+ * @public
  * @api public
  * @return {Runner} Runner instance.
  */

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,6 +24,8 @@ 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
@@ -36,9 +40,11 @@ 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
  */
@@ -189,6 +195,25 @@ 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.
  *
@@ -207,13 +232,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;
@@ -237,13 +256,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;
@@ -267,13 +280,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;
@@ -297,13 +304,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;
@@ -351,6 +352,8 @@ 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}
  */
@@ -362,6 +365,8 @@ 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}
  */
@@ -379,6 +384,8 @@ Suite.prototype.titlePath = function () {
 /**
  * Return the total number of tests.
  *
+ * @memberof Mocha.Suite
+ * @public
  * @api public
  * @return {number}
  */