mocha 8.3.0 → 9.0.0

package/lib/mocha.js

@@ -30,7 +30,6 @@ const {
   EVENT_FILE_POST_REQUIRE,
   EVENT_FILE_REQUIRE
 } = Suite.constants;
-var sQuote = utils.sQuote;
 var debug = require('debug')('mocha:mocha');
 
 exports = module.exports = Mocha;
@@ -96,6 +95,61 @@ exports.Suite = Suite;
 exports.Hook = require('./hook');
 exports.Test = require('./test');
 
+let currentContext;
+exports.afterEach = function(...args) {
+  return (currentContext.afterEach || currentContext.teardown).apply(
+    this,
+    args
+  );
+};
+exports.after = function(...args) {
+  return (currentContext.after || currentContext.suiteTeardown).apply(
+    this,
+    args
+  );
+};
+exports.beforeEach = function(...args) {
+  return (currentContext.beforeEach || currentContext.setup).apply(this, args);
+};
+exports.before = function(...args) {
+  return (currentContext.before || currentContext.suiteSetup).apply(this, args);
+};
+exports.describe = function(...args) {
+  return (currentContext.describe || currentContext.suite).apply(this, args);
+};
+exports.describe.only = function(...args) {
+  return (currentContext.describe || currentContext.suite).only.apply(
+    this,
+    args
+  );
+};
+exports.describe.skip = function(...args) {
+  return (currentContext.describe || currentContext.suite).skip.apply(
+    this,
+    args
+  );
+};
+exports.it = function(...args) {
+  return (currentContext.it || currentContext.test).apply(this, args);
+};
+exports.it.only = function(...args) {
+  return (currentContext.it || currentContext.test).only.apply(this, args);
+};
+exports.it.skip = function(...args) {
+  return (currentContext.it || currentContext.test).skip.apply(this, args);
+};
+exports.xdescribe = exports.describe.skip;
+exports.xit = exports.it.skip;
+exports.setup = exports.beforeEach;
+exports.suiteSetup = exports.before;
+exports.suiteTeardown = exports.after;
+exports.suite = exports.describe;
+exports.teardown = exports.afterEach;
+exports.test = exports.it;
+exports.run = function(...args) {
+  return currentContext.run.apply(this, args);
+};
+
 /**
  * Constructs a new Mocha instance with `options`.
  *
@@ -109,6 +163,7 @@ exports.Test = require('./test');
  * @param {boolean} [options.color] - Color TTY output from reporter?
  * @param {boolean} [options.delay] - Delay root suite execution?
  * @param {boolean} [options.diff] - Show diff on failure?
+ * @param {boolean} [options.dryRun] - Report tests without running them?
  * @param {string} [options.fgrep] - Test filter given string.
  * @param {boolean} [options.forbidOnly] - Tests marked `only` fail the suite?
  * @param {boolean} [options.forbidPending] - Pending tests fail the suite?
@@ -125,10 +180,10 @@ exports.Test = require('./test');
  * @param {number} [options.slow] - Slow threshold value.
  * @param {number|string} [options.timeout] - Timeout threshold value.
  * @param {string} [options.ui] - Interface name.
- * @param {boolean} [options.parallel] - Run jobs in parallel
- * @param {number} [options.jobs] - Max number of worker processes for parallel runs
- * @param {MochaRootHookObject} [options.rootHooks] - Hooks to bootstrap the root
- * suite with
+ * @param {boolean} [options.parallel] - Run jobs in parallel.
+ * @param {number} [options.jobs] - Max number of worker processes for parallel runs.
+ * @param {MochaRootHookObject} [options.rootHooks] - Hooks to bootstrap the root suite with.
+ * @param {string[]} [options.require] - Pathname of `rootHooks` plugin for parallel runs.
  * @param {boolean} [options.isWorker] - Should be `true` if `Mocha` process is running in a worker process.
  */
 function Mocha(options = {}) {
@@ -145,7 +200,7 @@ function Mocha(options = {}) {
     .ui(options.ui)
     .reporter(
       options.reporter,
-      options.reporterOption || options.reporterOptions // reporterOptions was previously the only way to specify options to reporter
+      options.reporterOption || options.reporterOptions // for backwards compability
     )
     .slow(options.slow)
     .global(options.global);
@@ -167,6 +222,7 @@ function Mocha(options = {}) {
     'color',
     'delay',
     'diff',
+    'dryRun',
     'forbidOnly',
     'forbidPending',
     'fullTrace',
@@ -291,23 +347,19 @@ Mocha.prototype.reporter = function(reporterName, reporterOptions) {
             reporter = require(path.resolve(utils.cwd(), reporterName));
           } catch (_err) {
             _err.code === 'MODULE_NOT_FOUND'
-              ? warn(sQuote(reporterName) + ' reporter not found')
+              ? warn(`'${reporterName}' reporter not found`)
               : warn(
-                  sQuote(reporterName) +
-                    ' reporter blew up with error:\n' +
-                    err.stack
+                  `'${reporterName}' reporter blew up with error:\n ${err.stack}`
                 );
           }
         } else {
-          warn(
-            sQuote(reporterName) + ' reporter blew up with error:\n' + err.stack
-          );
+          warn(`'${reporterName}' reporter blew up with error:\n ${err.stack}`);
         }
       }
     }
     if (!reporter) {
       throw createInvalidReporterError(
-        'invalid reporter ' + sQuote(reporterName),
+        `invalid reporter '${reporterName}'`,
         reporterName
       );
     }
@@ -341,30 +393,14 @@ Mocha.prototype.ui = function(ui) {
       try {
         bindInterface = require(ui);
       } catch (err) {
-        throw createInvalidInterfaceError(
-          'invalid interface ' + sQuote(ui),
-          ui
-        );
+        throw createInvalidInterfaceError(`invalid interface '${ui}'`, ui);
       }
     }
   }
   bindInterface(this.suite);
 
   this.suite.on(EVENT_FILE_PRE_REQUIRE, function(context) {
-    exports.afterEach = context.afterEach || context.teardown;
-    exports.after = context.after || context.suiteTeardown;
-    exports.beforeEach = context.beforeEach || context.setup;
-    exports.before = context.before || context.suiteSetup;
-    exports.describe = context.describe || context.suite;
-    exports.it = context.it || context.test;
-    exports.xit = context.xit || (context.test && context.test.skip);
-    exports.setup = context.setup || context.beforeEach;
-    exports.suiteSetup = context.suiteSetup || context.before;
-    exports.suiteTeardown = context.suiteTeardown || context.after;
-    exports.suite = context.suite || context.describe;
-    exports.teardown = context.teardown || context.afterEach;
-    exports.test = context.test || context.it;
-    exports.run = context.run;
+    currentContext = context;
   });
 
   return this;
@@ -742,6 +778,20 @@ Mocha.prototype.diff = function(diff) {
   return this;
 };
 
+/**
+ * Enables or disables running tests in dry-run mode.
+ *
+ * @public
+ * @see [CLI option](../#-dry-run)
+ * @param {boolean} [dryRun=true] - Whether to activate dry-run mode.
+ * @return {Mocha} this
+ * @chainable
+ */
+Mocha.prototype.dryRun = function(dryRun) {
+  this.options.dryRun = dryRun !== false;
+  return this;
+};
+
 /**
  * @summary
  * Sets timeout threshold value.
@@ -974,6 +1024,7 @@ Mocha.prototype.run = function(fn) {
   options.files = this.files;
   const runner = new this._runnerClass(suite, {
     delay: options.delay,
+    dryRun: options.dryRun,
     cleanReferencesAfterRun: this._cleanReferencesAfterRun
   });
   createStatsCollector(runner);
@@ -1299,7 +1350,7 @@ Mocha.prototype.hasGlobalTeardownFixtures = function hasGlobalTeardownFixtures()
  * A (sync) function to assert a user-supplied plugin implementation is valid.
  *
  * Defined in a {@link PluginDefinition}.
- 
+
  * @callback PluginValidator
  * @param {*} value - Value to check
  * @this {PluginDefinition}

package/lib/reporters/base.js

@@ -10,6 +10,7 @@ var diff = require('diff');
 var milliseconds = require('ms');
 var utils = require('../utils');
 var supportsColor = require('supports-color');
+var symbols = require('log-symbols');
 var constants = require('../runner').constants;
 var EVENT_TEST_PASS = constants.EVENT_TEST_PASS;
 var EVENT_TEST_FAIL = constants.EVENT_TEST_FAIL;
@@ -88,20 +89,13 @@ exports.colors = {
  */
 
 exports.symbols = {
-  ok: '✓',
-  err: '✖',
-  dot: '․',
+  ok: symbols.success,
+  err: symbols.err,
+  dot: '.',
   comma: ',',
   bang: '!'
 };
 
-// With node.js on Windows: use symbols available in terminal default fonts
-if (process.platform === 'win32') {
-  exports.symbols.ok = '\u221A';
-  exports.symbols.err = '\u00D7';
-  exports.symbols.dot = '.';
-}
-
 /**
  * Color `str` with the given `type`,
  * allowing colors to be disabled,
@@ -196,6 +190,13 @@ function stringifyDiffObjs(err) {
  */
 var generateDiff = (exports.generateDiff = function(actual, expected) {
   try {
+    const diffSize = 2048;
+    if (actual.length > diffSize) {
+      actual = actual.substring(0, diffSize) + ' ... Lines skipped';
+    }
+    if (expected.length > diffSize) {
+      expected = expected.substring(0, diffSize) + ' ... Lines skipped';
+    }
     return exports.inlineDiffs
       ? inlineDiff(actual, expected)
       : unifiedDiff(actual, expected);
@@ -242,10 +243,10 @@ exports.list = function(failures) {
       err = test.err;
     }
     var message;
-    if (err.message && typeof err.message.toString === 'function') {
-      message = err.message + '';
-    } else if (typeof err.inspect === 'function') {
+    if (typeof err.inspect === 'function') {
       message = err.inspect() + '';
+    } else if (err.message && typeof err.message.toString === 'function') {
+      message = err.message + '';
     } else {
       message = '';
     }

package/lib/runner.js

@@ -4,7 +4,6 @@
  * Module dependencies.
  * @private
  */
-var util = require('util');
 var EventEmitter = require('events').EventEmitter;
 var Pending = require('./pending');
 var utils = require('./utils');
@@ -19,8 +18,6 @@ var EVENT_ROOT_SUITE_RUN = Suite.constants.EVENT_ROOT_SUITE_RUN;
 var STATE_FAILED = Runnable.constants.STATE_FAILED;
 var STATE_PASSED = Runnable.constants.STATE_PASSED;
 var STATE_PENDING = Runnable.constants.STATE_PENDING;
-var dQuote = utils.dQuote;
-var sQuote = utils.sQuote;
 var stackFilter = utils.stackTraceFilter();
 var stringify = utils.stringify;
 
@@ -138,8 +135,9 @@ class Runner extends EventEmitter {
    * @public
    * @class
    * @param {Suite} suite - Root suite
-   * @param {Object|boolean} [opts] - Options. If `boolean`, whether or not to delay execution of root suite until ready (for backwards compatibility).
+   * @param {Object|boolean} [opts] - Options. If `boolean` (deprecated), whether or not to delay execution of root suite until ready.
    * @param {boolean} [opts.delay] - Whether to delay execution of root suite until ready.
+   * @param {boolean} [opts.dryRun] - Whether to report tests without running them.
    * @param {boolean} [opts.cleanReferencesAfterRun] - Whether to clean references to test fns and hooks when a suite is done.
    */
   constructor(suite, opts) {
@@ -148,7 +146,10 @@ class Runner extends EventEmitter {
       opts = {};
     }
     if (typeof opts === 'boolean') {
-      // TODO: deprecate this
+      // TODO: remove this
+      require('./errors').deprecate(
+        '"Runner(suite: Suite, delay: boolean)" is deprecated. Use "Runner(suite: Suite, {delay: boolean})" instead.'
+      );
       this._delay = opts;
       opts = {};
     } else {
@@ -407,9 +408,8 @@ Runner.prototype.checkGlobals = function(test) {
   this._globals = this._globals.concat(leaks);
 
   if (leaks.length) {
-    var msg = 'global leak(s) detected: %s';
-    var error = new Error(util.format(msg, leaks.map(sQuote).join(', ')));
-    this.fail(test, error);
+    var msg = `global leak(s) detected: ${leaks.map(e => `'${e}'`).join(', ')}`;
+    this.fail(test, new Error(msg));
   }
 };
 
@@ -476,6 +476,8 @@ Runner.prototype.fail = function(test, err, force) {
  */
 
 Runner.prototype.hook = function(name, fn) {
+  if (this._opts.dryRun) return fn();
+
   var suite = this.suite;
   var hooks = suite.getHooks(name);
   var self = this;
@@ -554,8 +556,7 @@ Runner.prototype.hook = function(name, fn) {
     function setHookTitle(hook) {
       hook.originalTitle = hook.originalTitle || hook.title;
       if (hook.ctx && hook.ctx.currentTest) {
-        hook.title =
-          hook.originalTitle + ' for ' + dQuote(hook.ctx.currentTest.title);
+        hook.title = `${hook.originalTitle} for "${hook.ctx.currentTest.title}"`;
       } else {
         var parentTitle;
         if (hook.parent.title) {
@@ -563,7 +564,7 @@ Runner.prototype.hook = function(name, fn) {
         } else {
           parentTitle = hook.parent.root ? '{root}' : '';
         }
-        hook.title = hook.originalTitle + ' in ' + dQuote(parentTitle);
+        hook.title = `${hook.originalTitle} in "${parentTitle}"`;
       }
     }
   }
@@ -609,7 +610,7 @@ Runner.prototype.hooks = function(name, suites, fn) {
 };
 
 /**
- * Run hooks from the top level down.
+ * Run 'afterEach' hooks from bottom up.
  *
  * @param {String} name
  * @param {Function} fn
@@ -621,7 +622,7 @@ Runner.prototype.hookUp = function(name, fn) {
 };
 
 /**
- * Run hooks from the bottom up.
+ * Run 'beforeEach' hooks from top level down.
  *
  * @param {String} name
  * @param {Function} fn
@@ -656,6 +657,8 @@ Runner.prototype.parents = function() {
  * @private
  */
 Runner.prototype.runTest = function(fn) {
+  if (this._opts.dryRun) return fn();
+
   var self = this;
   var test = this.test;
 
@@ -701,7 +704,6 @@ Runner.prototype.runTests = function(suite, fn) {
     self.suite = after ? errSuite.parent : errSuite;
 
     if (self.suite) {
-      // call hookUp afterEach
       self.hookUp(HOOK_TYPE_AFTER_EACH, function(err2, errSuite2) {
         self.suite = orig;
         // some hooks may fail even now

package/lib/utils.js

@@ -13,7 +13,6 @@ const {nanoid} = require('nanoid/non-secure');
 var path = require('path');
 var util = require('util');
 var he = require('he');
-const errors = require('./errors');
 
 const MOCHA_ID_PROP_NAME = '__mocha_id__';
 
@@ -519,44 +518,6 @@ exports.clamp = function clamp(value, range) {
   return Math.min(Math.max(value, range[0]), range[1]);
 };
 
-/**
- * Single quote text by combining with undirectional ASCII quotation marks.
- *
- * @description
- * Provides a simple means of markup for quoting text to be used in output.
- * Use this to quote names of variables, methods, and packages.
- *
- * <samp>package 'foo' cannot be found</samp>
- *
- * @private
- * @param {string} str - Value to be quoted.
- * @returns {string} quoted value
- * @example
- * sQuote('n') // => 'n'
- */
-exports.sQuote = function(str) {
-  return "'" + str + "'";
-};
-
-/**
- * Double quote text by combining with undirectional ASCII quotation marks.
- *
- * @description
- * Provides a simple means of markup for quoting text to be used in output.
- * Use this to quote names of datatypes, classes, pathnames, and strings.
- *
- * <samp>argument 'value' must be "string" or "number"</samp>
- *
- * @private
- * @param {string} str - Value to be quoted.
- * @returns {string} quoted value
- * @example
- * dQuote('number') // => "number"
- */
-exports.dQuote = function(str) {
-  return '"' + str + '"';
-};
-
 /**
  * It's a noop.
  * @public
@@ -650,35 +611,6 @@ exports.isBrowser = function isBrowser() {
   return Boolean(process.browser);
 };
 
-/**
- * Lookup file names at the given `path`.
- *
- * @description
- * Filenames are returned in _traversal_ order by the OS/filesystem.
- * **Make no assumption that the names will be sorted in any fashion.**
- *
- * @public
- * @alias module:lib/cli.lookupFiles
- * @param {string} filepath - Base path to start searching from.
- * @param {string[]} [extensions=[]] - File extensions to look for.
- * @param {boolean} [recursive=false] - Whether to recurse into subdirectories.
- * @return {string[]} An array of paths.
- * @throws {Error} if no files match pattern.
- * @throws {TypeError} if `filepath` is directory and `extensions` not provided.
- * @deprecated Moved to {@link module:lib/cli.lookupFiles}
- */
-exports.lookupFiles = (...args) => {
-  if (exports.isBrowser()) {
-    throw errors.createUnsupportedError(
-      'lookupFiles() is only supported in Node.js!'
-    );
-  }
-  errors.deprecate(
-    '`lookupFiles()` in module `mocha/lib/utils` has moved to module `mocha/lib/cli` and will be removed in the next major revision of Mocha'
-  );
-  return require('./cli').lookupFiles(...args);
-};
-
 /*
  * Casts `value` to an array; useful for optionally accepting array parameters
  *