mocha 5.1.1 → 5.2.0

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+# 5.2.0 / 2018-05-18
+
+## :tada: Enhancements
+
+- [#3375]: Add support for comments in `mocha.opts` ([@plroebuck])
+
+## :bug: Fixes
+
+- [#3346]: Exit correctly from `before` hooks when using `--bail` ([@outsideris])
+
+## :book: Documentation
+
+- [#3328]: Mocha-flavored [API docs](https://mochajs.org/api/)! ([@Munter])
+
+## :nut_and_bolt: Other
+
+- [#3330]: Use `Buffer.from()` ([@harrysarson])
+- [#3295]: Remove redundant folder ([@DavNej])
+- [#3356]: Refactoring ([@plroebuck])
+
+[#3375]: https://github.com/mochajs/mocha/pull/3375
+[#3346]: https://github.com/mochajs/mocha/pull/3346
+[#3328]: https://github.com/mochajs/mocha/pull/3328
+[#3330]: https://github.com/mochajs/mocha/pull/3330
+[#3295]: https://github.com/mochajs/mocha/pull/3295
+[#3356]: https://github.com/mochajs/mocha/pull/3356
+
+[@plroebuck]: https://github.com/plroebuck
+[@harrysarson]: https://github.com/harrysarson
+[@outsideris]: https://github.com/outsideris
+[@Munter]: https://github.com/Munter
+
 # 5.1.1 / 2018-04-18
 
 ## :bug: Fixes

package/bin/_mocha

@@ -58,7 +58,7 @@ const exit = code => {
   // https://github.com/joyent/node/issues/6247 is just one bug example
   // https://github.com/visionmedia/mocha/issues/333 has a good discussion
   const done = () => {
-    if (!(draining--)) {
+    if (!draining--) {
       process.exit(clampedCode);
     }
   };
@@ -143,16 +143,23 @@ const requires = [];
  */
 
 const images = {
-  fail: path.join(__dirname, '..', 'images', 'error.png'),
-  pass: path.join(__dirname, '..', 'images', 'ok.png')
+  fail: path.join(__dirname, '..', 'assets', 'growl', 'error.png'),
+  pass: path.join(__dirname, '..', 'assets', 'growl', 'ok.png')
 };
 
 // options
 
 program
-  .version(JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version)
+  .version(
+    JSON.parse(
+      fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+    ).version
+  )
   .usage('[debug] [options] [files]')
-  .option('-A, --async-only', 'force all tests to take a callback (async) or return a promise')
+  .option(
+    '-A, --async-only',
+    'force all tests to take a callback (async) or return a promise'
+  )
   .option('-c, --colors', 'force enabling of colors')
   .option('-C, --no-colors', 'force disabling of colors')
   .option('-G, --growl', 'enable growl notification support')
@@ -168,24 +175,53 @@ program
   .option('-r, --require <name>', 'require the given module')
   .option('-s, --slow <ms>', '"slow" test threshold in milliseconds [75]')
   .option('-t, --timeout <ms>', 'set test-case timeout in milliseconds [2000]')
-  .option('-u, --ui <name>', `specify user-interface (${interfaceNames.join('|')})`, 'bdd')
+  .option(
+    '-u, --ui <name>',
+    `specify user-interface (${interfaceNames.join('|')})`,
+    'bdd'
+  )
   .option('-w, --watch', 'watch files for changes')
   .option('--check-leaks', 'check for global variable leaks')
   .option('--full-trace', 'display the full stack trace')
-  .option('--compilers <ext>:<module>,...', 'use the given module(s) to compile files', list, [])
+  .option(
+    '--compilers <ext>:<module>,...',
+    'use the given module(s) to compile files',
+    list,
+    []
+  )
   .option('--debug-brk', "enable node's debugger breaking on the first line")
-  .option('--globals <names>', 'allow the given comma-delimited global [names]', list, [])
+  .option(
+    '--globals <names>',
+    'allow the given comma-delimited global [names]',
+    list,
+    []
+  )
   .option('--es_staging', 'enable all staged features')
-  .option('--harmony<_classes,_generators,...>', 'all node --harmony* flags are available')
-  .option('--preserve-symlinks', 'Instructs the module loader to preserve symbolic links when resolving and caching modules')
+  .option(
+    '--harmony<_classes,_generators,...>',
+    'all node --harmony* flags are available'
+  )
+  .option(
+    '--preserve-symlinks',
+    'Instructs the module loader to preserve symbolic links when resolving and caching modules'
+  )
   .option('--icu-data-dir', 'include ICU data')
-  .option('--inline-diffs', 'display actual/expected differences inline within each string')
+  .option(
+    '--inline-diffs',
+    'display actual/expected differences inline within each string'
+  )
   .option('--no-diff', 'do not show a diff on failure')
   .option('--inspect', 'activate devtools in chrome')
-  .option('--inspect-brk', 'activate devtools in chrome and break on the first line')
+  .option(
+    '--inspect-brk',
+    'activate devtools in chrome and break on the first line'
+  )
   .option('--interfaces', 'display available interfaces')
   .option('--no-deprecation', 'silence deprecation warnings')
-  .option('--exit', 'force shutdown of the event loop after test run: mocha will call process.exit')
+  .option(
+    '--exit',
+    'force shutdown of the event loop after test run: mocha will call process.exit'
+  )
   .option('--no-timeouts', 'disables timeouts, given implicitly with --debug')
   .option('--no-warnings', 'silence all node process warnings')
   .option('--opts <path>', 'specify opts path', 'test/mocha.opts')
@@ -195,18 +231,37 @@ program
   .option('--log-timer-events', 'Time events including external callbacks')
   .option('--recursive', 'include sub directories')
   .option('--reporters', 'display available reporters')
-  .option('--retries <times>', 'set numbers of time to retry a failed test case')
-  .option('--throw-deprecation', 'throw an exception anytime a deprecated function is used')
+  .option(
+    '--retries <times>',
+    'set numbers of time to retry a failed test case'
+  )
+  .option(
+    '--throw-deprecation',
+    'throw an exception anytime a deprecated function is used'
+  )
   .option('--trace', 'trace function calls')
   .option('--trace-deprecation', 'show stack traces on deprecations')
   .option('--trace-warnings', 'show stack traces on node process warnings')
   .option('--use_strict', 'enforce strict mode')
-  .option('--watch-extensions <ext>,...', 'additional extensions to monitor with --watch', list, [])
+  .option(
+    '--watch-extensions <ext>,...',
+    'additional extensions to monitor with --watch',
+    list,
+    ['js']
+  )
   .option('--delay', 'wait for async suite definition')
   .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(
+    '--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('--exclude <file>', 'a file or glob pattern to ignore', collect, []);
 
 program._name = 'mocha';
@@ -312,19 +367,6 @@ if (program.reporterOptions !== undefined) {
 
 mocha.reporter(program.reporter, reporterOptions);
 
-// load reporter
-
-let Reporter = null;
-try {
-  Reporter = require(`../lib/reporters/${program.reporter}`);
-} catch (err) {
-  try {
-    Reporter = require(program.reporter);
-  } catch (err2) {
-    throw new Error(`reporter "${program.reporter}" does not exist`);
-  }
-}
-
 // --no-colors
 
 if (!program.colors) {
@@ -447,7 +489,7 @@ if (program.forbidPending) mocha.forbidPending();
 
 if (program.compilers.length > 0) {
   require('util').deprecate(() => {},
-    '"--compilers" will be removed in a future version of Mocha; see https://git.io/vdcSr for more info')();
+  '"--compilers" will be removed in a future version of Mocha; see https://git.io/vdcSr for more info')();
 }
 const extensions = ['js'];
 program.compilers.forEach(c => {
@@ -489,7 +531,9 @@ args.forEach(arg => {
     newFiles = utils.lookupFiles(arg, extensions, program.recursive);
   } catch (err) {
     if (err.message.indexOf('cannot resolve path') === 0) {
-      console.error(`Warning: Could not find any test files matching pattern: ${arg}`);
+      console.error(
+        `Warning: Could not find any test files matching pattern: ${arg}`
+      );
       return;
     }
 
@@ -500,7 +544,9 @@ args.forEach(arg => {
     if (typeof newFiles === 'string') {
       newFiles = [newFiles];
     }
-    newFiles = newFiles.filter(fileName => program.exclude.every(pattern => !minimatch(fileName, pattern)));
+    newFiles = newFiles.filter(fileName =>
+      program.exclude.every(pattern => !minimatch(fileName, pattern))
+    );
   }
 
   files = files.concat(newFiles);
@@ -538,7 +584,7 @@ if (program.watch) {
     process.exit(130);
   });
 
-  const watchFiles = utils.files(cwd, [ 'js' ].concat(program.watchExtensions));
+  const watchFiles = utils.files(cwd, ['js'].concat(program.watchExtensions));
   let runAgain = false;
 
   loadAndRun = () => {
@@ -585,7 +631,7 @@ if (program.watch) {
     }
   });
 } else {
-// load
+  // load
 
   mocha.files = files;
   runner = mocha.run(program.exit ? exit : exitLater);

package/bin/options.js

@@ -16,17 +16,23 @@ module.exports = getOptions;
  * Get options.
  */
 
-function getOptions () {
-  if (process.argv.length === 3 && (process.argv[2] === '-h' || process.argv[2] === '--help')) {
+function getOptions() {
+  if (
+    process.argv.length === 3 &&
+    (process.argv[2] === '-h' || process.argv[2] === '--help')
+  ) {
     return;
   }
 
-  const optsPath = process.argv.indexOf('--opts') === -1
-    ? 'test/mocha.opts'
-    : process.argv[process.argv.indexOf('--opts') + 1];
+  const optsPath =
+    process.argv.indexOf('--opts') === -1
+      ? 'test/mocha.opts'
+      : process.argv[process.argv.indexOf('--opts') + 1];
 
   try {
-    const opts = fs.readFileSync(optsPath, 'utf8')
+    const opts = fs
+      .readFileSync(optsPath, 'utf8')
+      .replace(/^#.*$/gm, '')
       .replace(/\\\s/g, '%20')
       .split(/\s/)
       .filter(Boolean)
@@ -35,8 +41,8 @@ function getOptions () {
     process.argv = process.argv
       .slice(0, 2)
       .concat(opts.concat(process.argv.slice(2)));
-  } catch (err) {
-    // ignore
+  } catch (ignore) {
+    // NOTE: should console.error() and throw the error
   }
 
   process.env.LOADED_MOCHA_OPTS = true;

package/browser-entry.js

@@ -17,7 +17,7 @@ var Mocha = require('./lib/mocha');
  * @return {undefined}
  */
 
-var mocha = new Mocha({ reporter: 'html' });
+var mocha = new Mocha({reporter: 'html'});
 
 /**
  * Save timer references to avoid Sinon interfering (see GH-237).
@@ -38,12 +38,12 @@ var originalOnerrorHandler = global.onerror;
  * Revert to original onerror handler if previously defined.
  */
 
-process.removeListener = function (e, fn) {
+process.removeListener = function(e, fn) {
   if (e === 'uncaughtException') {
     if (originalOnerrorHandler) {
       global.onerror = originalOnerrorHandler;
     } else {
-      global.onerror = function () {};
+      global.onerror = function() {};
     }
     var i = uncaughtExceptionHandlers.indexOf(fn);
     if (i !== -1) {
@@ -56,9 +56,9 @@ process.removeListener = function (e, fn) {
  * Implements uncaughtException listener.
  */
 
-process.on = function (e, fn) {
+process.on = function(e, fn) {
   if (e === 'uncaughtException') {
-    global.onerror = function (err, url, line) {
+    global.onerror = function(err, url, line) {
       fn(new Error(err + ' (' + url + ':' + line + ')'));
       return !mocha.allowUncaught;
     };
@@ -74,9 +74,9 @@ mocha.suite.removeAllListeners('pre-require');
 var immediateQueue = [];
 var immediateTimeout;
 
-function timeslice () {
+function timeslice() {
   var immediateStart = new Date().getTime();
-  while (immediateQueue.length && (new Date().getTime() - immediateStart) < 100) {
+  while (immediateQueue.length && new Date().getTime() - immediateStart < 100) {
     immediateQueue.shift()();
   }
   if (immediateQueue.length) {
@@ -90,7 +90,7 @@ function timeslice () {
  * High-performance override of Runner.immediately.
  */
 
-Mocha.Runner.immediately = function (callback) {
+Mocha.Runner.immediately = function(callback) {
   immediateQueue.push(callback);
   if (!immediateTimeout) {
     immediateTimeout = setTimeout(timeslice, 0);
@@ -102,8 +102,8 @@ Mocha.Runner.immediately = function (callback) {
  * This is useful when running tests in a browser because window.onerror will
  * only receive the 'message' attribute of the Error.
  */
-mocha.throwError = function (err) {
-  uncaughtExceptionHandlers.forEach(function (fn) {
+mocha.throwError = function(err) {
+  uncaughtExceptionHandlers.forEach(function(fn) {
     fn(err);
   });
   throw err;
@@ -114,7 +114,7 @@ mocha.throwError = function (err) {
  * Normally this would happen in Mocha.prototype.loadFiles.
  */
 
-mocha.ui = function (ui) {
+mocha.ui = function(ui) {
   Mocha.prototype.ui.call(this, ui);
   this.suite.emit('pre-require', global, null, this);
   return this;
@@ -124,9 +124,9 @@ mocha.ui = function (ui) {
  * Setup mocha with the given setting options.
  */
 
-mocha.setup = function (opts) {
+mocha.setup = function(opts) {
   if (typeof opts === 'string') {
-    opts = { ui: opts };
+    opts = {ui: opts};
   }
   for (var opt in opts) {
     if (opts.hasOwnProperty(opt)) {
@@ -140,7 +140,7 @@ mocha.setup = function (opts) {
  * Run mocha, returning the Runner.
  */
 
-mocha.run = function (fn) {
+mocha.run = function(fn) {
   var options = mocha.options;
   mocha.globals('location');
 
@@ -155,10 +155,14 @@ mocha.run = function (fn) {
     mocha.invert();
   }
 
-  return Mocha.prototype.run.call(mocha, function (err) {
+  return Mocha.prototype.run.call(mocha, function(err) {
     // The DOM Document is not available in Web Workers.
     var document = global.document;
-    if (document && document.getElementById('mocha') && options.noHighlighting !== true) {
+    if (
+      document &&
+      document.getElementById('mocha') &&
+      options.noHighlighting !== true
+    ) {
       Mocha.utils.highlightTags('code');
     }
     if (fn) {

package/lib/browser/progress.js

@@ -9,7 +9,7 @@ module.exports = Progress;
 /**
  * Initialize a new `Progress` indicator.
  */
-function Progress () {
+function Progress() {
   this.percent = 0;
   this.size(0);
   this.fontSize(11);
@@ -23,7 +23,7 @@ function Progress () {
  * @param {number} size
  * @return {Progress} Progress instance.
  */
-Progress.prototype.size = function (size) {
+Progress.prototype.size = function(size) {
   this._size = size;
   return this;
 };
@@ -35,7 +35,7 @@ Progress.prototype.size = function (size) {
  * @param {string} text
  * @return {Progress} Progress instance.
  */
-Progress.prototype.text = function (text) {
+Progress.prototype.text = function(text) {
   this._text = text;
   return this;
 };
@@ -47,7 +47,7 @@ Progress.prototype.text = function (text) {
  * @param {number} size
  * @return {Progress} Progress instance.
  */
-Progress.prototype.fontSize = function (size) {
+Progress.prototype.fontSize = function(size) {
   this._fontSize = size;
   return this;
 };
@@ -58,7 +58,7 @@ Progress.prototype.fontSize = function (size) {
  * @param {string} family
  * @return {Progress} Progress instance.
  */
-Progress.prototype.font = function (family) {
+Progress.prototype.font = function(family) {
   this._font = family;
   return this;
 };
@@ -69,7 +69,7 @@ Progress.prototype.font = function (family) {
  * @param {number} n
  * @return {Progress} Progress instance.
  */
-Progress.prototype.update = function (n) {
+Progress.prototype.update = function(n) {
   this.percent = n;
   return this;
 };
@@ -80,7 +80,7 @@ Progress.prototype.update = function (n) {
  * @param {CanvasRenderingContext2d} ctx
  * @return {Progress} Progress instance.
  */
-Progress.prototype.draw = function (ctx) {
+Progress.prototype.draw = function(ctx) {
   try {
     var percent = Math.min(this.percent, 100);
     var size = this._size;
@@ -112,7 +112,7 @@ Progress.prototype.draw = function (ctx) {
     var w = ctx.measureText(text).width;
 
     ctx.fillText(text, x - w / 2 + 1, y + fontSize / 2 - 1);
-  } catch (err) {
+  } catch (ignore) {
     // don't fail if we can't render progress
   }
   return this;

package/lib/browser/tty.js

@@ -1,10 +1,10 @@
 'use strict';
 
-exports.isatty = function isatty () {
+exports.isatty = function isatty() {
   return true;
 };
 
-exports.getWindowSize = function getWindowSize () {
+exports.getWindowSize = function getWindowSize() {
   if ('innerHeight' in global) {
     return [global.innerHeight, global.innerWidth];
   }

package/lib/context.js

@@ -13,7 +13,7 @@ module.exports = Context;
  *
  * @api private
  */
-function Context () {}
+function Context() {}
 
 /**
  * Set or get the context `Runnable` to `runnable`.
@@ -22,7 +22,7 @@ function Context () {}
  * @param {Runnable} runnable
  * @return {Context} context
  */
-Context.prototype.runnable = function (runnable) {
+Context.prototype.runnable = function(runnable) {
   if (!arguments.length) {
     return this._runnable;
   }
@@ -37,7 +37,7 @@ Context.prototype.runnable = function (runnable) {
  * @param {number} ms
  * @return {Context} self
  */
-Context.prototype.timeout = function (ms) {
+Context.prototype.timeout = function(ms) {
   if (!arguments.length) {
     return this.runnable().timeout();
   }
@@ -52,7 +52,7 @@ Context.prototype.timeout = function (ms) {
  * @param {boolean} enabled
  * @return {Context} self
  */
-Context.prototype.enableTimeouts = function (enabled) {
+Context.prototype.enableTimeouts = function(enabled) {
   if (!arguments.length) {
     return this.runnable().enableTimeouts();
   }
@@ -67,7 +67,7 @@ Context.prototype.enableTimeouts = function (enabled) {
  * @param {number} ms
  * @return {Context} self
  */
-Context.prototype.slow = function (ms) {
+Context.prototype.slow = function(ms) {
   if (!arguments.length) {
     return this.runnable().slow();
   }
@@ -81,7 +81,7 @@ Context.prototype.slow = function (ms) {
  * @api private
  * @throws Pending
  */
-Context.prototype.skip = function () {
+Context.prototype.skip = function() {
   this.runnable().skip();
 };
 
@@ -92,7 +92,7 @@ Context.prototype.skip = function () {
  * @param {number} n
  * @return {Context} self
  */
-Context.prototype.retries = function (n) {
+Context.prototype.retries = function(n) {
   if (!arguments.length) {
     return this.runnable().retries();
   }

package/lib/hook.js

@@ -1,11 +1,4 @@
 'use strict';
-/**
- * @module Hook
- *
- */
-/**
- * Module dependencies.
- */
 
 var Runnable = require('./runnable');
 var inherits = require('./utils').inherits;
@@ -17,17 +10,14 @@ var inherits = require('./utils').inherits;
 module.exports = Hook;
 
 /**
- * Initialize a new `Hook` with the given `title` and callback `fn`. Derived from
- * `Runnable`.
+ * Initialize a new `Hook` with the given `title` and callback `fn`
  *
- * @memberof Mocha
- * @public
  * @class
+ * @extends Runnable
  * @param {String} title
  * @param {Function} fn
- * @api private
  */
-function Hook (title, fn) {
+function Hook(title, fn) {
   Runnable.call(this, title, fn);
   this.type = 'hook';
 }
@@ -40,13 +30,12 @@ inherits(Hook, Runnable);
 /**
  * Get or set the test `err`.
  *
- * @memberof Mocha.Hook
+ * @memberof Hook
  * @public
  * @param {Error} err
  * @return {Error}
- * @api public
  */
-Hook.prototype.error = function (err) {
+Hook.prototype.error = function(err) {
   if (!arguments.length) {
     err = this._error;
     this._error = null;

package/lib/interfaces/bdd.js

@@ -1,9 +1,5 @@
 'use strict';
 
-/**
- * Module dependencies.
- */
-
 var Test = require('../test');
 
 /**
@@ -23,10 +19,10 @@ var Test = require('../test');
  *
  * @param {Suite} suite Root suite.
  */
-module.exports = function (suite) {
+module.exports = function bddInterface(suite) {
   var suites = [suite];
 
-  suite.on('pre-require', function (context, file, mocha) {
+  suite.on('pre-require', function(context, file, mocha) {
     var common = require('./common')(suites, context, mocha);
 
     context.before = common.before;
@@ -40,7 +36,7 @@ module.exports = function (suite) {
      * and/or tests.
      */
 
-    context.describe = context.context = function (title, fn) {
+    context.describe = context.context = function(title, fn) {
       return common.suite.create({
         title: title,
         file: file,
@@ -52,7 +48,10 @@ module.exports = function (suite) {
      * Pending describe.
      */
 
-    context.xdescribe = context.xcontext = context.describe.skip = function (title, fn) {
+    context.xdescribe = context.xcontext = context.describe.skip = function(
+      title,
+      fn
+    ) {
       return common.suite.skip({
         title: title,
         file: file,
@@ -64,7 +63,7 @@ module.exports = function (suite) {
      * Exclusive suite.
      */
 
-    context.describe.only = function (title, fn) {
+    context.describe.only = function(title, fn) {
       return common.suite.only({
         title: title,
         file: file,
@@ -78,7 +77,7 @@ module.exports = function (suite) {
      * acting as a thunk.
      */
 
-    context.it = context.specify = function (title, fn) {
+    context.it = context.specify = function(title, fn) {
       var suite = suites[0];
       if (suite.isPending()) {
         fn = null;
@@ -93,7 +92,7 @@ module.exports = function (suite) {
      * Exclusive test-case.
      */
 
-    context.it.only = function (title, fn) {
+    context.it.only = function(title, fn) {
       return common.test.only(mocha, context.it(title, fn));
     };
 
@@ -101,14 +100,14 @@ module.exports = function (suite) {
      * Pending test case.
      */
 
-    context.xit = context.xspecify = context.it.skip = function (title) {
+    context.xit = context.xspecify = context.it.skip = function(title) {
       return context.it(title);
     };
 
     /**
      * Number of attempts to retry.
      */
-    context.it.retries = function (n) {
+    context.it.retries = function(n) {
       context.retries(n);
     };
   });