mocha-compat 3.6.4 → 10.8.2

package/lib/reporters/json-stream.js

@@ -1,63 +1,92 @@
 'use strict';
-
+/**
+ * @module JSONStream
+ */
 /**
  * Module dependencies.
  */
 
 var Base = require('./base');
-var JSON = require('json3');
+var constants = require('../runner').constants;
+var EVENT_TEST_PASS = constants.EVENT_TEST_PASS;
+var EVENT_TEST_FAIL = constants.EVENT_TEST_FAIL;
+var EVENT_RUN_BEGIN = constants.EVENT_RUN_BEGIN;
+var EVENT_RUN_END = constants.EVENT_RUN_END;
 
 /**
- * Expose `List`.
+ * Expose `JSONStream`.
  */
 
-exports = module.exports = List;
+exports = module.exports = JSONStream;
 
 /**
- * Initialize a new `List` test reporter.
+ * Constructs a new `JSONStream` reporter instance.
  *
- * @api public
- * @param {Runner} runner
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
+ * @param {Runner} runner - Instance triggers reporter actions.
+ * @param {Object} [options] - runner options
  */
-function List (runner) {
-  Base.call(this, runner);
+function JSONStream(runner, options) {
+  Base.call(this, runner, options);
 
   var self = this;
   var total = runner.total;
 
-  runner.on('start', function () {
-    console.log(JSON.stringify(['start', { total: total }]));
+  runner.once(EVENT_RUN_BEGIN, function () {
+    writeEvent(['start', {total}]);
   });
 
-  runner.on('pass', function (test) {
-    console.log(JSON.stringify(['pass', clean(test)]));
+  runner.on(EVENT_TEST_PASS, function (test) {
+    writeEvent(['pass', clean(test)]);
   });
 
-  runner.on('fail', function (test, err) {
+  runner.on(EVENT_TEST_FAIL, function (test, err) {
     test = clean(test);
     test.err = err.message;
     test.stack = err.stack || null;
-    console.log(JSON.stringify(['fail', test]));
+    writeEvent(['fail', test]);
   });
 
-  runner.on('end', function () {
-    process.stdout.write(JSON.stringify(['end', self.stats]));
+  runner.once(EVENT_RUN_END, function () {
+    writeEvent(['end', self.stats]);
   });
 }
 
 /**
- * Return a plain-object representation of `test`
- * free of cyclic properties etc.
+ * Mocha event to be written to the output stream.
+ * @typedef {Array} JSONStream~MochaEvent
+ */
+
+/**
+ * Writes Mocha event to reporter output stream.
+ *
+ * @private
+ * @param {JSONStream~MochaEvent} event - Mocha event to be output.
+ */
+function writeEvent(event) {
+  process.stdout.write(JSON.stringify(event) + '\n');
+}
+
+/**
+ * Returns an object literal representation of `test`
+ * free of cyclic properties, etc.
  *
- * @api private
- * @param {Object} test
- * @return {Object}
+ * @private
+ * @param {Test} test - Instance used as data source.
+ * @return {Object} object containing pared-down test instance data
  */
-function clean (test) {
+function clean(test) {
   return {
     title: test.title,
     fullTitle: test.fullTitle(),
+    file: test.file,
     duration: test.duration,
-    currentRetry: test.currentRetry()
+    currentRetry: test.currentRetry(),
+    speed: test.speed
   };
 }
+
+JSONStream.description = 'newline delimited JSON events';

package/lib/reporters/json.js

@@ -1,10 +1,22 @@
 'use strict';
-
+/**
+ * @module JSON
+ */
 /**
  * Module dependencies.
  */
 
 var Base = require('./base');
+var fs = require('fs');
+var path = require('path');
+const createUnsupportedError = require('../errors').createUnsupportedError;
+const utils = require('../utils');
+var constants = require('../runner').constants;
+var EVENT_TEST_PASS = constants.EVENT_TEST_PASS;
+var EVENT_TEST_PENDING = constants.EVENT_TEST_PENDING;
+var EVENT_TEST_FAIL = constants.EVENT_TEST_FAIL;
+var EVENT_TEST_END = constants.EVENT_TEST_END;
+var EVENT_RUN_END = constants.EVENT_RUN_END;
 
 /**
  * Expose `JSON`.
@@ -13,37 +25,49 @@ var Base = require('./base');
 exports = module.exports = JSONReporter;
 
 /**
- * Initialize a new `JSON` reporter.
+ * Constructs a new `JSON` reporter instance.
  *
- * @api public
- * @param {Runner} runner
+ * @public
+ * @class JSON
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
+ * @param {Runner} runner - Instance triggers reporter actions.
+ * @param {Object} [options] - runner options
  */
-function JSONReporter (runner) {
-  Base.call(this, runner);
+function JSONReporter(runner, options = {}) {
+  Base.call(this, runner, options);
 
   var self = this;
   var tests = [];
   var pending = [];
   var failures = [];
   var passes = [];
+  var output;
+
+  if (options.reporterOption && options.reporterOption.output) {
+    if (utils.isBrowser()) {
+      throw createUnsupportedError('file output not supported in browser');
+    }
+    output = options.reporterOption.output;
+  }
 
-  runner.on('test end', function (test) {
+  runner.on(EVENT_TEST_END, function (test) {
     tests.push(test);
   });
 
-  runner.on('pass', function (test) {
+  runner.on(EVENT_TEST_PASS, function (test) {
     passes.push(test);
   });
 
-  runner.on('fail', function (test) {
+  runner.on(EVENT_TEST_FAIL, function (test) {
     failures.push(test);
   });
 
-  runner.on('pending', function (test) {
+  runner.on(EVENT_TEST_PENDING, function (test) {
     pending.push(test);
   });
 
-  runner.on('end', function () {
+  runner.once(EVENT_RUN_END, function () {
     var obj = {
       stats: self.stats,
       tests: tests.map(clean),
@@ -54,7 +78,20 @@ function JSONReporter (runner) {
 
     runner.testResults = obj;
 
-    process.stdout.write(JSON.stringify(obj, null, 2));
+    var json = JSON.stringify(obj, null, 2);
+    if (output) {
+      try {
+        fs.mkdirSync(path.dirname(output), {recursive: true});
+        fs.writeFileSync(output, json);
+      } catch (err) {
+        console.error(
+          `${Base.symbols.err} [mocha] writing output to "${output}" failed: ${err.message}\n`
+        );
+        process.stdout.write(json);
+      }
+    } else {
+      process.stdout.write(json);
+    }
   });
 }
 
@@ -62,31 +99,64 @@ function JSONReporter (runner) {
  * Return a plain-object representation of `test`
  * free of cyclic properties etc.
  *
- * @api private
+ * @private
  * @param {Object} test
  * @return {Object}
  */
-function clean (test) {
+function clean(test) {
+  var err = test.err || {};
+  if (err instanceof Error) {
+    err = errorJSON(err);
+  }
+
   return {
     title: test.title,
     fullTitle: test.fullTitle(),
+    file: test.file,
     duration: test.duration,
     currentRetry: test.currentRetry(),
-    err: errorJSON(test.err || {})
+    speed: test.speed,
+    err: cleanCycles(err)
   };
 }
 
 /**
- * Transform `error` into a JSON object.
+ * Replaces any circular references inside `obj` with '[object Object]'
  *
- * @api private
+ * @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.
+ *
+ * @private
  * @param {Error} err
  * @return {Object}
  */
-function errorJSON (err) {
+function errorJSON(err) {
   var res = {};
   Object.getOwnPropertyNames(err).forEach(function (key) {
     res[key] = err[key];
   }, err);
   return res;
 }
+
+JSONReporter.description = 'single JSON object';

package/lib/reporters/landing.js

@@ -1,11 +1,19 @@
 'use strict';
-
+/**
+ * @module Landing
+ */
 /**
  * Module dependencies.
  */
 
 var Base = require('./base');
 var inherits = require('../utils').inherits;
+var constants = require('../runner').constants;
+var EVENT_RUN_BEGIN = constants.EVENT_RUN_BEGIN;
+var EVENT_RUN_END = constants.EVENT_RUN_END;
+var EVENT_TEST_END = constants.EVENT_TEST_END;
+var STATE_FAILED = require('../runnable').constants.STATE_FAILED;
+
 var cursor = Base.cursor;
 var color = Base.color;
 
@@ -34,38 +42,42 @@ Base.colors['plane crash'] = 31;
 Base.colors.runway = 90;
 
 /**
- * Initialize a new `Landing` reporter.
+ * Constructs a new `Landing` reporter instance.
  *
- * @api public
- * @param {Runner} runner
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
+ * @param {Runner} runner - Instance triggers reporter actions.
+ * @param {Object} [options] - runner options
  */
-function Landing (runner) {
-  Base.call(this, runner);
+function Landing(runner, options) {
+  Base.call(this, runner, options);
 
   var self = this;
-  var width = Base.window.width * 0.75 | 0;
-  var total = runner.total;
+  var width = (Base.window.width * 0.75) | 0;
   var stream = process.stdout;
+
   var plane = color('plane', '✈');
   var crashed = -1;
   var n = 0;
+  var total = 0;
 
-  function runway () {
+  function runway() {
     var buf = Array(width).join('-');
     return '  ' + color('runway', buf);
   }
 
-  runner.on('start', function () {
+  runner.on(EVENT_RUN_BEGIN, function () {
     stream.write('\n\n\n  ');
     cursor.hide();
   });
 
-  runner.on('test end', function (test) {
+  runner.on(EVENT_TEST_END, function (test) {
     // check if the plane crashed
-    var col = crashed === -1 ? width * ++n / total | 0 : crashed;
-
+    var col = crashed === -1 ? ((width * ++n) / ++total) | 0 : crashed;
     // show the crash
-    if (test.state === 'failed') {
+    if (test.state === STATE_FAILED) {
       plane = color('plane crash', '✈');
       crashed = col;
     }
@@ -81,14 +93,24 @@ function Landing (runner) {
     stream.write('\u001b[0m');
   });
 
-  runner.on('end', function () {
+  runner.once(EVENT_RUN_END, function () {
     cursor.show();
-    console.log();
+    process.stdout.write('\n');
     self.epilogue();
   });
+
+  // if cursor is hidden when we ctrl-C, then it will remain hidden unless...
+  process.once('SIGINT', function () {
+    cursor.show();
+    process.nextTick(function () {
+      process.kill(process.pid, 'SIGINT');
+    });
+  });
 }
 
 /**
  * Inherit from `Base.prototype`.
  */
 inherits(Landing, Base);
+
+Landing.description = 'Unicode landing strip';

package/lib/reporters/list.js

@@ -1,11 +1,20 @@
 'use strict';
-
+/**
+ * @module List
+ */
 /**
  * Module dependencies.
  */
 
 var Base = require('./base');
 var inherits = require('../utils').inherits;
+var constants = require('../runner').constants;
+var EVENT_RUN_BEGIN = constants.EVENT_RUN_BEGIN;
+var EVENT_RUN_END = constants.EVENT_RUN_END;
+var EVENT_TEST_BEGIN = constants.EVENT_TEST_BEGIN;
+var EVENT_TEST_FAIL = constants.EVENT_TEST_FAIL;
+var EVENT_TEST_PASS = constants.EVENT_TEST_PASS;
+var EVENT_TEST_PENDING = constants.EVENT_TEST_PENDING;
 var color = Base.color;
 var cursor = Base.cursor;
 
@@ -16,48 +25,54 @@ var cursor = Base.cursor;
 exports = module.exports = List;
 
 /**
- * Initialize a new `List` test reporter.
+ * Constructs a new `List` reporter instance.
  *
- * @api public
- * @param {Runner} runner
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
+ * @param {Runner} runner - Instance triggers reporter actions.
+ * @param {Object} [options] - runner options
  */
-function List (runner) {
-  Base.call(this, runner);
+function List(runner, options) {
+  Base.call(this, runner, options);
 
   var self = this;
   var n = 0;
 
-  runner.on('start', function () {
-    console.log();
+  runner.on(EVENT_RUN_BEGIN, function () {
+    Base.consoleLog();
   });
 
-  runner.on('test', function (test) {
+  runner.on(EVENT_TEST_BEGIN, function (test) {
     process.stdout.write(color('pass', '    ' + test.fullTitle() + ': '));
   });
 
-  runner.on('pending', function (test) {
-    var fmt = color('checkmark', '  -') +
-      color('pending', ' %s');
-    console.log(fmt, test.fullTitle());
+  runner.on(EVENT_TEST_PENDING, function (test) {
+    var fmt = color('checkmark', '  -') + color('pending', ' %s');
+    Base.consoleLog(fmt, test.fullTitle());
   });
 
-  runner.on('pass', function (test) {
-    var fmt = color('checkmark', '  ' + Base.symbols.ok) +
+  runner.on(EVENT_TEST_PASS, function (test) {
+    var fmt =
+      color('checkmark', '  ' + Base.symbols.ok) +
       color('pass', ' %s: ') +
       color(test.speed, '%dms');
     cursor.CR();
-    console.log(fmt, test.fullTitle(), test.duration);
+    Base.consoleLog(fmt, test.fullTitle(), test.duration);
   });
 
-  runner.on('fail', function (test) {
+  runner.on(EVENT_TEST_FAIL, function (test) {
     cursor.CR();
-    console.log(color('fail', '  %d) %s'), ++n, test.fullTitle());
+    Base.consoleLog(color('fail', '  %d) %s'), ++n, test.fullTitle());
   });
 
-  runner.on('end', self.epilogue.bind(self));
+  runner.once(EVENT_RUN_END, self.epilogue.bind(self));
 }
 
 /**
  * Inherit from `Base.prototype`.
  */
 inherits(List, Base);
+
+List.description = 'like "spec" reporter but flat';

package/lib/reporters/markdown.js

@@ -1,11 +1,18 @@
 'use strict';
-
+/**
+ * @module Markdown
+ */
 /**
  * Module dependencies.
  */
 
 var Base = require('./base');
 var utils = require('../utils');
+var constants = require('../runner').constants;
+var EVENT_RUN_END = constants.EVENT_RUN_END;
+var EVENT_SUITE_BEGIN = constants.EVENT_SUITE_BEGIN;
+var EVENT_SUITE_END = constants.EVENT_SUITE_END;
+var EVENT_TEST_PASS = constants.EVENT_TEST_PASS;
 
 /**
  * Constants
@@ -20,26 +27,30 @@ var SUITE_PREFIX = '$';
 exports = module.exports = Markdown;
 
 /**
- * Initialize a new `Markdown` reporter.
+ * Constructs a new `Markdown` reporter instance.
  *
- * @api public
- * @param {Runner} runner
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
+ * @param {Runner} runner - Instance triggers reporter actions.
+ * @param {Object} [options] - runner options
  */
-function Markdown (runner) {
-  Base.call(this, runner);
+function Markdown(runner, options) {
+  Base.call(this, runner, options);
 
   var level = 0;
   var buf = '';
 
-  function title (str) {
+  function title(str) {
     return Array(level).join('#') + ' ' + str;
   }
 
-  function mapTOC (suite, obj) {
+  function mapTOC(suite, obj) {
     var ret = obj;
     var key = SUITE_PREFIX + suite.title;
 
-    obj = obj[key] = obj[key] || { suite: suite };
+    obj = obj[key] = obj[key] || {suite};
     suite.suites.forEach(function (suite) {
       mapTOC(suite, obj);
     });
@@ -47,7 +58,7 @@ function Markdown (runner) {
     return ret;
   }
 
-  function stringifyTOC (obj, level) {
+  function stringifyTOC(obj, level) {
     ++level;
     var buf = '';
     var link;
@@ -65,25 +76,25 @@ function Markdown (runner) {
     return buf;
   }
 
-  function generateTOC (suite) {
+  function generateTOC(suite) {
     var obj = mapTOC(suite, {});
     return stringifyTOC(obj, 0);
   }
 
   generateTOC(runner.suite);
 
-  runner.on('suite', function (suite) {
+  runner.on(EVENT_SUITE_BEGIN, function (suite) {
     ++level;
     var slug = utils.slug(suite.fullTitle());
     buf += '<a name="' + slug + '"></a>' + '\n';
     buf += title(suite.title) + '\n';
   });
 
-  runner.on('suite end', function () {
+  runner.on(EVENT_SUITE_END, function () {
     --level;
   });
 
-  runner.on('pass', function (test) {
+  runner.on(EVENT_TEST_PASS, function (test) {
     var code = utils.clean(test.body);
     buf += test.title + '.\n';
     buf += '\n```js\n';
@@ -91,9 +102,11 @@ function Markdown (runner) {
     buf += '```\n\n';
   });
 
-  runner.on('end', function () {
+  runner.once(EVENT_RUN_END, function () {
     process.stdout.write('# TOC\n');
     process.stdout.write(generateTOC(runner.suite));
     process.stdout.write(buf);
   });
 }
+
+Markdown.description = 'GitHub Flavored Markdown';

package/lib/reporters/min.js

@@ -1,11 +1,16 @@
 'use strict';
-
+/**
+ * @module Min
+ */
 /**
  * Module dependencies.
  */
 
 var Base = require('./base');
 var inherits = require('../utils').inherits;
+var constants = require('../runner').constants;
+var EVENT_RUN_END = constants.EVENT_RUN_END;
+var EVENT_RUN_BEGIN = constants.EVENT_RUN_BEGIN;
 
 /**
  * Expose `Min`.
@@ -14,25 +19,34 @@ var inherits = require('../utils').inherits;
 exports = module.exports = Min;
 
 /**
- * Initialize a new `Min` minimal test reporter (best used with --watch).
+ * Constructs a new `Min` reporter instance.
  *
- * @api public
- * @param {Runner} runner
+ * @description
+ * This minimal test reporter is best used with '--watch'.
+ *
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
+ * @param {Runner} runner - Instance triggers reporter actions.
+ * @param {Object} [options] - runner options
  */
-function Min (runner) {
-  Base.call(this, runner);
+function Min(runner, options) {
+  Base.call(this, runner, options);
 
-  runner.on('start', function () {
+  runner.on(EVENT_RUN_BEGIN, function () {
     // clear screen
     process.stdout.write('\u001b[2J');
     // set cursor position
     process.stdout.write('\u001b[1;3H');
   });
 
-  runner.on('end', this.epilogue.bind(this));
+  runner.once(EVENT_RUN_END, this.epilogue.bind(this));
 }
 
 /**
  * Inherit from `Base.prototype`.
  */
 inherits(Min, Base);
+
+Min.description = 'essentially just a summary';