mocha 5.1.1 → 6.0.0

package/lib/context.js

@@ -11,18 +11,18 @@ module.exports = Context;
 /**
  * Initialize a new `Context`.
  *
- * @api private
+ * @private
  */
-function Context () {}
+function Context() {}
 
 /**
  * Set or get the context `Runnable` to `runnable`.
  *
- * @api private
+ * @private
  * @param {Runnable} runnable
  * @return {Context} context
  */
-Context.prototype.runnable = function (runnable) {
+Context.prototype.runnable = function(runnable) {
   if (!arguments.length) {
     return this._runnable;
   }
@@ -33,11 +33,11 @@ Context.prototype.runnable = function (runnable) {
 /**
  * Set or get test timeout `ms`.
  *
- * @api private
+ * @private
  * @param {number} ms
  * @return {Context} self
  */
-Context.prototype.timeout = function (ms) {
+Context.prototype.timeout = function(ms) {
   if (!arguments.length) {
     return this.runnable().timeout();
   }
@@ -48,11 +48,11 @@ Context.prototype.timeout = function (ms) {
 /**
  * Set test timeout `enabled`.
  *
- * @api private
+ * @private
  * @param {boolean} enabled
  * @return {Context} self
  */
-Context.prototype.enableTimeouts = function (enabled) {
+Context.prototype.enableTimeouts = function(enabled) {
   if (!arguments.length) {
     return this.runnable().enableTimeouts();
   }
@@ -63,11 +63,11 @@ Context.prototype.enableTimeouts = function (enabled) {
 /**
  * Set or get test slowness threshold `ms`.
  *
- * @api private
+ * @private
  * @param {number} ms
  * @return {Context} self
  */
-Context.prototype.slow = function (ms) {
+Context.prototype.slow = function(ms) {
   if (!arguments.length) {
     return this.runnable().slow();
   }
@@ -78,21 +78,21 @@ Context.prototype.slow = function (ms) {
 /**
  * Mark a test as skipped.
  *
- * @api private
+ * @private
  * @throws Pending
  */
-Context.prototype.skip = function () {
+Context.prototype.skip = function() {
   this.runnable().skip();
 };
 
 /**
  * Set or get a number of allowed retries on failed tests
  *
- * @api private
+ * @private
  * @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/errors.js

@@ -0,0 +1,141 @@
+'use strict';
+/**
+ * @module Errors
+ */
+/**
+ * Factory functions to create throwable error objects
+ */
+
+/**
+ * Creates an error object to be thrown when no files to be tested could be found using specified pattern.
+ *
+ * @public
+ * @param {string} message - Error message to be displayed.
+ * @param {string} pattern - User-specified argument value.
+ * @returns {Error} instance detailing the error condition
+ */
+function createNoFilesMatchPatternError(message, pattern) {
+  var err = new Error(message);
+  err.code = 'ERR_MOCHA_NO_FILES_MATCH_PATTERN';
+  err.pattern = pattern;
+  return err;
+}
+
+/**
+ * Creates an error object to be thrown when the reporter specified in the options was not found.
+ *
+ * @public
+ * @param {string} message - Error message to be displayed.
+ * @param {string} reporter - User-specified reporter value.
+ * @returns {Error} instance detailing the error condition
+ */
+function createInvalidReporterError(message, reporter) {
+  var err = new TypeError(message);
+  err.code = 'ERR_MOCHA_INVALID_REPORTER';
+  err.reporter = reporter;
+  return err;
+}
+
+/**
+ * Creates an error object to be thrown when the interface specified in the options was not found.
+ *
+ * @public
+ * @param {string} message - Error message to be displayed.
+ * @param {string} ui - User-specified interface value.
+ * @returns {Error} instance detailing the error condition
+ */
+function createInvalidInterfaceError(message, ui) {
+  var err = new Error(message);
+  err.code = 'ERR_MOCHA_INVALID_INTERFACE';
+  err.interface = ui;
+  return err;
+}
+
+/**
+ * Creates an error object to be thrown when a behavior, option, or parameter is unsupported.
+ *
+ * @public
+ * @param {string} message - Error message to be displayed.
+ * @returns {Error} instance detailing the error condition
+ */
+function createUnsupportedError(message) {
+  var err = new Error(message);
+  err.code = 'ERR_MOCHA_UNSUPPORTED';
+  return err;
+}
+
+/**
+ * Creates an error object to be thrown when an argument is missing.
+ *
+ * @public
+ * @param {string} message - Error message to be displayed.
+ * @param {string} argument - Argument name.
+ * @param {string} expected - Expected argument datatype.
+ * @returns {Error} instance detailing the error condition
+ */
+function createMissingArgumentError(message, argument, expected) {
+  return createInvalidArgumentTypeError(message, argument, expected);
+}
+
+/**
+ * Creates an error object to be thrown when an argument did not use the supported type
+ *
+ * @public
+ * @param {string} message - Error message to be displayed.
+ * @param {string} argument - Argument name.
+ * @param {string} expected - Expected argument datatype.
+ * @returns {Error} instance detailing the error condition
+ */
+function createInvalidArgumentTypeError(message, argument, expected) {
+  var err = new TypeError(message);
+  err.code = 'ERR_MOCHA_INVALID_ARG_TYPE';
+  err.argument = argument;
+  err.expected = expected;
+  err.actual = typeof argument;
+  return err;
+}
+
+/**
+ * Creates an error object to be thrown when an argument did not use the supported value
+ *
+ * @public
+ * @param {string} message - Error message to be displayed.
+ * @param {string} argument - Argument name.
+ * @param {string} value - Argument value.
+ * @param {string} [reason] - Why value is invalid.
+ * @returns {Error} instance detailing the error condition
+ */
+function createInvalidArgumentValueError(message, argument, value, reason) {
+  var err = new TypeError(message);
+  err.code = 'ERR_MOCHA_INVALID_ARG_VALUE';
+  err.argument = argument;
+  err.value = value;
+  err.reason = typeof reason !== 'undefined' ? reason : 'is invalid';
+  return err;
+}
+
+/**
+ * Creates an error object to be thrown when an exception was caught, but the `Error` is falsy or undefined.
+ *
+ * @public
+ * @param {string} message - Error message to be displayed.
+ * @returns {Error} instance detailing the error condition
+ */
+function createInvalidExceptionError(message, value) {
+  var err = new Error(message);
+  err.code = 'ERR_MOCHA_INVALID_EXCEPTION';
+  err.valueType = typeof value;
+  err.value = value;
+  return err;
+}
+
+module.exports = {
+  createInvalidArgumentTypeError: createInvalidArgumentTypeError,
+  createInvalidArgumentValueError: createInvalidArgumentValueError,
+  createInvalidExceptionError: createInvalidExceptionError,
+  createInvalidInterfaceError: createInvalidInterfaceError,
+  createInvalidReporterError: createInvalidReporterError,
+  createMissingArgumentError: createMissingArgumentError,
+  createNoFilesMatchPatternError: createNoFilesMatchPatternError,
+  createUnsupportedError: createUnsupportedError
+};

package/lib/growl.js

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * Desktop Notifications module.
+ * @module Growl
+ */
+
+const os = require('os');
+const path = require('path');
+const {sync: which} = require('which');
+const {EVENT_RUN_END} = require('./runner').constants;
+
+/**
+ * @summary
+ * Checks if Growl notification support seems likely.
+ *
+ * @description
+ * Glosses over the distinction between an unsupported platform
+ * and one that lacks prerequisite software installations.
+ *
+ * @public
+ * @see {@link https://github.com/tj/node-growl/blob/master/README.md|Prerequisite Installs}
+ * @see {@link Mocha#growl}
+ * @see {@link Mocha#isGrowlCapable}
+ * @return {boolean} whether Growl notification support can be expected
+ */
+exports.isCapable = () => {
+  if (!process.browser) {
+    return getSupportBinaries().reduce(
+      (acc, binary) => acc || Boolean(which(binary, {nothrow: true})),
+      false
+    );
+  }
+  return false;
+};
+
+/**
+ * Implements desktop notifications as a pseudo-reporter.
+ *
+ * @public
+ * @see {@link Mocha#_growl}
+ * @param {Runner} runner - Runner instance.
+ */
+exports.notify = runner => {
+  runner.once(EVENT_RUN_END, () => {
+    display(runner);
+  });
+};
+
+/**
+ * Displays the notification.
+ *
+ * @private
+ * @param {Runner} runner - Runner instance.
+ */
+const display = runner => {
+  const growl = require('growl');
+  const stats = runner.stats;
+  const symbol = {
+    cross: '\u274C',
+    tick: '\u2705'
+  };
+  let _message;
+  let message;
+  let title;
+
+  if (stats.failures) {
+    _message = `${stats.failures} of ${stats.tests} tests failed`;
+    message = `${symbol.cross} ${_message}`;
+    title = 'Failed';
+  } else {
+    _message = `${stats.passes} tests passed in ${stats.duration}ms`;
+    message = `${symbol.tick} ${_message}`;
+    title = 'Passed';
+  }
+
+  // Send notification
+  const options = {
+    image: logo(),
+    name: 'mocha',
+    title
+  };
+  growl(message, options, onCompletion);
+};
+
+/**
+ * @summary
+ * Callback for result of attempted Growl notification.
+ *
+ * @description
+ * Despite its appearance, this is <strong>not</strong> an Error-first
+ * callback -- all parameters are populated regardless of success.
+ *
+ * @private
+ * @callback Growl~growlCB
+ * @param {*} err - Error object, or <code>null</code> if successful.
+ */
+function onCompletion(err) {
+  if (err) {
+    // As notifications are tangential to our purpose, just log the error.
+    const message =
+      err.code === 'ENOENT' ? 'prerequisite software not found' : err.message;
+    console.error('notification error:', message);
+  }
+}
+
+/**
+ * Returns Mocha logo image path.
+ *
+ * @private
+ * @return {string} Pathname of Mocha logo
+ */
+const logo = () => {
+  return path.join(__dirname, '..', 'assets', 'mocha-logo-96.png');
+};
+
+/**
+ * @summary
+ * Gets platform-specific Growl support binaries.
+ *
+ * @description
+ * Somewhat brittle dependency on `growl` package implementation, but it
+ * rarely changes.
+ *
+ * @private
+ * @see {@link https://github.com/tj/node-growl/blob/master/lib/growl.js#L28-L126|setupCmd}
+ * @return {string[]} names of Growl support binaries
+ */
+const getSupportBinaries = () => {
+  const binaries = {
+    Darwin: ['terminal-notifier', 'growlnotify'],
+    Linux: ['notify-send', 'growl'],
+    Windows_NT: ['growlnotify.exe']
+  };
+  return binaries[os.type()] || [];
+};

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,10 +1,8 @@
 'use strict';
 
-/**
- * Module dependencies.
- */
-
 var Test = require('../test');
+var EVENT_FILE_PRE_REQUIRE = require('../suite').constants
+  .EVENT_FILE_PRE_REQUIRE;
 
 /**
  * BDD-style interface:
@@ -23,10 +21,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(EVENT_FILE_PRE_REQUIRE, function(context, file, mocha) {
     var common = require('./common')(suites, context, mocha);
 
     context.before = common.before;
@@ -40,7 +38,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 +50,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 +65,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 +79,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 +94,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,15 +102,17 @@ 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);
     };
   });
 };
+
+module.exports.description = 'BDD or RSpec style [default]';

package/lib/interfaces/common.js

@@ -1,6 +1,9 @@
 'use strict';
 
 var Suite = require('../suite');
+var utils = require('../utils');
+var errors = require('../errors');
+var createMissingArgumentError = errors.createMissingArgumentError;
 
 /**
  * Functions common to more than one interface.
@@ -10,7 +13,23 @@ var Suite = require('../suite');
  * @param {Mocha} mocha
  * @return {Object} An object containing common functions.
  */
-module.exports = function (suites, context, mocha) {
+module.exports = function(suites, context, mocha) {
+  /**
+   * Check if the suite should be tested.
+   *
+   * @private
+   * @param {Suite} suite - suite to check
+   * @returns {boolean}
+   */
+  function shouldBeTested(suite) {
+    return (
+      !mocha.options.grep ||
+      (mocha.options.grep &&
+        mocha.options.grep.test(suite.fullTitle()) &&
+        !mocha.options.invert)
+    );
+  }
+
   return {
     /**
      * This is only present if flag --delay is passed into Mocha. It triggers
@@ -19,8 +38,8 @@ module.exports = function (suites, context, mocha) {
      * @param {Suite} suite The root suite.
      * @return {Function} A function which runs the root suite
      */
-    runWithSuite: function runWithSuite (suite) {
-      return function run () {
+    runWithSuite: function runWithSuite(suite) {
+      return function run() {
         suite.run();
       };
     },
@@ -31,7 +50,7 @@ module.exports = function (suites, context, mocha) {
      * @param {string} name
      * @param {Function} fn
      */
-    before: function (name, fn) {
+    before: function(name, fn) {
       suites[0].beforeAll(name, fn);
     },
 
@@ -41,7 +60,7 @@ module.exports = function (suites, context, mocha) {
      * @param {string} name
      * @param {Function} fn
      */
-    after: function (name, fn) {
+    after: function(name, fn) {
       suites[0].afterAll(name, fn);
     },
 
@@ -51,7 +70,7 @@ module.exports = function (suites, context, mocha) {
      * @param {string} name
      * @param {Function} fn
      */
-    beforeEach: function (name, fn) {
+    beforeEach: function(name, fn) {
       suites[0].beforeEach(name, fn);
     },
 
@@ -61,7 +80,7 @@ module.exports = function (suites, context, mocha) {
      * @param {string} name
      * @param {Function} fn
      */
-    afterEach: function (name, fn) {
+    afterEach: function(name, fn) {
       suites[0].afterEach(name, fn);
     },
 
@@ -73,7 +92,7 @@ module.exports = function (suites, context, mocha) {
        * @param {Object} opts
        * @returns {Suite}
        */
-      only: function only (opts) {
+      only: function only(opts) {
         opts.isOnly = true;
         return this.create(opts);
       },
@@ -85,13 +104,14 @@ module.exports = function (suites, context, mocha) {
        * @param {Object} opts
        * @returns {Suite}
        */
-      skip: function skip (opts) {
+      skip: function skip(opts) {
         opts.pending = true;
         return this.create(opts);
       },
 
       /**
        * Creates a suite.
+       *
        * @param {Object} opts Options
        * @param {string} opts.title Title of Suite
        * @param {Function} [opts.fn] Suite Function (not always applicable)
@@ -100,19 +120,44 @@ module.exports = function (suites, context, mocha) {
        * @param {boolean} [opts.isOnly] Is Suite exclusive?
        * @returns {Suite}
        */
-      create: function create (opts) {
+      create: function create(opts) {
         var suite = Suite.create(suites[0], opts.title);
         suite.pending = Boolean(opts.pending);
         suite.file = opts.file;
         suites.unshift(suite);
         if (opts.isOnly) {
-          suite.parent._onlySuites = suite.parent._onlySuites.concat(suite);
+          if (mocha.options.forbidOnly && shouldBeTested(suite)) {
+            throw new Error('`.only` forbidden');
+          }
+
+          suite.parent.appendOnlySuite(suite);
+        }
+        if (suite.pending) {
+          if (mocha.options.forbidPending && shouldBeTested(suite)) {
+            throw new Error('Pending test forbidden');
+          }
         }
         if (typeof opts.fn === 'function') {
-          opts.fn.call(suite);
+          var result = opts.fn.call(suite);
+          if (typeof result !== 'undefined') {
+            utils.deprecate(
+              'Suites ignore return values. Suite "' +
+                suite.fullTitle() +
+                '" in ' +
+                suite.file +
+                ' returned a value; this may be a bug in your test code'
+            );
+          }
           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.');
+          throw createMissingArgumentError(
+            'Suite "' +
+              suite.fullTitle() +
+              '" was defined but no callback was supplied. ' +
+              'Supply a callback or explicitly skip the suite.',
+            'callback',
+            'function'
+          );
         } else if (!opts.fn && suite.pending) {
           suites.shift();
         }
@@ -122,7 +167,6 @@ module.exports = function (suites, context, mocha) {
     },
 
     test: {
-
       /**
        * Exclusive test-case.
        *
@@ -130,8 +174,8 @@ module.exports = function (suites, context, mocha) {
        * @param {Function} test
        * @returns {*}
        */
-      only: function (mocha, test) {
-        test.parent._onlyTests = test.parent._onlyTests.concat(test);
+      only: function(mocha, test) {
+        test.parent.appendOnlyTest(test);
         return test;
       },
 
@@ -140,7 +184,7 @@ module.exports = function (suites, context, mocha) {
        *
        * @param {string} title
        */
-      skip: function (title) {
+      skip: function(title) {
         context.test(title);
       },
 
@@ -149,7 +193,7 @@ module.exports = function (suites, context, mocha) {
        *
        * @param {number} n
        */
-      retries: function (n) {
+      retries: function(n) {
         context.retries(n);
       }
     }