mocha 5.1.0 → 6.0.0-1

package/bin/mocha

@@ -3,75 +3,101 @@
 'use strict';
 
 /**
- * This tiny wrapper file checks for known node flags and appends them
- * when found, before invoking the "real" _mocha(1) executable.
+ * This wrapper executable checks for known node flags and appends them when found, before invoking the "real" _mocha(1) executable.
+ *
+ * @module bin/mocha
+ * @private
  */
 
-const spawn = require('child_process').spawn;
-const path = require('path');
-const getOptions = require('./options');
-const args = [path.join(__dirname, '_mocha')];
+const {deprecate} = require('../lib/utils');
+const {spawn} = require('child_process');
+const {loadOptions} = require('../lib/cli/options');
+const {isNodeFlag, impliesNoTimeouts} = require('../lib/cli/node-flags');
+const unparse = require('yargs-unparser');
+const debug = require('debug')('mocha:cli');
+const {aliases} = require('../lib/cli/run-option-metadata');
 
-// Load mocha.opts into process.argv
-// Must be loaded here to handle node-specific options
-getOptions();
+const mochaPath = require.resolve('./_mocha');
+const childOpts = {};
+const nodeOpts = {};
 
-process.argv.slice(2).forEach(arg => {
-  const flag = arg.split('=')[0];
+const opts = loadOptions(process.argv.slice(2));
+debug('loaded opts', opts);
 
-  switch (flag) {
-    case '-d':
-      args.unshift('--debug');
-      args.push('--no-timeouts');
-      break;
-    case 'debug':
-    case '--debug':
-    case '--debug-brk':
-    case '--inspect':
-    case '--inspect-brk':
-      args.unshift(arg);
-      args.push('--no-timeouts');
-      break;
-    case '-gc':
-    case '--expose-gc':
-      args.unshift('--expose-gc');
-      break;
-    case '--gc-global':
-    case '--es_staging':
-    case '--no-deprecation':
-    case '--no-warnings':
-    case '--prof':
-    case '--log-timer-events':
-    case '--throw-deprecation':
-    case '--trace-deprecation':
-    case '--trace-warnings':
-    case '--use_strict':
-    case '--allow-natives-syntax':
-    case '--perf-basic-prof':
-    case '--napi-modules':
-      args.unshift(arg);
-      break;
-    default:
-      if (arg.indexOf('--harmony') === 0) {
-        args.unshift(arg);
-      } else if (arg.indexOf('--trace') === 0) {
-        args.unshift(arg);
-      } else if (arg.indexOf('--icu-data-dir') === 0) {
-        args.unshift(arg);
-      } else if (arg.indexOf('--max-old-space-size') === 0) {
-        args.unshift(arg);
-      } else if (arg.indexOf('--preserve-symlinks') === 0) {
-        args.unshift(arg);
-      } else {
-        args.push(arg);
-      }
-      break;
+Object.keys(opts).forEach(opt => {
+  if (isNodeFlag(opt)) {
+    if (/^v8-/.test(opt)) {
+      opt = opt.slice(2);
+    }
+    nodeOpts[opt] = opts[opt];
+    if (impliesNoTimeouts(opt)) {
+      debug(`option "${opt}" disabled timeouts`);
+      childOpts.timeout = false;
+    }
+  } else {
+    childOpts[opt] = opts[opt];
   }
 });
 
+// allow --debug to invoke --inspect on Node.js v8 or newer  nodeOpts.inspect = childOpts.debug;
+if (childOpts.debug) {
+  childOpts.timeout = false;
+  delete childOpts.debug;
+  debug('--debug -> --inspect');
+} else if (childOpts['debug-brk']) {
+  nodeOpts['inspect-brk'] = childOpts['debug-brk'];
+  childOpts.timeout = false;
+  delete childOpts['debug-brk'];
+  debug('--debug-brk -> --inspect-brk');
+}
+
+// historical
+if (nodeOpts.gc) {
+  deprecate(
+    '"-gc" is deprecated and will be removed from a future version of Mocha.  Use "--gc-global" instead.'
+  );
+  nodeOpts['gc-global'] = nodeOpts.gc;
+  delete nodeOpts.gc;
+}
+
+// Native debugger handling
+// see https://nodejs.org/api/debugger.html#debugger_debugger
+// look for 'debug' or 'inspect' that would launch this debugger,
+// remove it from Mocha's opts and prepend it to Node's opts.
+// also coerce depending on Node.js version.
+if (/^(debug|inspect)$/.test(childOpts._[0])) {
+  childOpts.timeout = false;
+  childOpts._.shift();
+  // don't conflict with inspector
+  delete nodeOpts['debug'];
+  delete nodeOpts['inspect'];
+  delete nodeOpts['debug-brk'];
+  delete nodeOpts['inspect-brk'];
+  nodeOpts._ = [
+    parseInt(
+      process.version
+        .slice(1)
+        .split('.')
+        .shift(),
+      10
+    ) >= 8
+      ? 'inspect'
+      : 'debug'
+  ];
+}
+
+const args = [].concat(
+  unparse(nodeOpts),
+  mochaPath,
+  unparse(childOpts, {alias: aliases})
+);
+
+debug(`exec ${process.execPath} w/ args:`, args);
+
 const proc = spawn(process.execPath, args, {
   stdio: 'inherit'
 });
+
 proc.on('exit', (code, signal) => {
   process.on('exit', () => {
     if (signal) {

package/bin/options.js

@@ -1,43 +1,10 @@
 'use strict';
 
-/**
- * Dependencies.
+/*
+ * This module is deprecated and will be removed in a future version of Mocha.
+ * @deprecated Deprecated in v6.0.0; source moved into {@link module:lib/cli/options lib/cli/options module}.
+ * @module
+ * @exports module:lib/cli/options
  */
 
-const fs = require('fs');
-
-/**
- * Export `getOptions`.
- */
-
-module.exports = getOptions;
-
-/**
- * Get options.
- */
-
-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];
-
-  try {
-    const opts = fs.readFileSync(optsPath, 'utf8')
-      .replace(/\\\s/g, '%20')
-      .split(/\s/)
-      .filter(Boolean)
-      .map(value => value.replace(/%20/g, ' '));
-
-    process.argv = process.argv
-      .slice(0, 2)
-      .concat(opts.concat(process.argv.slice(2)));
-  } catch (err) {
-    // ignore
-  }
-
-  process.env.LOADED_MOCHA_OPTS = true;
-}
+module.exports = require('../lib/cli/options');

package/browser-entry.js

@@ -7,7 +7,7 @@
  * Shim process.stdout.
  */
 
-process.stdout = require('browser-stdout')({level: false});
+process.stdout = require('browser-stdout')({label: false});
 
 var Mocha = require('./lib/mocha');
 
@@ -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/growl.js

@@ -1,5 +1,167 @@
 'use strict';
 
-// just stub out growl
+/**
+ * Web Notifications module.
+ * @module Growl
+ */
 
-module.exports = require('../utils').noop;
+/**
+ * Save timer references to avoid Sinon interfering (see GH-237).
+ */
+var Date = global.Date;
+var setTimeout = global.setTimeout;
+
+/**
+ * Checks if browser notification support exists.
+ *
+ * @public
+ * @see {@link https://caniuse.com/#feat=notifications|Browser support (notifications)}
+ * @see {@link https://caniuse.com/#feat=promises|Browser support (promises)}
+ * @see {@link Mocha#growl}
+ * @see {@link Mocha#isGrowlCapable}
+ * @return {boolean} whether browser notification support exists
+ */
+exports.isCapable = function() {
+  var hasNotificationSupport = 'Notification' in window;
+  var hasPromiseSupport = typeof Promise === 'function';
+  return process.browser && hasNotificationSupport && hasPromiseSupport;
+};
+
+/**
+ * Implements browser notifications as a pseudo-reporter.
+ *
+ * @public
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/notification|Notification API}
+ * @see {@link https://developers.google.com/web/fundamentals/push-notifications/display-a-notification|Displaying a Notification}
+ * @see {@link Growl#isPermitted}
+ * @see {@link Mocha#_growl}
+ * @param {Runner} runner - Runner instance.
+ */
+exports.notify = function(runner) {
+  var promise = isPermitted();
+
+  /**
+   * Attempt notification.
+   */
+  var sendNotification = function() {
+    // If user hasn't responded yet... "No notification for you!" (Seinfeld)
+    Promise.race([promise, Promise.resolve(undefined)])
+      .then(canNotify)
+      .then(function() {
+        display(runner);
+      })
+      .catch(notPermitted);
+  };
+
+  runner.once('end', sendNotification);
+};
+
+/**
+ * Checks if browser notification is permitted by user.
+ *
+ * @private
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Notification/permission|Notification.permission}
+ * @see {@link Mocha#growl}
+ * @see {@link Mocha#isGrowlPermitted}
+ * @returns {Promise<boolean>} promise determining if browser notification
+ *     permissible when fulfilled.
+ */
+function isPermitted() {
+  var permitted = {
+    granted: function allow() {
+      return Promise.resolve(true);
+    },
+    denied: function deny() {
+      return Promise.resolve(false);
+    },
+    default: function ask() {
+      return Notification.requestPermission().then(function(permission) {
+        return permission === 'granted';
+      });
+    }
+  };
+
+  return permitted[Notification.permission]();
+}
+
+/**
+ * @summary
+ * Determines if notification should proceed.
+ *
+ * @description
+ * Notification shall <strong>not</strong> proceed unless `value` is true.
+ *
+ * `value` will equal one of:
+ * <ul>
+ *   <li><code>true</code> (from `isPermitted`)</li>
+ *   <li><code>false</code> (from `isPermitted`)</li>
+ *   <li><code>undefined</code> (from `Promise.race`)</li>
+ * </ul>
+ *
+ * @private
+ * @param {boolean|undefined} value - Determines if notification permissible.
+ * @returns {Promise<undefined>} Notification can proceed
+ */
+function canNotify(value) {
+  if (!value) {
+    var why = value === false ? 'blocked' : 'unacknowledged';
+    var reason = 'not permitted by user (' + why + ')';
+    return Promise.reject(new Error(reason));
+  }
+  return Promise.resolve();
+}
+
+/**
+ * Displays the notification.
+ *
+ * @private
+ * @param {Runner} runner - Runner instance.
+ */
+function display(runner) {
+  var stats = runner.stats;
+  var symbol = {
+    cross: '\u274C',
+    tick: '\u2705'
+  };
+  var logo = require('../../package').notifyLogo;
+  var _message;
+  var message;
+  var title;
+
+  if (stats.failures) {
+    _message = stats.failures + ' of ' + runner.total + ' 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
+  var options = {
+    badge: logo,
+    body: message,
+    dir: 'ltr',
+    icon: logo,
+    lang: 'en-US',
+    name: 'mocha',
+    requireInteraction: false,
+    timestamp: Date.now()
+  };
+  var notification = new Notification(title, options);
+
+  // Autoclose after brief delay (makes various browsers act same)
+  var FORCE_DURATION = 4000;
+  setTimeout(notification.close.bind(notification), FORCE_DURATION);
+}
+
+/**
+ * As notifications are tangential to our purpose, just log the error.
+ *
+ * @private
+ * @param {Error} err - Why notification didn't happen.
+ */
+function notPermitted(err) {
+  console.error('notification error:', err.message);
+}

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);
@@ -19,11 +19,11 @@ function Progress () {
 /**
  * Set progress size to `size`.
  *
- * @api public
+ * @public
  * @param {number} size
  * @return {Progress} Progress instance.
  */
-Progress.prototype.size = function (size) {
+Progress.prototype.size = function(size) {
   this._size = size;
   return this;
 };
@@ -31,11 +31,11 @@ Progress.prototype.size = function (size) {
 /**
  * Set text to `text`.
  *
- * @api public
+ * @public
  * @param {string} text
  * @return {Progress} Progress instance.
  */
-Progress.prototype.text = function (text) {
+Progress.prototype.text = function(text) {
   this._text = text;
   return this;
 };
@@ -43,11 +43,11 @@ Progress.prototype.text = function (text) {
 /**
  * Set font size to `size`.
  *
- * @api public
+ * @public
  * @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/cli/cli.js

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * This is where we finally parse and handle arguments passed to the `mocha` executable.
+ * Option parsing is handled by {@link https://npm.im/yargs yargs}.
+ * If executed via `node`, this module will run {@linkcode module:lib/cli/cli.main main()}.
+ *
+ * @private
+ * @module
+ */
+
+const debug = require('debug')('mocha:cli:cli');
+const symbols = require('log-symbols');
+const yargs = require('yargs');
+const path = require('path');
+const {loadOptions} = require('./options');
+const commands = require('./commands');
+const ansi = require('ansi-colors');
+const {repository, homepage, version, gitter} = require('../../package.json');
+
+/**
+ * - Accepts an `Array` of arguments
+ * - Modifies {@link https://nodejs.org/api/modules.html#modules_module_paths Node.js' search path} for easy loading of consumer modules
+ * - Sets {@linkcode https://nodejs.org/api/errors.html#errors_error_stacktracelimit Error.stackTraceLimit} to `Infinity`
+ * @summary Mocha's main entry point from the command-line.
+ * @param {string[]} argv - Array of arguments to parse, or by default the lovely `process.argv.slice(2)`
+ */
+exports.main = (argv = process.argv.slice(2)) => {
+  debug('entered main with raw args', argv);
+  // ensure we can require() from current working directory
+  module.paths.push(process.cwd(), path.resolve('node_modules'));
+
+  Error.stackTraceLimit = Infinity; // configurable via --stack-trace-limit?
+
+  yargs
+    .scriptName('mocha')
+    .command(commands.run)
+    .command(commands.init)
+    .updateStrings({
+      'Positionals:': 'Positional Arguments',
+      'Options:': 'Other Options',
+      'Commands:': 'Commands'
+    })
+    .fail((msg, err, yargs) => {
+      debug(err);
+      yargs.showHelp();
+      console.error(`\n${symbols.error} ${ansi.red('ERROR:')} ${msg}`);
+      process.exit(1);
+    })
+    .help('help', 'Show usage information & exit')
+    .alias('help', 'h')
+    .version('version', 'Show version number & exit', version)
+    .alias('version', 'V')
+    .wrap(process.stdout.columns ? Math.min(process.stdout.columns, 80) : 80)
+    .epilog(
+      `Mocha Resources
+    Chat: ${ansi.magenta(gitter)}
+  GitHub: ${ansi.blue(repository.url)}
+    Docs: ${ansi.yellow(homepage)}
+      `
+    )
+    .parse(argv, loadOptions(argv));
+};
+
+// allow direct execution
+if (require.main === module) {
+  exports.main();
+}

package/lib/cli/commands.js

@@ -0,0 +1,13 @@
+'use strict';
+
+/**
+ * Exports Yargs commands
+ * @see https://git.io/fpJ0G
+ * @private
+ * @module
+ */
+
+exports.init = require('./init');
+
+// default command
+exports.run = require('./run');