mocha 5.0.3 → 5.1.1

package/CHANGELOG.md

@@ -1,3 +1,89 @@
+# 5.1.1 / 2018-04-18
+
+## :bug: Fixes
+
+- [#3325]: Revert change which broke `--watch` ([@boneskull])
+
+[#3325]: https://github.com/mochajs/mocha/issues/3325
+
+# 5.1.0 / 2018-04-12
+
+## :tada: Enhancements
+
+- [#3210]: Add `--exclude` option ([@metalex9])
+
+## :bug: Fixes
+
+- [#3318]: Fix failures in circular objects in JSON reporter ([@jeversmann], [@boneskull])
+
+## :book: Documentation
+
+- [#3323]: Publish actual [API documentation](https://mochajs.org/api/)! ([@dfberry], [@Munter])
+- [#3299]: Improve docs around exclusive tests ([@nicgirault])
+
+## :nut_and_bolt: Other
+
+- [#3302], [#3308], [#3310], [#3315], [#3316]: Build matrix improvements ([more info](https://boneskull.com/mocha-and-travis-ci-build-stages/)) ([@outsideris], [@boneskull])
+- [#3272]: Refactor reporter tests ([@jMuzsik])
+
+[#3210]: https://github.com/mochajs/mocha/pull/3210
+[#3318]: https://github.com/mochajs/mocha/pull/3318
+[#3323]: https://github.com/mochajs/mocha/pull/3323
+[#3299]: https://github.com/mochajs/mocha/pull/3299
+[#3302]: https://github.com/mochajs/mocha/pull/3302
+[#3308]: https://github.com/mochajs/mocha/pull/3308
+[#3310]: https://github.com/mochajs/mocha/pull/3310
+[#3315]: https://github.com/mochajs/mocha/pull/3315
+[#3316]: https://github.com/mochajs/mocha/pull/3316
+[#3272]: https://github.com/mochajs/mocha/pull/3272
+[@metalex9]: https://github.com/metalex9
+[@jeversmann]: https://github.com/jeversmann
+[@dfberry]: https://github.com/dfberry
+[@nicgirault]: https://github.com/nicgirault
+[@jMuzsik]: https://github.com/jMuzsik
+
+# 5.0.5 / 2018-03-22
+
+Welcome [@outsideris] to the team!
+
+## :bug: Fixes
+
+- [#3096]: Fix `--bail` failing to bail within hooks ([@outsideris])
+- [#3184]: Don't skip too many suites (using `describe.skip()`) ([@outsideris])
+
+## :book: Documentation
+
+- [#3133]: Improve docs regarding "pending" behavior ([@ematicipo])
+- [#3276], [#3274]: Fix broken stuff in `CHANGELOG.md` ([@tagoro9], [@honzajavorek])
+
+## :nut_and_bolt: Other
+
+- [#3208]: Improve test coverage for AMD users ([@outsideris])
+- [#3267]: Remove vestiges of PhantomJS from CI ([@anishkny])
+- [#2952]: Fix a debug message ([@boneskull])
+
+[#3096]: https://github.com/mochajs/mocha/issues/3096
+[#3184]: https://github.com/mochajs/mocha/issues/3184
+[#3133]: https://github.com/mochajs/mocha/issues/3133
+[#3276]: https://github.com/mochajs/mocha/pull/3276
+[#3274]: https://github.com/mochajs/mocha/pull/3274
+[#3208]: https://github.com/mochajs/mocha/issues/3208
+[#2952]: https://github.com/mochajs/mocha/issues/2952
+[#3267]: https://github.com/mochajs/mocha/pull/3267
+
+[@ematicipo]: https://github.com/ematicipo
+[@tagoro9]: https://github.com/tagoro9
+[@honzajavorek]: https://github.com/honajavorek
+[@anishkny]: https://github.com/anishkny
+
+# 5.0.4 / 2018-03-07
+
+## :bug: Fixes
+
+- [#3265]: Fixes regression in "watch" functionality introduced in v5.0.2 ([@outsideris])
+
+[#3265]: https://github.com/mochajs/mocha/issues/3265
+
 # 5.0.3 / 2018-03-06
 
 This patch features a fix to address a potential "low severity" [ReDoS vulnerability](https://snyk.io/vuln/npm:diff:20180305) in the [diff](https://npm.im/diff) package (a dependency of Mocha).
@@ -44,7 +130,7 @@ This release fixes a class of tests which report as *false positives*.  **Certai
   **Maintainers of external reporters**: *If* a test of this class is encountered, the `Runner` instance will emit the `end` event *twice*; you *may* need to change your reporter to use `runner.once('end')` intead of `runner.on('end')`.
 - [#3093]: Fix stack trace reformatting problem ([@outsideris])
 
-## :nut_and_bolt Other
+## :nut_and_bolt: Other
 
 - [#3248]: Update `browser-stdout` to v1.3.1 ([@honzajavorek])
 
@@ -79,10 +165,10 @@ Special thanks to [Wallaby.js](https://wallabyjs.com) for their continued suppor
 [#3119]: https://github.com/mochajs/mocha/issues/3119
 [#3132]: https://github.com/mochajs/mocha/issues/3132
 [#3098]: https://github.com/mochajs/mocha/issues/3098
-[#3212]: https://github.com/mochajs/mocha/pulls/3212
-[#3205]: https://github.com/mochajs/mocha/pulls/3205
-[#3224]: https://github.com/mochajs/mocha/pulls/3224
-[#3230]: https://github.com/mochajs/mocha/pulls/3230
+[#3212]: https://github.com/mochajs/mocha/pull/3212
+[#3205]: https://github.com/mochajs/mocha/pull/3205
+[#3224]: https://github.com/mochajs/mocha/pull/3224
+[#3230]: https://github.com/mochajs/mocha/pull/3230
 [@silviom]: https://github.com/silviom
 [@outsideris]: https://github.com/outsideris
 [@ArtemGovorov]: https://github.com/ArtemGovorov
@@ -342,9 +428,9 @@ For more info, please [read this article](https://boneskull.com/mocha-v4-nears-r
 - Various CI-and-test-related fixes and improvements ([@boneskull], [@dasilvacontin], [@PopradiArpad], [@Munter], [@ScottFreeCode])
 - "Officially" support Node.js 8 ([@elergy])
 
-[#2860]: https://github.com/mochajs/mocha/pulls/2860
-[#2696]: https://github.com/mochajs/mocha/pulls/2696
-[#2813]: https://github.com/mochajs/mocha/pulls/2813
+[#2860]: https://github.com/mochajs/mocha/pull/2860
+[#2696]: https://github.com/mochajs/mocha/pull/2696
+[#2813]: https://github.com/mochajs/mocha/pull/2813
 [@charlierudolph]: https://github.com/charlierudolph
 [@PopradiArpad]: https://github.com/PopradiArpad
 [@kungapal]: https://github.com/kungapal
@@ -366,7 +452,7 @@ For more info, please [read this article](https://boneskull.com/mocha-v4-nears-r
 [@makepanic]: https://github.com/makepanic
 [@Munter]: https://github.com/Munter
 
-[#2778]: https://github.com/mochajs/mocha/pulls/2778
+[#2778]: https://github.com/mochajs/mocha/pull/2778
 [#2802]: https://github.com/mochajs/mocha/issues/2802
 [#2820]: https://github.com/mochajs/mocha/pull/2820
 

package/bin/_mocha

@@ -10,6 +10,7 @@
 const program = require('commander');
 const path = require('path');
 const fs = require('fs');
+const minimatch = require('minimatch');
 const resolve = path.resolve;
 const exists = fs.existsSync;
 const Mocha = require('../');
@@ -205,7 +206,8 @@ program
   .option('--allow-uncaught', 'enable uncaught errors to propagate')
   .option('--forbid-only', 'causes test marked with only to fail the suite')
   .option('--forbid-pending', 'causes pending tests and test marked with skip to fail the suite')
-  .option('--file <file>', 'include a file to be ran during the suite', collect, []);
+  .option('--file <file>', 'include a file to be ran during the suite', collect, [])
+  .option('--exclude <file>', 'a file or glob pattern to ignore', collect, []);
 
 program._name = 'mocha';
 
@@ -494,6 +496,13 @@ args.forEach(arg => {
     throw err;
   }
 
+  if (typeof newFiles !== 'undefined') {
+    if (typeof newFiles === 'string') {
+      newFiles = [newFiles];
+    }
+    newFiles = newFiles.filter(fileName => program.exclude.every(pattern => !minimatch(fileName, pattern)));
+  }
+
   files = files.concat(newFiles);
 });
 

package/lib/context.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module Context
+ */
 /**
  * Expose `Context`.
  */
@@ -18,7 +20,7 @@ function Context () {}
  *
  * @api private
  * @param {Runnable} runnable
- * @return {Context}
+ * @return {Context} context
  */
 Context.prototype.runnable = function (runnable) {
   if (!arguments.length) {

package/lib/hook.js

@@ -1,5 +1,8 @@
 'use strict';
-
+/**
+ * @module Hook
+ *
+ */
 /**
  * Module dependencies.
  */
@@ -14,8 +17,12 @@ var inherits = require('./utils').inherits;
 module.exports = Hook;
 
 /**
- * Initialize a new `Hook` with the given `title` and callback `fn`.
+ * Initialize a new `Hook` with the given `title` and callback `fn`. Derived from
+ * `Runnable`.
  *
+ * @memberof Mocha
+ * @public
+ * @class
  * @param {String} title
  * @param {Function} fn
  * @api private
@@ -33,6 +40,8 @@ inherits(Hook, Runnable);
 /**
  * Get or set the test `err`.
  *
+ * @memberof Mocha.Hook
+ * @public
  * @param {Error} err
  * @return {Error}
  * @api public

package/lib/interfaces/common.js

@@ -113,6 +113,8 @@ module.exports = function (suites, context, mocha) {
           suites.shift();
         } else if (typeof opts.fn === 'undefined' && !suite.pending) {
           throw new Error('Suite "' + suite.fullTitle() + '" was defined but no callback was supplied. Supply a callback or explicitly skip the suite.');
+        } else if (!opts.fn && suite.pending) {
+          suites.shift();
         }
 
         return suite;

package/lib/mocha.js

@@ -5,7 +5,10 @@
  * Copyright(c) 2011 TJ Holowaychuk <tj@vision-media.ca>
  * MIT Licensed
  */
-
+/**
+ * @namespace Mocha
+ * @module Mocha
+ */
 /**
  * Module dependencies.
  */
@@ -34,11 +37,25 @@ if (!process.browser) {
  * Expose internals.
  */
 
+/**
+ * @public
+ * @class utils
+ * @memberof Mocha
+ */
 exports.utils = utils;
 exports.interfaces = require('./interfaces');
+/**
+ *
+ * @memberof Mocha
+ * @public
+ */
 exports.reporters = reporters;
 exports.Runnable = require('./runnable');
 exports.Context = require('./context');
+/**
+ *
+ * @memberof Mocha
+ */
 exports.Runner = require('./runner');
 exports.Suite = require('./suite');
 exports.Hook = require('./hook');
@@ -71,6 +88,8 @@ function image (name) {
  *   - `fullTrace` display the full stack-trace on failing
  *   - `grep` string or regexp to filter tests with
  *
+ * @public
+ * @class Mocha
  * @param {Object} options
  * @api public
  */
@@ -106,6 +125,7 @@ function Mocha (options) {
 /**
  * Enable or disable bailing on the first failure.
  *
+ * @public
  * @api public
  * @param {boolean} [bail]
  */
@@ -120,6 +140,7 @@ Mocha.prototype.bail = function (bail) {
 /**
  * Add test `file`.
  *
+ * @public
  * @api public
  * @param {string} file
  */
@@ -131,6 +152,7 @@ Mocha.prototype.addFile = function (file) {
 /**
  * Set reporter to `reporter`, defaults to "spec".
  *
+ * @public
  * @param {String|Function} reporter name or constructor
  * @param {Object} reporterOptions optional options
  * @api public
@@ -181,7 +203,7 @@ Mocha.prototype.reporter = function (reporter, reporterOptions) {
 
 /**
  * Set test UI `name`, defaults to "bdd".
- *
+ * @public
  * @api public
  * @param {string} bdd
  */
@@ -260,6 +282,7 @@ Mocha.prototype._growl = function (runner, reporter) {
 /**
  * Escape string and add it to grep as a regexp.
  *
+ * @public
  * @api public
  * @param str
  * @returns {Mocha}
@@ -271,6 +294,7 @@ Mocha.prototype.fgrep = function (str) {
 /**
  * Add regexp to grep, if `re` is a string it is escaped.
  *
+ * @public
  * @param {RegExp|String} re
  * @return {Mocha}
  * @api public
@@ -290,6 +314,7 @@ Mocha.prototype.grep = function (re) {
 /**
  * Invert `.grep()` matches.
  *
+ * @public
  * @return {Mocha}
  * @api public
  */
@@ -301,6 +326,7 @@ Mocha.prototype.invert = function () {
 /**
  * Ignore global leaks.
  *
+ * @public
  * @param {Boolean} ignore
  * @return {Mocha}
  * @api public
@@ -317,6 +343,7 @@ Mocha.prototype.ignoreLeaks = function (ignore) {
  *
  * @return {Mocha}
  * @api public
+ * @public
  */
 Mocha.prototype.checkLeaks = function () {
   this.options.ignoreLeaks = false;
@@ -328,6 +355,7 @@ Mocha.prototype.checkLeaks = function () {
  *
  * @return {Mocha}
  * @api public
+ * @public
  */
 Mocha.prototype.fullTrace = function () {
   this.options.fullStackTrace = true;
@@ -339,6 +367,7 @@ Mocha.prototype.fullTrace = function () {
  *
  * @return {Mocha}
  * @api public
+ * @public
  */
 Mocha.prototype.growl = function () {
   this.options.growl = true;
@@ -351,6 +380,7 @@ Mocha.prototype.growl = function () {
  * @param {Array|String} globals
  * @return {Mocha}
  * @api public
+ * @public
  * @param {Array|string} globals
  * @return {Mocha}
  */
@@ -365,6 +395,7 @@ Mocha.prototype.globals = function (globals) {
  * @param {Boolean} colors
  * @return {Mocha}
  * @api public
+ * @public
  * @param {boolean} colors
  * @return {Mocha}
  */
@@ -381,6 +412,7 @@ Mocha.prototype.useColors = function (colors) {
  * @param {Boolean} inlineDiffs
  * @return {Mocha}
  * @api public
+ * @public
  * @param {boolean} inlineDiffs
  * @return {Mocha}
  */
@@ -395,6 +427,7 @@ Mocha.prototype.useInlineDiffs = function (inlineDiffs) {
  * @param {Boolean} hideDiff
  * @return {Mocha}
  * @api public
+ * @public
  * @param {boolean} hideDiff
  * @return {Mocha}
  */
@@ -409,6 +442,7 @@ Mocha.prototype.hideDiff = function (hideDiff) {
  * @param {Number} timeout
  * @return {Mocha}
  * @api public
+ * @public
  * @param {number} timeout
  * @return {Mocha}
  */
@@ -423,6 +457,7 @@ Mocha.prototype.timeout = function (timeout) {
  * @param {Number} retry times
  * @return {Mocha}
  * @api public
+ * @public
  */
 Mocha.prototype.retries = function (n) {
   this.suite.retries(n);
@@ -435,6 +470,7 @@ Mocha.prototype.retries = function (n) {
  * @param {Number} slow
  * @return {Mocha}
  * @api public
+ * @public
  * @param {number} slow
  * @return {Mocha}
  */
@@ -449,6 +485,7 @@ Mocha.prototype.slow = function (slow) {
  * @param {Boolean} enabled
  * @return {Mocha}
  * @api public
+ * @public
  * @param {boolean} enabled
  * @return {Mocha}
  */
@@ -462,6 +499,7 @@ Mocha.prototype.enableTimeouts = function (enabled) {
  *
  * @return {Mocha}
  * @api public
+ * @public
  */
 Mocha.prototype.asyncOnly = function () {
   this.options.asyncOnly = true;
@@ -472,6 +510,7 @@ Mocha.prototype.asyncOnly = function () {
  * Disable syntax highlighting (in browser).
  *
  * @api public
+ * @public
  */
 Mocha.prototype.noHighlighting = function () {
   this.options.noHighlighting = true;
@@ -483,6 +522,7 @@ Mocha.prototype.noHighlighting = function () {
  *
  * @return {Mocha}
  * @api public
+ * @public
  */
 Mocha.prototype.allowUncaught = function () {
   this.options.allowUncaught = true;
@@ -528,6 +568,7 @@ Mocha.prototype.forbidPending = function () {
  * cache first in whichever manner best suits your needs.
  *
  * @api public
+ * @public
  * @param {Function} fn
  * @return {Runner}
  */

package/lib/ms.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module milliseconds
+ */
 /**
  * Helpers.
  */
@@ -13,6 +15,8 @@ var y = d * 365.25;
 /**
  * Parse or format the given `val`.
  *
+ * @memberof Mocha
+ * @public
  * @api public
  * @param {string|number} val
  * @return {string|number}

package/lib/reporters/base.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module Base
+ */
 /**
  * Module dependencies.
  */
@@ -185,6 +187,9 @@ var generateDiff = exports.generateDiff = function (actual, expected) {
 /**
  * Output the given `failures` as a list.
  *
+ * @public
+ * @memberof Mocha.reporters.Base
+ * @variation 1
  * @param {Array} failures
  * @api public
  */
@@ -261,6 +266,9 @@ exports.list = function (failures) {
  * stats such as test duration, number
  * of tests passed / failed etc.
  *
+ * @memberof Mocha.reporters
+ * @public
+ * @class
  * @param {Runner} runner
  * @api public
  */
@@ -328,6 +336,8 @@ function Base (runner) {
  * Output common epilogue used by many of
  * the bundled reporters.
  *
+ * @memberof Mocha.reporters.Base
+ * @public
  * @api public
  */
 Base.prototype.epilogue = function () {

package/lib/reporters/doc.js

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

package/lib/reporters/dot.js

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

package/lib/reporters/html.js

@@ -1,7 +1,9 @@
 'use strict';
 
 /* eslint-env browser */
-
+/**
+ * @module HTML
+ */
 /**
  * Module dependencies.
  */
@@ -46,6 +48,10 @@ var playIcon = '‣';
 /**
  * Initialize a new `HTML` reporter.
  *
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
  * @api public
  * @param {Runner} runner
  */

package/lib/reporters/json-stream.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module JSONStream
+ */
 /**
  * Module dependencies.
  */
@@ -13,8 +15,13 @@ var Base = require('./base');
 exports = module.exports = List;
 
 /**
- * Initialize a new `List` test reporter.
+ * Initialize a new `JSONStream` test reporter.
  *
+ * @public
+ * @name JSONStream
+ * @class JSONStream
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
  * @api public
  * @param {Runner} runner
  */

package/lib/reporters/json.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module JSON
+ */
 /**
  * Module dependencies.
  */
@@ -15,6 +17,10 @@ exports = module.exports = JSONReporter;
 /**
  * Initialize a new `JSON` reporter.
  *
+ * @public
+ * @class JSON
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
  * @api public
  * @param {Runner} runner
  */
@@ -67,17 +73,44 @@ function JSONReporter (runner) {
  * @return {Object}
  */
 function clean (test) {
+  var err = test.err || {};
+  if (err instanceof Error) {
+    err = errorJSON(err);
+  }
+
   return {
     title: test.title,
     fullTitle: test.fullTitle(),
     duration: test.duration,
     currentRetry: test.currentRetry(),
-    err: errorJSON(test.err || {})
+    err: cleanCycles(err)
   };
 }
 
 /**
- * Transform `error` into a JSON object.
+ * Replaces any circular references inside `obj` with '[object Object]'
+ *
+ * @api private
+ * @param {Object} obj
+ * @return {Object}
+ */
+function cleanCycles (obj) {
+  var cache = [];
+  return JSON.parse(JSON.stringify(obj, function (key, value) {
+    if (typeof value === 'object' && value !== null) {
+      if (cache.indexOf(value) !== -1) {
+        // Instead of going in a circle, we'll print [object Object]
+        return '' + value;
+      }
+      cache.push(value);
+    }
+
+    return value;
+  }));
+}
+
+/**
+ * Transform an Error object into a JSON object.
  *
  * @api private
  * @param {Error} err