☕️ Classic, reliable, trusted test framework for Node.js and the browser
Added custom error objects including code (#3467)
Craig Taub0810441ca445
diff --git a/docs/index.md b/docs/index.mdindex 6a18e0bc..126a9c45 100644--- a/docs/index.md+++ b/docs/index.md@@ -74,6 +74,7 @@ Mocha is a feature-rich JavaScript test framework running on [Node.js](https://n- [Configuring Mocha (Node.js)](#configuring-mocha-nodejs)- [`mocha.opts`](#mochaopts)- [The `test/` Directory](#the-test-directory)+- [Error Codes](#error-codes)- [Editor Plugins](#editor-plugins)- [Examples](#examples)- [Testing Mocha](#testing-mocha)@@ -1724,6 +1725,20 @@ $ mocha "./spec/**/*.js"*Note*: Double quotes around the glob are recommended for portability.+## Error Codes++List of codes associated with Errors thrown inside Mocha. Following NodeJS practices.++| Code | Meaning |+| ------------- | ------------- |+| ERR_MOCHA_INVALID_ARG_TYPE | argument of the wrong type was passed to Mocha's API |+| ERR_MOCHA_INVALID_ARG_VALUE | invalid or unsupported value was passed for a given argument |+| ERR_MOCHA_INVALID_INTERFACE | interface specified in options not found |+| ERR_MOCHA_INVALID_REPORTER | reporter specified in options not found |+| ERR_MOCHA_NO_FILES_MATCH_PATTERN | file/s of test could not be found |+| ERR_MOCHA_NOT_SUPPORTED | type of output specified was not supported |+| ERR_MOCHA_UNDEFINED_ERROR | an error was thrown but no details were specified |+## Editor PluginsThe following editor-related packages are available:diff --git a/lib/cli/run-helpers.js b/lib/cli/run-helpers.jsindex 3afa7143..5212d386 100644--- a/lib/cli/run-helpers.js+++ b/lib/cli/run-helpers.js@@ -143,10 +143,8 @@ exports.handleFiles = ({try {newFiles = utils.lookupFiles(arg, extension, recursive);} catch (err) {- if (err.message.indexOf('cannot resolve path') === 0) {- console.error(- `Warning: Could not find any test files matching pattern: ${arg}`- );+ if (err.code === 'ERR_MOCHA_NO_FILES_MATCH_PATTERN') {+ console.warn('Warning: %s: %O', err.message, err.pattern);return;}diff --git a/lib/cli/run.js b/lib/cli/run.jsindex 1d6bf1ac..e6c14f67 100644--- a/lib/cli/run.js+++ b/lib/cli/run.js@@ -9,6 +9,8 @@const Mocha = require('../mocha');const ansi = require('ansi-colors');+const errors = require('../errors');+const createInvalidArgumentValueError = errors.createInvalidArgumentValueError;const {list,@@ -190,7 +192,12 @@ exports.builder = yargs =>const pair = opt.split('=');if (pair.length > 2 || !pair.length) {- throw new Error(`invalid reporter option '${opt}'`);+ throw createInvalidArgumentValueError(+ `invalid reporter option '${opt}'`,+ '--reporter-option',+ opt,+ 'expected "key=value" format'+ );}acc[pair[0]] = pair.length === 2 ? pair[1] : true;diff --git a/lib/errors.js b/lib/errors.jsnew file mode 100644index 00000000..90d0b92d--- /dev/null+++ b/lib/errors.js@@ -0,0 +1,139 @@+'use strict';+/**+ * @module Errors+ */+/**+ * Factory functions to create throwable error objects+ */++/**+ * Creates an error object used 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 used 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 used 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 used when the type of output specified was not supported.+ *+ * @public+ * @param {string} message - Error message to be displayed.+ * @returns {Error} instance detailing the error condition+ */+function createNotSupportedError(message) {+ var err = new Error(message);+ err.code = 'ERR_MOCHA_NOT_SUPPORTED';+ return err;+}++/**+ * Creates an error object used 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 used 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 used 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 used when an error was thrown but no details were specified.+ *+ * @public+ * @param {string} message - Error message to be displayed.+ * @returns {Error} instance detailing the error condition+ */+function createUndefinedError(message) {+ var err = new Error(message);+ err.code = 'ERR_MOCHA_UNDEFINED_ERROR';+ return err;+}++module.exports = {+ createInvalidArgumentTypeError: createInvalidArgumentTypeError,+ createInvalidArgumentValueError: createInvalidArgumentValueError,+ createInvalidInterfaceError: createInvalidInterfaceError,+ createInvalidReporterError: createInvalidReporterError,+ createMissingArgumentError: createMissingArgumentError,+ createNoFilesMatchPatternError: createNoFilesMatchPatternError,+ createNotSupportedError: createNotSupportedError,+ createUndefinedError: createUndefinedError+};diff --git a/lib/interfaces/common.js b/lib/interfaces/common.jsindex 3c6dffa9..1656ce2a 100644--- a/lib/interfaces/common.js+++ b/lib/interfaces/common.js@@ -2,6 +2,8 @@var Suite = require('../suite');var utils = require('../utils');+var errors = require('../errors');+var createMissingArgumentError = errors.createMissingArgumentError;/*** Functions common to more than one interface.@@ -147,11 +149,13 @@ module.exports = function(suites, context, mocha) {}suites.shift();} else if (typeof opts.fn === 'undefined' && !suite.pending) {- throw new Error(+ throw createMissingArgumentError('Suite "' +suite.fullTitle() +'" was defined but no callback was supplied. ' +- 'Supply a callback or explicitly skip the suite.'+ 'Supply a callback or explicitly skip the suite.',+ 'callback',+ 'function');} else if (!opts.fn && suite.pending) {suites.shift();diff --git a/lib/mocha.js b/lib/mocha.jsindex f92cc173..44478efd 100644--- a/lib/mocha.js+++ b/lib/mocha.js@@ -13,6 +13,9 @@ var growl = require('./growl');var utils = require('./utils');var mocharc = require('./mocharc.json');var assign = require('object.assign').getPolyfill();+var errors = require('./errors');+var createInvalidReporterError = errors.createInvalidReporterError;+var createInvalidInterfaceError = errors.createInvalidInterfaceError;exports = module.exports = Mocha;@@ -210,12 +213,16 @@ Mocha.prototype.reporter = function(reporter, reporterOptions) {try {_reporter = require(reporter);} catch (err) {- if (err.message.indexOf('Cannot find module') !== -1) {+ if (+ err.code !== 'MODULE_NOT_FOUND' ||+ err.message.includes('Cannot find module')+ ) {// Try to load reporters from a path (absolute or relative)try {_reporter = require(path.resolve(process.cwd(), reporter));} catch (_err) {- err.message.indexOf('Cannot find module') !== -1+ _err.code !== 'MODULE_NOT_FOUND' ||+ _err.message.includes('Cannot find module')? console.warn('"' + reporter + '" reporter not found'): console.warn('"' +@@ -239,7 +246,10 @@ Mocha.prototype.reporter = function(reporter, reporterOptions) {);}if (!_reporter) {- throw new Error('invalid reporter "' + reporter + '"');+ throw createInvalidReporterError(+ 'invalid reporter "' + reporter + '"',+ reporter+ );}this._reporter = _reporter;}@@ -265,7 +275,10 @@ Mocha.prototype.ui = function(name) {try {this._ui = require(name);} catch (err) {- throw new Error('invalid interface "' + name + '"');+ throw createInvalidInterfaceError(+ 'invalid interface "' + name + '"',+ name+ );}}this._ui = this._ui(this.suite);diff --git a/lib/reporters/xunit.js b/lib/reporters/xunit.jsindex f559207b..643367aa 100644--- a/lib/reporters/xunit.js+++ b/lib/reporters/xunit.js@@ -13,7 +13,8 @@ var fs = require('fs');var escape = utils.escape;var mkdirp = require('mkdirp');var path = require('path');-+var errors = require('../errors');+var createNotSupportedError = errors.createNotSupportedError;/*** Save timer references to avoid Sinon interfering (see GH-237).*/@@ -50,7 +51,7 @@ function XUnit(runner, options) {if (options && options.reporterOptions) {if (options.reporterOptions.output) {if (!fs.createWriteStream) {- throw new Error('file output not supported in browser');+ throw createNotSupportedError('file output not supported in browser');}mkdirp.sync(path.dirname(options.reporterOptions.output));diff --git a/lib/suite.js b/lib/suite.jsindex 482a4792..64e7db4b 100644--- a/lib/suite.js+++ b/lib/suite.js@@ -12,6 +12,8 @@ var utils = require('./utils');var inherits = utils.inherits;var debug = require('debug')('mocha:suite');var milliseconds = require('ms');+var errors = require('./errors');+var createInvalidArgumentTypeError = errors.createInvalidArgumentTypeError;/*** Expose `Suite`.@@ -49,10 +51,12 @@ exports.create = function(parent, title) {*/function Suite(title, parentContext) {if (!utils.isString(title)) {- throw new Error(- 'Suite `title` should be a "string" but "' ++ throw createInvalidArgumentTypeError(+ 'Suite argument "title" must be a string. Received type "' +typeof title +- '" was given instead.'+ '"',+ 'title',+ 'string');}this.title = title;diff --git a/lib/test.js b/lib/test.jsindex d8233a35..6c6aeb6b 100644--- a/lib/test.js+++ b/lib/test.js@@ -1,6 +1,8 @@'use strict';var Runnable = require('./runnable');var utils = require('./utils');+var errors = require('./errors');+var createInvalidArgumentTypeError = errors.createInvalidArgumentTypeError;var isString = utils.isString;module.exports = Test;@@ -15,10 +17,12 @@ module.exports = Test;*/function Test(title, fn) {if (!isString(title)) {- throw new Error(- 'Test `title` should be a "string" but "' ++ throw createInvalidArgumentTypeError(+ 'Test argument "title" should be a string. Received type "' +typeof title +- '" was given instead.'+ '"',+ 'title',+ 'string');}Runnable.call(this, title, fn);diff --git a/lib/utils.js b/lib/utils.jsindex 43d02faa..f2f2af41 100644--- a/lib/utils.js+++ b/lib/utils.js@@ -14,6 +14,10 @@ var glob = require('glob');var path = require('path');var join = path.join;var he = require('he');+var errors = require('./errors');+var createNoFilesMatchPatternError = errors.createNoFilesMatchPatternError;+var createMissingArgumentError = errors.createMissingArgumentError;+var createUndefinedError = errors.createUndefinedError;/*** Ignored directories.@@ -515,7 +519,10 @@ exports.lookupFiles = function lookupFiles(filepath, extensions, recursive) {} else {files = glob.sync(filepath);if (!files.length) {- throw new Error("cannot resolve path (or pattern) '" + filepath + "'");+ throw createNoFilesMatchPatternError(+ 'cannot find any files matching pattern "' + filepath + '"',+ filepath+ );}return files;}@@ -546,8 +553,10 @@ exports.lookupFiles = function lookupFiles(filepath, extensions, recursive) {return;}if (!extensions) {- throw new Error(- 'extensions parameter required when filepath is a directory'+ throw createMissingArgumentError(+ 'Argument "extensions" required when argument "filepath" is a directory',+ 'extensions',+ 'array');}var re = new RegExp('\\.(?:' + extensions.join('|') + ')$');@@ -567,7 +576,7 @@ exports.lookupFiles = function lookupFiles(filepath, extensions, recursive) {*/exports.undefinedError = function() {- return new Error(+ return createUndefinedError('Caught undefined error, did you throw without specifying what?');};diff --git a/test/integration/file-utils.spec.js b/test/integration/file-utils.spec.jsindex 74c30be4..3fe030ee 100644--- a/test/integration/file-utils.spec.js+++ b/test/integration/file-utils.spec.js@@ -75,11 +75,11 @@ describe('file utils', function() {var dirLookup = function() {return utils.lookupFiles(tmpDir, undefined, false);};- expect(- dirLookup,- 'to throw',- 'extensions parameter required when filepath is a directory'- );+ expect(dirLookup, 'to throw', {+ name: 'TypeError',+ code: 'ERR_MOCHA_INVALID_ARG_TYPE',+ argument: 'extensions'+ });});});diff --git a/test/integration/glob.spec.js b/test/integration/glob.spec.jsindex 29d7ec64..6aa7563b 100644--- a/test/integration/glob.spec.js+++ b/test/integration/glob.spec.js@@ -28,7 +28,7 @@ describe('globbing', function() {expect(results.stderr,'to contain',- 'Could not find any test files matching pattern'+ 'cannot find any files matching pattern "./*-none.js"');},done@@ -47,7 +47,7 @@ describe('globbing', function() {expect(results.stderr,'to contain',- 'Could not find any test files matching pattern'+ 'cannot find any files matching pattern');},done@@ -77,7 +77,7 @@ describe('globbing', function() {expect(results.stderr,'to contain',- 'Could not find any test files matching pattern'+ 'cannot find any files matching pattern');},done@@ -96,7 +96,7 @@ describe('globbing', function() {expect(results.stderr,'to contain',- 'Could not find any test files matching pattern'+ 'cannot find any files matching pattern');},done@@ -125,7 +125,7 @@ describe('globbing', function() {expect(results.stderr,'to contain',- 'Could not find any test files matching pattern'+ 'cannot find any files matching pattern');},done@@ -144,7 +144,7 @@ describe('globbing', function() {expect(results.stderr,'to contain',- 'Could not find any test files matching pattern'+ 'cannot find any files matching pattern');},donediff --git a/test/integration/suite.spec.js b/test/integration/suite.spec.jsindex 93450c95..cd379dc3 100644--- a/test/integration/suite.spec.js+++ b/test/integration/suite.spec.js@@ -1,6 +1,5 @@'use strict';-var assert = require('assert');var run = require('./helpers').runMocha;var args = [];@@ -13,8 +12,9 @@ describe('suite w/no callback', function() {if (err) {return done(err);}- var result = res.output.match(/no callback was supplied/) || [];- assert.strictEqual(result.length, 1);+ var pattern = new RegExp('TypeError', 'g');+ var result = res.output.match(pattern) || [];+ expect(result, 'to have length', 2);done();},{stdio: 'pipe'}@@ -28,9 +28,9 @@ describe('skipped suite w/no callback', function() {if (err) {return done(err);}- var pattern = new RegExp('Error', 'g');+ var pattern = new RegExp('TypeError', 'g');var result = res.output.match(pattern) || [];- assert.strictEqual(result.length, 0);+ expect(result, 'to have length', 0);done();});});@@ -42,9 +42,9 @@ describe('skipped suite w/ callback', function() {if (err) {return done(err);}- var pattern = new RegExp('Error', 'g');+ var pattern = new RegExp('TypeError', 'g');var result = res.output.match(pattern) || [];- assert.strictEqual(result.length, 0);+ expect(result, 'to have length', 0);done();});});@@ -61,7 +61,7 @@ describe('suite returning a value', function() {}var pattern = new RegExp('Deprecation Warning', 'g');var result = res.output.match(pattern) || [];- assert.strictEqual(result.length, 1);+ expect(result, 'to have length', 1);done();},{stdio: 'pipe'}diff --git a/test/reporters/helpers.js b/test/reporters/helpers.jsindex bd49392a..a507f25c 100644--- a/test/reporters/helpers.js+++ b/test/reporters/helpers.js@@ -1,5 +1,7 @@'use strict';+var errors = require('../../lib/errors');+var createNotSupportedError = errors.createNotSupportedError;/*This function prevents the constant use of creating a runnerEvent.runStr is the argument that defines the runnerEvent.@@ -116,7 +118,7 @@ function createRunnerFunction(runStr, ifStr1, ifStr2, ifStr3, arg1, arg2) {}};default:- throw new Error(+ throw createNotSupportedError('This function does not support the runner string specified.');}diff --git a/test/unit/errors.spec.js b/test/unit/errors.spec.jsnew file mode 100644index 00000000..51d066ef--- /dev/null+++ b/test/unit/errors.spec.js@@ -0,0 +1,28 @@+'use strict';++var errors = require('../../lib/errors');++describe('Errors', function() {+ var expectedMessage = 'some message';+ it('should include expected code in thrown reporter errors', function() {+ var throwError = function() {+ throw errors.createInvalidReporterError(expectedMessage, 'badReporter');+ };+ expect(throwError, 'to throw', {+ message: expectedMessage,+ code: 'ERR_MOCHA_INVALID_REPORTER',+ reporter: 'badReporter'+ });+ });++ it('should include expected code in thrown interface errors', function() {+ var throwError = function() {+ throw errors.createInvalidInterfaceError(expectedMessage, 'badUi');+ };+ expect(throwError, 'to throw', {+ message: expectedMessage,+ code: 'ERR_MOCHA_INVALID_INTERFACE',+ interface: 'badUi'+ });+ });+});diff --git a/test/unit/mocha.spec.js b/test/unit/mocha.spec.jsindex e17fe2cf..5cb6319d 100644--- a/test/unit/mocha.spec.js+++ b/test/unit/mocha.spec.js@@ -225,4 +225,19 @@ describe('Mocha', function() {expect(mocha.suite._bail, 'to be', true);});});++ describe('error handling', function() {+ it('should throw reporter error if an invalid reporter is given', function() {+ var updatedOpts = {reporter: 'invalidReporter', reporterOptions: {}};+ var throwError = function() {+ // eslint-disable-next-line no-new+ new Mocha(updatedOpts);+ };+ expect(throwError, 'to throw', {+ message: 'invalid reporter "invalidReporter"',+ code: 'ERR_MOCHA_INVALID_REPORTER',+ reporter: 'invalidReporter'+ });+ });+ });});