Improved readability of matcher-related deprecations

* Include stack traces. This makes it easier to find the matcher that
needs to be updated, particularly when it comes from a library rather
than the user's own code.

* Show each deprecation only once unless `config.verboseDeprecations`
is set. Since matchers are often added in a global `beforeEach`, logging
deprecations every time can be overwhelming.

src/core/Env.js

@@ -32,6 +32,7 @@ getJasmineRequireObj().Env = function(j$) {
     var currentlyExecutingSuites = [];
     var currentDeclarationSuite = null;
     var hasFailures = false;
+    var deprecationsToSuppress = [];
 
     /**
      * This represents the available options to configure Jasmine.
@@ -111,7 +112,19 @@ getJasmineRequireObj().Env = function(j$) {
        * @type function
        * @default undefined
        */
-      Promise: undefined
+      Promise: undefined,
+      /**
+       * Whether or not to issue warnings for certain deprecated functionality
+       * every time it's used. If not set or set to false, deprecation warnings
+       * for methods that tend to be called frequently will be issued only once
+       * or otherwise throttled to to prevent the suite output from being flooded
+       * with warnings.
+       * @name Configuration#verboseDeprecations
+       * @since 3.6.0
+       * @type Boolean
+       * @default false
+       */
+      verboseDeprecations: false
     };
 
     var currentSuite = function() {
@@ -205,6 +218,10 @@ getJasmineRequireObj().Env = function(j$) {
           );
         }
       }
+
+      if (configuration.hasOwnProperty('verboseDeprecations')) {
+        config.verboseDeprecations = configuration.verboseDeprecations;
+      }
     };
 
     /**
@@ -279,7 +296,7 @@ getJasmineRequireObj().Env = function(j$) {
 
       for (var matcherName in matchersToAdd) {
         if (matchersToAdd[matcherName].length > 1) {
-          self.deprecated(
+          self.deprecatedOnceWithStack(
             'The matcher factory for "' +
               matcherName +
               '" ' +
@@ -304,7 +321,7 @@ getJasmineRequireObj().Env = function(j$) {
 
       for (var matcherName in matchersToAdd) {
         if (matchersToAdd[matcherName].length > 1) {
-          self.deprecated(
+          self.deprecatedOnceWithStack(
             'The matcher factory for "' +
               matcherName +
               '" ' +
@@ -612,6 +629,29 @@ getJasmineRequireObj().Env = function(j$) {
       }
     };
 
+    this.deprecatedOnceWithStack = function(deprecation) {
+      var formatter = new j$.ExceptionFormatter(),
+        stackTrace = formatter
+          .stack(j$.util.errorWithStack())
+          .replace(/^Error\n/m, '');
+
+      if (config.verboseDeprecations) {
+        this.deprecated(deprecation + '\n' + stackTrace);
+      } else {
+        if (deprecationsToSuppress.indexOf(deprecation) === -1) {
+          this.deprecated(
+            deprecation +
+              '\n' +
+              'Note: This message will be shown only once. ' +
+              'Set config.verboseDeprecations to true to see every occurrence.\n' +
+              stackTrace
+          );
+        }
+
+        deprecationsToSuppress.push(deprecation);
+      }
+    };
+
     var queueRunnerFactory = function(options, args) {
       var failFast = false;
       if (options.isLeaf) {

src/core/matchers/matchersUtil.js

@@ -34,9 +34,9 @@ getJasmineRequireObj().MatchersUtil = function(j$) {
    */
   MatchersUtil.prototype.contains = function(haystack, needle, customTesters) {
     if (customTesters) {
-      j$.getEnv().deprecated('Passing custom equality testers to ' +
-        'MatchersUtil#contains is deprecated. See ' +
-        '<https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
+      j$.getEnv().deprecatedOnceWithStack('Passing custom equality testers ' +
+        'to MatchersUtil#contains is deprecated. ' +
+        'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
     }
 
     if (j$.isSet(haystack)) {
@@ -138,14 +138,14 @@ getJasmineRequireObj().MatchersUtil = function(j$) {
       diffBuilder = customTestersOrDiffBuilder;
     } else {
       if (customTestersOrDiffBuilder) {
-        j$.getEnv().deprecated('Passing custom equality testers to ' +
-          'MatchersUtil#equals is deprecated. See ' +
-          '<https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
+        j$.getEnv().deprecatedOnceWithStack('Passing custom equality testers ' +
+          'to MatchersUtil#equals is deprecated. ' +
+          'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
       }
 
       if (diffBuilderOrNothing) {
-        j$.getEnv().deprecated('Diff builder should be passed as the third argument ' +
-          'to MatchersUtil#equals, not the fourth. ' +
+        j$.getEnv().deprecatedOnceWithStack('Diff builder should be passed ' +
+          'as the third argument to MatchersUtil#equals, not the fourth. ' +
           'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
       }
 

src/core/requireCore.js

@@ -58,7 +58,7 @@ var getJasmineRequireObj = (function(jasmineGlobal) {
     j$.basicPrettyPrinter_ = j$.makePrettyPrinter();
     Object.defineProperty(j$, 'pp', {
       get: function() {
-        j$.getEnv().deprecated(
+        j$.getEnv().deprecatedOnceWithStack(
           'jasmine.pp is deprecated and will be removed in a future release. ' +
             'Use the pp method of the matchersUtil passed to the matcher factory ' +
             "or the asymmetric equality tester's `asymmetricMatch` method " +
@@ -75,7 +75,7 @@ var getJasmineRequireObj = (function(jasmineGlobal) {
     });
     Object.defineProperty(j$, 'matchersUtil', {
       get: function() {
-        j$.getEnv().deprecated(
+        j$.getEnv().deprecatedOnceWithStack(
           'jasmine.matchersUtil is deprecated and will be removed ' +
             'in a future release. Use the instance passed to the matcher factory or ' +
             "the asymmetric equality tester's `asymmetricMatch` method instead. " +