browser setup functions

lib/mocha.js

@@ -100,11 +100,9 @@ function Mocha(options) {
   this.grep(options.grep)
     .fgrep(options.fgrep)
     .ui(options.ui)
-    .bail(options.bail)
     .reporter(options.reporter, options.reporterOption)
     .slow(options.slow)
-    .useInlineDiffs(options.inlineDiffs)
-    .globals(options.global);
+    .global(options.global);
 
   // this guard exists because Suite#timeout does not consider `undefined` to be valid input
   if (typeof options.timeout !== 'undefined') {
@@ -118,12 +116,16 @@ function Mocha(options) {
   [
     'allowUncaught',
     'asyncOnly',
+    'bail',
     'checkLeaks',
+    'color',
     'delay',
+    'diff',
     'forbidOnly',
     'forbidPending',
     'fullTrace',
     'growl',
+    'inlineDiffs',
     'invert'
   ].forEach(function(opt) {
     if (options[opt]) {
@@ -136,16 +138,13 @@ function Mocha(options) {
  * Enables or disables bailing on the first failure.
  *
  * @public
- * @see {@link /#-bail-b|CLI option}
+ * @see [CLI](../#-bail-b)
  * @param {boolean} [bail=true] - Whether to bail on first error.
  * @returns {Mocha} this
  * @chainable
  */
 Mocha.prototype.bail = function(bail) {
-  if (!arguments.length) {
-    bail = true;
-  }
-  this.suite.bail(bail);
+  this.suite.bail(bail !== false);
   return this;
 };
 
@@ -430,44 +429,46 @@ Mocha.prototype.invert = function() {
 /**
  * Enables or disables ignoring global leaks.
  *
+ * @deprecated since v7.0.0
  * @public
  * @see {@link Mocha#checkLeaks}
  * @param {boolean} [ignoreLeaks=false] - Whether to ignore global leaks.
  * @return {Mocha} this
  * @chainable
- * @example
- *
- * // Ignore global leaks
- * mocha.ignoreLeaks(true);
  */
 Mocha.prototype.ignoreLeaks = function(ignoreLeaks) {
+  utils.deprecate(
+    '"ignoreLeaks()" is DEPRECATED, please use "checkLeaks()" instead.'
+  );
   this.options.checkLeaks = !ignoreLeaks;
   return this;
 };
 
 /**
- * Enables checking for global variables leaked while running tests.
+ * Enables or disables checking for global variables leaked while running tests.
  *
  * @public
- * @see {@link /#-check-leaks|CLI option}
- * @see {@link Mocha#ignoreLeaks}
+ * @see [CLI](../#-check-leaks)
+ * @param {boolean} [checkLeaks=true] - Whether to check for global variable leaks.
  * @return {Mocha} this
  * @chainable
  */
-Mocha.prototype.checkLeaks = function() {
-  this.options.checkLeaks = true;
+Mocha.prototype.checkLeaks = function(checkLeaks) {
+  this.options.checkLeaks = checkLeaks !== false;
   return this;
 };
 
 /**
  * Displays full stack trace upon test failure.
  *
  * @public
+ * @see [CLI](../#-full-trace)
+ * @param {boolean} [fullTrace=true] - Whether to print full stacktrace upon failure.
  * @return {Mocha} this
  * @chainable
  */
-Mocha.prototype.fullTrace = function() {
-  this.options.fullTrace = true;
+Mocha.prototype.fullTrace = function(fullTrace) {
+  this.options.fullTrace = fullTrace !== false;
   return this;
 };
 
@@ -519,68 +520,121 @@ Mocha.prototype._growl = growl.notify;
  * Specifies whitelist of variable names to be expected in global scope.
  *
  * @public
- * @see {@link /#-global-variable-name|CLI option}
+ * @see [CLI](../#-global-variable-name)
  * @see {@link Mocha#checkLeaks}
- * @param {String[]|String} globals - Accepted global variable name(s).
+ * @param {String[]|String} global - Accepted global variable name(s).
  * @return {Mocha} this
  * @chainable
  * @example
  *
  * // Specify variables to be expected in global scope
- * mocha.globals(['jQuery', 'MyLib']);
+ * mocha.global(['jQuery', 'MyLib']);
  */
-Mocha.prototype.globals = function(globals) {
+Mocha.prototype.global = function(global) {
   this.options.global = (this.options.global || [])
-    .concat(globals)
+    .concat(global)
     .filter(Boolean)
     .filter(function(elt, idx, arr) {
       return arr.indexOf(elt) === idx;
     });
   return this;
 };
+// for backwards compability, 'globals' is an alias of 'global'
+Mocha.prototype.globals = Mocha.prototype.global;
 
 /**
  * Enables or disables TTY color output by screen-oriented reporters.
  *
+ * @deprecated since v7.0.0
  * @public
  * @param {boolean} colors - Whether to enable color output.
  * @return {Mocha} this
  * @chainable
  */
 Mocha.prototype.useColors = function(colors) {
+  utils.deprecate('"useColors()" is DEPRECATED, please use "color()" instead.');
   if (colors !== undefined) {
     this.options.color = colors;
   }
   return this;
 };
 
+/**
+ * Enables or disables TTY color output by screen-oriented reporters.
+ *
+ * @public
+ * @see [CLI](../#-color-c-colors)
+ * @param {boolean} [color=true] - Whether to enable color output.
+ * @return {Mocha} this
+ * @chainable
+ */
+Mocha.prototype.color = function(color) {
+  this.options.color = color !== false;
+  return this;
+};
+
 /**
  * Determines if reporter should use inline diffs (rather than +/-)
  * in test failure output.
  *
+ * @deprecated since v7.0.0
  * @public
  * @param {boolean} [inlineDiffs=false] - Whether to use inline diffs.
  * @return {Mocha} this
  * @chainable
  */
 Mocha.prototype.useInlineDiffs = function(inlineDiffs) {
+  utils.deprecate(
+    '"useInlineDiffs()" is DEPRECATED, please use "inlineDiffs()" instead.'
+  );
   this.options.inlineDiffs = inlineDiffs !== undefined && inlineDiffs;
   return this;
 };
 
+/**
+ * Enables or disables reporter to use inline diffs (rather than +/-)
+ * in test failure output.
+ *
+ * @public
+ * @see [CLI](../#-inline-diffs)
+ * @param {boolean} [inlineDiffs=true] - Whether to use inline diffs.
+ * @return {Mocha} this
+ * @chainable
+ */
+Mocha.prototype.inlineDiffs = function(inlineDiffs) {
+  this.options.inlineDiffs = inlineDiffs !== false;
+  return this;
+};
+
 /**
  * Determines if reporter should include diffs in test failure output.
  *
+ * @deprecated since v7.0.0
  * @public
  * @param {boolean} [hideDiff=false] - Whether to hide diffs.
  * @return {Mocha} this
  * @chainable
  */
 Mocha.prototype.hideDiff = function(hideDiff) {
+  utils.deprecate('"hideDiff()" is DEPRECATED, please use "diff()" instead.');
   this.options.diff = !(hideDiff === true);
   return this;
 };
 
+/**
+ * Enables or disables reporter to include diff in test failure output.
+ *
+ * @public
+ * @see [CLI](../#-diff)
+ * @param {boolean} [diff=true] - Whether to show diff on failure.
+ * @return {Mocha} this
+ * @chainable
+ */
+Mocha.prototype.diff = function(diff) {
+  this.options.diff = diff !== false;
+  return this;
+};
+
 /**
  * @summary
  * Sets timeout threshold value.
@@ -670,11 +724,13 @@ Mocha.prototype.enableTimeouts = function(enableTimeouts) {
  * Forces all tests to either accept a `done` callback or return a promise.
  *
  * @public
+ * @see [CLI](../#-async-only-a)
+ * @param {boolean} [asyncOnly=true] - Wether to force `done` callback or promise.
  * @return {Mocha} this
  * @chainable
  */
-Mocha.prototype.asyncOnly = function() {
-  this.options.asyncOnly = true;
+Mocha.prototype.asyncOnly = function(asyncOnly) {
+  this.options.asyncOnly = asyncOnly !== false;
   return this;
 };
 
@@ -691,14 +747,16 @@ Mocha.prototype.noHighlighting = function() {
 };
 
 /**
- * Enables uncaught errors to propagate (in browser).
+ * Enables or disables uncaught errors to propagate.
  *
  * @public
+ * @see [CLI](../#-allow-uncaught)
+ * @param {boolean} [allowUncaught=true] - Whether to propagate uncaught errors.
  * @return {Mocha} this
  * @chainable
  */
-Mocha.prototype.allowUncaught = function() {
-  this.options.allowUncaught = true;
+Mocha.prototype.allowUncaught = function(allowUncaught) {
+  this.options.allowUncaught = allowUncaught !== false;
   return this;
 };
 
@@ -723,23 +781,27 @@ Mocha.prototype.delay = function delay() {
  * Causes tests marked `only` to fail the suite.
  *
  * @public
+ * @see [CLI](../#-forbid-only)
+ * @param {boolean} [forbidOnly=true] - Whether tests marked `only` fail the suite.
  * @returns {Mocha} this
  * @chainable
  */
-Mocha.prototype.forbidOnly = function() {
-  this.options.forbidOnly = true;
+Mocha.prototype.forbidOnly = function(forbidOnly) {
+  this.options.forbidOnly = forbidOnly !== false;
   return this;
 };
 
 /**
  * Causes pending tests and tests marked `skip` to fail the suite.
  *
  * @public
+ * @see [CLI](../#-forbid-pending)
+ * @param {boolean} [forbidPending=true] - Whether pending tests fail the suite.
  * @returns {Mocha} this
  * @chainable
  */
-Mocha.prototype.forbidPending = function() {
-  this.options.forbidPending = true;
+Mocha.prototype.forbidPending = function(forbidPending) {
+  this.options.forbidPending = forbidPending !== false;
   return this;
 };