Introduce a configuration object to Env deprecating old single use functions

[finishes #159158038]

src/core/Env.js

@@ -23,14 +23,62 @@ getJasmineRequireObj().Env = function(j$) {
     var currentSpec = null;
     var currentlyExecutingSuites = [];
     var currentDeclarationSuite = null;
-    var throwOnExpectationFailure = false;
-    var stopOnSpecFailure = false;
-    var random = true;
-    var hidingDisabled = false;
-    var seed = null;
-    var handlingLoadErrors = true;
     var hasFailures = false;
 
+    /**
+     * This represents the available options to configure Jasmine.
+     * Options that are not provided will use their default values
+     * @interface Configuration
+     */
+    var config = {
+      /**
+       * Whether to randomize spec execution order
+       * @name Configuration#random
+       * @type Boolean
+       * @default true
+       */
+      random: true,
+      /**
+       * Seed to use as the basis of randomization.
+       * Null causes the seed to be determined randomly at the start of execution.
+       * @name Configuration#seed
+       * @type function
+       * @default null
+       */
+      seed: null,
+      /**
+       * Whether to stop execution of the suite after the first spec failure
+       * @name Configuration#failFast
+       * @type Boolean
+       * @default false
+       */
+      failFast: false,
+      /**
+       * Whether to cause specs to only have one expectation failure.
+       * @name Configuration#oneFailurePerSpec
+       * @type Boolean
+       * @default false
+       */
+      oneFailurePerSpec: false,
+      /**
+       * Function to use to filter specs
+       * @name Configuration#specFilter
+       * @type function
+       * @default true
+       */
+      specFilter: function() {
+        return true;
+      },
+      /**
+       * Whether or not reporters should hide disabled specs from their output.
+       * Currently only supported by Jasmine's HTMLReporter
+       * @name Configuration#hideDisabled
+       * @type Boolean
+       * @default false
+       */
+      hideDisabled: false
+    };
+
     var currentSuite = function() {
       return currentlyExecutingSuites[currentlyExecutingSuites.length - 1];
     };
@@ -63,10 +111,63 @@ getJasmineRequireObj().Env = function(j$) {
       });
     }
 
-    this.specFilter = function() {
-      return true;
+    /**
+     * Configure your jasmine environment
+     * @name Env#configure
+     * @argument {Configuration} configuration
+     * @function
+     */
+    this.configure = function(configuration) {
+      if (configuration.specFilter) {
+        config.specFilter = configuration.specFilter;
+      }
+
+      if (configuration.hasOwnProperty('random')) {
+        config.random = !!configuration.random;
+      }
+
+      if (configuration.hasOwnProperty('seed')) {
+        config.seed = configuration.seed;
+      }
+
+      if (configuration.hasOwnProperty('failFast')) {
+        config.failFast = configuration.failFast;
+      }
+
+      if (configuration.hasOwnProperty('oneFailurePerSpec')) {
+        config.oneFailurePerSpec = configuration.oneFailurePerSpec;
+      }
+
+      if (configuration.hasOwnProperty('hideDisabled')) {
+        config.hideDisabled = configuration.hideDisabled;
+      }
     };
 
+    /**
+     * Get the current configuration for your jasmine environment
+     * @name Env#configuration
+     * @function
+     * @returns {Configuration}
+     */
+    this.configuration = function() {
+      var result = {};
+      for (var property in config) {
+        result[property] = config[property];
+      }
+      return result;
+    };
+
+    Object.defineProperty(this, 'specFilter', {
+      get: function() {
+        self.deprecated('Getting specFilter directly from Env is deprecated, please check the specFilter option from `configuration`');
+        return config.specFilter;
+      },
+      set: function(val) {
+        self.deprecated('Setting specFilter directly on Env is deprecated, please use the specFilter option in `configure`');
+        config.specFilter = val;
+      }
+    });
+
     this.addSpyStrategy = function(name, fn) {
       if(!currentRunnable()) {
         throw new Error('Custom spy strategies must be added in a before function or a spec');
@@ -194,13 +295,16 @@ getJasmineRequireObj().Env = function(j$) {
      * @name Env#throwOnExpectationFailure
      * @function
      * @param {Boolean} value Whether to throw when a expectation fails
+     * @deprecated Use the `oneFailurePerSpec` option with {@link Env#configure}
      */
     this.throwOnExpectationFailure = function(value) {
-      throwOnExpectationFailure = !!value;
+      this.deprecated('Setting throwOnExpectationFailure directly on Env is deprecated, please use the oneFailurePerSpec option in `configure`');
+      this.configure({oneFailurePerSpec: !!value});
     };
 
     this.throwingExpectationFailures = function() {
-      return throwOnExpectationFailure;
+      this.deprecated('Getting throwingExpectationFailures directly from Env is deprecated, please check the oneFailurePerSpec option from `configuration`');
+      return config.oneFailurePerSpec;
     };
 
     /**
@@ -208,13 +312,16 @@ getJasmineRequireObj().Env = function(j$) {
      * @name Env#stopOnSpecFailure
      * @function
      * @param {Boolean} value Whether to stop suite execution when a spec fails
+     * @deprecated Use the `failFast` option with {@link Env#configure}
      */
     this.stopOnSpecFailure = function(value) {
-      stopOnSpecFailure = !!value;
+      this.deprecated('Setting stopOnSpecFailure directly is deprecated, please use the failFast option in `configure`');
+      this.configure({failFast: !!value});
     };
 
     this.stoppingOnSpecFailure = function() {
-      return stopOnSpecFailure;
+      this.deprecated('Getting stoppingOnSpecFailure directly from Env is deprecated, please check the failFast option from `configuration`');
+      return config.failFast;
     };
 
     /**
@@ -222,13 +329,16 @@ getJasmineRequireObj().Env = function(j$) {
      * @name Env#randomizeTests
      * @function
      * @param {Boolean} value Whether to randomize execution order
+     * @deprecated Use the `random` option with {@link Env#configure}
      */
     this.randomizeTests = function(value) {
-      random = !!value;
+      this.deprecated('Setting randomizeTests directly is deprecated, please use the random option in `configure`');
+      config.random = !!value;
     };
 
     this.randomTests = function() {
-      return random;
+      this.deprecated('Getting randomTests directly from Env is deprecated, please check the random option from `configuration`');
+      return config.random;
     };
 
     /**
@@ -236,16 +346,19 @@ getJasmineRequireObj().Env = function(j$) {
      * @name Env#seed
      * @function
      * @param {Number} value The seed value
+     * @deprecated Use the `seed` option with {@link Env#configure}
      */
     this.seed = function(value) {
+      this.deprecated('Setting seed directly is deprecated, please use the seed option in `configure`');
       if (value) {
-        seed = value;
+        config.seed = value;
       }
-      return seed;
+      return config.seed;
     };
 
     this.hidingDisabled = function(value) {
-      return hidingDisabled;
+      this.deprecated('Getting hidingDisabled directly from Env is deprecated, please check the hideDisabled option from `configuration`');
+      return config.hideDisabled;
     };
 
     /**
@@ -253,7 +366,8 @@ getJasmineRequireObj().Env = function(j$) {
      * @function
      */
     this.hideDisabled = function(value) {
-      hidingDisabled = !!value;
+      this.deprecated('Setting hideDisabled directly is deprecated, please use the hideDisabled option in `configure`');
+      config.hideDisabled = !!value;
     };
 
     this.deprecated = function(deprecation) {
@@ -267,9 +381,9 @@ getJasmineRequireObj().Env = function(j$) {
     var queueRunnerFactory = function(options, args) {
       var failFast = false;
       if (options.isLeaf) {
-        failFast = throwOnExpectationFailure;
+        failFast = config.oneFailurePerSpec;
       } else if (!options.isReporter) {
-        failFast = stopOnSpecFailure;
+        failFast = config.failFast;
       }
       options.clearStack = options.clearStack || clearStack;
       options.timeout = {setTimeout: realSetTimeout, clearTimeout: realClearTimeout};
@@ -384,8 +498,8 @@ getJasmineRequireObj().Env = function(j$) {
       }
 
       var order = new j$.Order({
-        random: random,
-        seed: seed
+        random: config.random,
+        seed: config.seed
       });
 
       var processor = new j$.TreeProcessor({
@@ -415,7 +529,7 @@ getJasmineRequireObj().Env = function(j$) {
           return order.sort(node.children);
         },
         excludeNode: function(spec) {
-          return !self.specFilter(spec);
+          return !config.specFilter(spec);
         }
       });
 
@@ -582,7 +696,7 @@ getJasmineRequireObj().Env = function(j$) {
         expectationFactory: expectationFactory,
         asyncExpectationFactory: asyncExpectationFactory,
         expectationResultFactory: expectationResultFactory,
-        throwOnExpectationFailure: throwOnExpectationFailure
+        throwOnExpectationFailure: config.oneFailurePerSpec
       });
 
       return suite;
@@ -688,7 +802,7 @@ getJasmineRequireObj().Env = function(j$) {
           fn: fn,
           timeout: timeout || 0
         },
-        throwOnExpectationFailure: throwOnExpectationFailure
+        throwOnExpectationFailure: config.oneFailurePerSpec
       });
 
       return spec;
@@ -836,7 +950,7 @@ getJasmineRequireObj().Env = function(j$) {
         error: error && error.message ? error : null
       });
 
-      if (self.throwingExpectationFailures()) {
+      if (config.oneFailurePerSpec) {
         throw new Error(message);
       }
     };