Added deprecation messages to interfaces that will be removed in 4.0

* `jasmine.pp`
* `jasmine.matchersUtil`
* Matchers that expect to receive custom equality testers
* Passing custom equality testers to `matchersUtil.contains`
* Passing custom equality testers to `matchersUtil.equals`

lib/jasmine-core/jasmine.js

@@ -77,11 +77,34 @@ var getJasmineRequireObj = (function(jasmineGlobal) {
       j$
     );
     j$.makePrettyPrinter = jRequire.makePrettyPrinter(j$);
-    j$.pp = j$.makePrettyPrinter();
+    j$.basicPrettyPrinter_ = j$.makePrettyPrinter();
+    Object.defineProperty(j$, 'pp', {
+      get: function() {
+        j$.getEnv().deprecated(
+          '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 " +
+            'instead. See ' +
+            '<https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
+        );
+        return j$.basicPrettyPrinter_;
+      }
+    });
     j$.MatchersUtil = jRequire.MatchersUtil(j$);
-    j$.matchersUtil = new j$.MatchersUtil({
+    var staticMatchersUtil = new j$.MatchersUtil({
       customTesters: [],
-      pp: j$.pp
+      pp: j$.basicPrettyPrinter_
+    });
+    Object.defineProperty(j$, 'matchersUtil', {
+      get: function() {
+        j$.getEnv().deprecated(
+          '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. " +
+            'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
+        );
+        return staticMatchersUtil;
+      }
     });
 
     j$.ObjectContaining = jRequire.ObjectContaining(j$);
@@ -1204,6 +1227,17 @@ getJasmineRequireObj().Env = function(j$) {
         runnableResources[currentRunnable().id].customMatchers;
 
       for (var matcherName in matchersToAdd) {
+        if (matchersToAdd[matcherName].length > 1) {
+          self.deprecated(
+            'The matcher factory for "' +
+              matcherName +
+              '" ' +
+              'accepts custom equality testers, but this parameter will no longer be ' +
+              'passed in a future release. ' +
+              'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
+          );
+        }
+
         customMatchers[matcherName] = matchersToAdd[matcherName];
       }
     };
@@ -1218,6 +1252,17 @@ getJasmineRequireObj().Env = function(j$) {
         runnableResources[currentRunnable().id].customAsyncMatchers;
 
       for (var matcherName in matchersToAdd) {
+        if (matchersToAdd[matcherName].length > 1) {
+          self.deprecated(
+            'The matcher factory for "' +
+              matcherName +
+              '" ' +
+              'accepts custom equality testers, but this parameter will no longer be ' +
+              'passed in a future release. ' +
+              'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
+          );
+        }
+
         customAsyncMatchers[matcherName] = matchersToAdd[matcherName];
       }
     };
@@ -2360,7 +2405,7 @@ getJasmineRequireObj().ArrayContaining = function(j$) {
 
   ArrayContaining.prototype.asymmetricMatch = function(other, matchersUtil) {
     if (!j$.isArray_(this.sample)) {
-      throw new Error('You must provide an array to arrayContaining, not ' + j$.pp(this.sample) + '.');
+      throw new Error('You must provide an array to arrayContaining, not ' + j$.basicPrettyPrinter_(this.sample) + '.');
     }
 
     // If the actual parameter is not an array, we can fail immediately, since it couldn't
@@ -2395,7 +2440,7 @@ getJasmineRequireObj().ArrayWithExactContents = function(j$) {
 
   ArrayWithExactContents.prototype.asymmetricMatch = function(other, matchersUtil) {
     if (!j$.isArray_(this.sample)) {
-      throw new Error('You must provide an array to arrayWithExactContents, not ' + j$.pp(this.sample) + '.');
+      throw new Error('You must provide an array to arrayWithExactContents, not ' + j$.basicPrettyPrinter_(this.sample) + '.');
     }
 
     if (this.sample.length !== other.length) {
@@ -2463,7 +2508,7 @@ getJasmineRequireObj().Falsy = function(j$) {
 getJasmineRequireObj().MapContaining = function(j$) {
   function MapContaining(sample) {
     if (!j$.isMap(sample)) {
-      throw new Error('You must provide a map to `mapContaining`, not ' + j$.pp(sample));
+      throw new Error('You must provide a map to `mapContaining`, not ' + j$.basicPrettyPrinter_(sample));
     }
 
     this.sample = sample;
@@ -2604,7 +2649,7 @@ getJasmineRequireObj().ObjectContaining = function(j$) {
 getJasmineRequireObj().SetContaining = function(j$) {
   function SetContaining(sample) {
     if (!j$.isSet(sample)) {
-      throw new Error('You must provide a set to `setContaining`, not ' + j$.pp(sample));
+      throw new Error('You must provide a set to `setContaining`, not ' + j$.basicPrettyPrinter_(sample));
     }
 
     this.sample = sample;
@@ -2735,10 +2780,10 @@ getJasmineRequireObj().asymmetricEqualityTesterArgCompatShim = function(j$) {
       i,
       k;
 
-    copy(self, customEqualityTesters, 'length');
+    copyAndDeprecate(self, customEqualityTesters, 'length');
 
     for (i = 0; i < customEqualityTesters.length; i++) {
-      copy(self, customEqualityTesters, i);
+      copyAndDeprecate(self, customEqualityTesters, i);
     }
 
     var props = arrayProps();
@@ -2746,16 +2791,22 @@ getJasmineRequireObj().asymmetricEqualityTesterArgCompatShim = function(j$) {
     for (i = 0; i < props.length; i++) {
       k = props[i];
       if (k !== 'length') {
-        copy(self, Array.prototype, k);
+        copyAndDeprecate(self, Array.prototype, k);
       }
     }
 
     return self;
   }
 
-  function copy(dest, src, propName) {
+  function copyAndDeprecate(dest, src, propName) {
     Object.defineProperty(dest, propName, {
       get: function() {
+        j$.getEnv().deprecated(
+          'The second argument to asymmetricMatch is now a ' +
+            'MatchersUtil. Using it as an array of custom equality testers is ' +
+            'deprecated and will stop working in a future release. ' +
+            'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
+        );
         return src[propName];
       }
     });
@@ -3488,7 +3539,7 @@ getJasmineRequireObj().ExceptionFormatter = function(j$) {
       }
 
       if (!empty) {
-        return 'error properties: ' + j$.pp(result) + '\n';
+        return 'error properties: ' + j$.basicPrettyPrinter_(result) + '\n';
       }
 
       return '';
@@ -4403,8 +4454,6 @@ getJasmineRequireObj().DiffBuilder = function (j$) {
 };
 
 getJasmineRequireObj().MatchersUtil = function(j$) {
-  // TODO: convert all uses of j$.pp to use the injected pp
-
   /**
    * _Note:_ Do not construct this directly. Jasmine will construct one and
    * pass it to matchers and asymmetric equality testers.
@@ -4434,10 +4483,17 @@ getJasmineRequireObj().MatchersUtil = function(j$) {
    * @name MatchersUtil#contains
    * @param {*} haystack The collection to search
    * @param {*} needle The value to search for
-   * @param [customTesters] An array of custom equality testers
+   * @param [customTesters] An array of custom equality testers. Deprecated.
+   * As of 3.6 this parameter no longer needs to be passed. It will be removed in 4.0.
    * @returns {boolean} True if `needle` was found in `haystack`
    */
   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.');
+    }
+
     if (j$.isSet(haystack)) {
       return haystack.has(needle);
     }
@@ -4526,7 +4582,8 @@ getJasmineRequireObj().MatchersUtil = function(j$) {
    * @name MatchersUtil#equals
    * @param {*} a The first value to compare
    * @param {*} b The second value to compare
-   * @param [customTesters] An array of custom equality testers
+   * @param [customTesters] An array of custom equality testers. Deprecated.
+   * As of 3.6 this parameter no longer needs to be passed. It will be removed in 4.0.
    * @returns {boolean} True if the values are equal
    */
   MatchersUtil.prototype.equals = function(a, b, customTestersOrDiffBuilder, diffBuilderOrNothing) {
@@ -4535,6 +4592,18 @@ getJasmineRequireObj().MatchersUtil = function(j$) {
     if (isDiffBuilder(customTestersOrDiffBuilder)) {
       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.');
+      }
+
+      if (diffBuilderOrNothing) {
+        j$.getEnv().deprecated('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.');
+      }
+
       customTesters = customTestersOrDiffBuilder;
       diffBuilder = diffBuilderOrNothing;
     }
@@ -7563,7 +7632,7 @@ getJasmineRequireObj().Spy = function(j$) {
             "Spy '" +
               strategyArgs.name +
               "' received a call with arguments " +
-              j$.pp(Array.prototype.slice.call(args)) +
+              j$.basicPrettyPrinter_(Array.prototype.slice.call(args)) +
               ' but all configured strategies specify other arguments.'
           );
         } else {

spec/core/asymmetricEqualityTesterArgCompatShimSpec.js

@@ -13,27 +13,54 @@ describe('asymmetricEqualityTesterArgCompatShim', function() {
     expect(shim.bar).toBe(matchersUtil.bar);
   });
 
-  it('provides all the properties of the customEqualityTesters', function() {
+  it('provides and deprecates all the properties of the customEqualityTesters', function() {
     var customEqualityTesters = [function() {}, function() {}],
       shim = jasmineUnderTest.asymmetricEqualityTesterArgCompatShim(
         {},
         customEqualityTesters
-      );
+      ),
+      deprecated = spyOn(jasmineUnderTest.getEnv(), 'deprecated'),
+      expectedMessage =
+        'The second argument to asymmetricMatch is now a MatchersUtil. ' +
+        'Using it as an array of custom equality testers is deprecated and will stop ' +
+        'working in a future release. ' +
+        'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.';
 
     expect(shim.length).toBe(2);
+    expect(deprecated).toHaveBeenCalledWith(expectedMessage);
+    deprecated.calls.reset();
+
     expect(shim[0]).toBe(customEqualityTesters[0]);
+    expect(deprecated).toHaveBeenCalledWith(expectedMessage);
+    deprecated.calls.reset();
+
     expect(shim[1]).toBe(customEqualityTesters[1]);
+    expect(deprecated).toHaveBeenCalledWith(expectedMessage);
   });
 
-  it('provides all the properties of Array.prototype', function() {
+  it('provides and deprecates all the properties of Array.prototype', function() {
-    var shim = jasmineUnderTest.asymmetricEqualityTesterArgCompatShim({}, []);
+    var shim = jasmineUnderTest.asymmetricEqualityTesterArgCompatShim({}, []),
+      deprecated = spyOn(jasmineUnderTest.getEnv(), 'deprecated'),
+      expectedMessage =
+        'The second argument to asymmetricMatch is now a MatchersUtil. ' +
+        'Using it as an array of custom equality testers is deprecated and will stop ' +
+        'working in a future release. ' +
+        'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.';
 
     expect(shim.filter).toBe(Array.prototype.filter);
+    expect(deprecated).toHaveBeenCalledWith(expectedMessage);
+    deprecated.calls.reset();
+
     expect(shim.forEach).toBe(Array.prototype.forEach);
+    expect(deprecated).toHaveBeenCalledWith(expectedMessage);
+    deprecated.calls.reset();
+
     expect(shim.map).toBe(Array.prototype.map);
+    expect(deprecated).toHaveBeenCalledWith(expectedMessage);
+    deprecated.calls.reset();
   });
 
-  it('provides properties of Array.prototype', function() {
+  it('provides and deprecates properties of Array.prototype', function() {
     var keys = [
         'concat',
         'constructor',
@@ -73,6 +100,7 @@ describe('asymmetricEqualityTesterArgCompatShim', function() {
         'values'
       ],
       shim = jasmineUnderTest.asymmetricEqualityTesterArgCompatShim({}, []),
+      deprecated = spyOn(jasmineUnderTest.getEnv(), 'deprecated'),
       i,
       k;
 
@@ -85,6 +113,8 @@ describe('asymmetricEqualityTesterArgCompatShim', function() {
       expect(shim[k])
         .withContext(k)
         .toBe(Array.prototype[k]);
+      expect(deprecated).toHaveBeenCalled();
+      deprecated.calls.reset();
     }
 
     // Properties that are present on only some supported runtimes
@@ -95,7 +125,21 @@ describe('asymmetricEqualityTesterArgCompatShim', function() {
         expect(shim[k])
           .withContext(k)
           .toBe(Array.prototype[k]);
+        expect(deprecated)
+          .withContext(k)
+          .toHaveBeenCalled();
+        deprecated.calls.reset();
       }
     }
   });
+
+  it('does not deprecate properties of Object.prototype', function() {
+    var shim = jasmineUnderTest.asymmetricEqualityTesterArgCompatShim({}, []),
+      deprecated = spyOn(jasmineUnderTest.getEnv(), 'deprecated');
+
+    expect(shim.hasOwnProperty).toBe(Object.prototype.hasOwnProperty);
+    expect(shim.isPrototypeOf).toBe(Object.prototype.isPrototypeOf);
+
+    expect(deprecated).not.toHaveBeenCalled();
+  });
 });

spec/core/integration/CustomAsyncMatchersSpec.js

@@ -147,4 +147,27 @@ describe('Custom Async Matchers (Integration)', function() {
     env.addReporter({ specDone: specExpectations, jasmineDone: done });
     env.execute();
   });
+
+  it('logs a deprecation warning if the matcher factory takes two arguments', function (done) {
+    var matcherFactory = function (matchersUtil, customEqualityTesters) {
+      return { compare: function () {} };
+    };
+
+    spyOn(env, 'deprecated');
+
+    env.it('a spec', function() {
+      env.addAsyncMatchers({toBeFoo: matcherFactory});
+    });
+
+    function jasmineDone() {
+      expect(env.deprecated).toHaveBeenCalledWith('The matcher factory for "toBeFoo" ' +
+        'accepts custom equality testers, but this parameter will no longer be passed ' +
+        'in a future release. ' +
+        'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
+      done();
+    }
+
+    env.addReporter({jasmineDone: jasmineDone});
+    env.execute();
+  });
 });

spec/core/integration/CustomMatchersSpec.js

@@ -88,6 +88,7 @@ describe("Custom Matchers (Integration)", function () {
   it("supports asymmetric equality testers that take a list of custom equality testers", function(done) {
     // TODO: remove this in the next major release.
     spyOn(jasmineUnderTest, 'getEnv').and.returnValue(env);
+    spyOn(env, 'deprecated'); // suppress warnings
 
     env.it("spec using custom asymmetric equality tester", function() {
       var customEqualityFn = function(a, b) {
@@ -265,4 +266,27 @@ describe("Custom Matchers (Integration)", function () {
     env.addReporter({specDone: specExpectations, jasmineDone: done});
     env.execute();
   });
+
+  it('logs a deprecation warning if the matcher factory takes two arguments', function(done) {
+    var matcherFactory = function (matchersUtil, customEqualityTesters) {
+      return { compare: function() {} };
+    };
+
+    spyOn(env, 'deprecated');
+
+    env.it('a spec', function() {
+      env.addMatchers({toBeFoo: matcherFactory});
+    });
+
+    function jasmineDone() {
+      expect(env.deprecated).toHaveBeenCalledWith('The matcher factory for "toBeFoo" ' +
+        'accepts custom equality testers, but this parameter will no longer be passed ' +
+        'in a future release. ' +
+        'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
+      done();
+    }
+
+    env.addReporter({jasmineDone: jasmineDone});
+    env.execute();
+  });
 });

spec/core/matchers/matchersUtilSpec.js

@@ -44,14 +44,16 @@ describe("matchersUtil", function() {
       }
 
       it('is symmetric', function() {
+        var matchersUtil = new jasmineUnderTest.MatchersUtil();
+
         fc.assert(
           fc.property(
             fc.anything(basicAnythingSettings()),
             fc.anything(basicAnythingSettings()),
             function(a, b) {
               return (
-                jasmineUnderTest.matchersUtil.equals(a, b) ===
+                matchersUtil.equals(a, b) ===
-                jasmineUnderTest.matchersUtil.equals(b, a)
+                matchersUtil.equals(b, a)
               );
             }
           ),
@@ -63,13 +65,14 @@ describe("matchersUtil", function() {
       });
 
       it('is reflexive', function() {
+        var matchersUtil = new jasmineUnderTest.MatchersUtil();
         var anythingSettings = basicAnythingSettings();
         anythingSettings.withMap = false;
         fc.assert(
           fc.property(fc.dedup(fc.anything(anythingSettings), 2), function(
             values
           ) {
-            return jasmineUnderTest.matchersUtil.equals(values[0], values[1]);
+            return matchersUtil.equals(values[0], values[1]);
           }),
           {
             numRuns: numRuns()
@@ -465,6 +468,8 @@ describe("matchersUtil", function() {
       var tester = function(a, b) { return true; },
         matchersUtil = new jasmineUnderTest.MatchersUtil();
 
+      spyOn(jasmineUnderTest.getEnv(), 'deprecated'); // suppress warning
+
       expect(matchersUtil.equals(1, 2, [tester])).toBe(true);
     });
 
@@ -486,6 +491,7 @@ describe("matchersUtil", function() {
 
       it("passes for two empty Objects", function () {
         var matchersUtil = new jasmineUnderTest.MatchersUtil();
+        spyOn(jasmineUnderTest.getEnv(), 'deprecated'); // suppress warning
         expect(matchersUtil.equals({}, {}, [tester])).toBe(true);
       });
     });
@@ -504,6 +510,8 @@ describe("matchersUtil", function() {
       var tester = function(a, b) { return false; },
         matchersUtil = new jasmineUnderTest.MatchersUtil();
 
+      spyOn(jasmineUnderTest.getEnv(), 'deprecated'); // suppress warning
+
       expect(matchersUtil.equals(1, 1, [tester])).toBe(false);
     });
 
@@ -520,6 +528,8 @@ describe("matchersUtil", function() {
         symmetricTester = function(a, b) { return false; },
         matchersUtil = new jasmineUnderTest.MatchersUtil();
 
+      spyOn(jasmineUnderTest.getEnv(), 'deprecated'); // suppress warning
+
       expect(matchersUtil.equals(asymmetricTester, true, [symmetricTester])).toBe(true);
       expect(matchersUtil.equals(true, asymmetricTester, [symmetricTester])).toBe(true);
     });
@@ -541,6 +551,7 @@ describe("matchersUtil", function() {
             matchersUtil = new jasmineUnderTest.MatchersUtil(),
             shim;
 
+          spyOn(jasmineUnderTest.getEnv(), 'deprecated'); // suppress warning
           matchersUtil.equals(true, asymmetricTester, [symmetricTester]);
           shim = asymmetricTester.asymmetricMatch.calls.argsFor(0)[1];
           expect(shim).toEqual(jasmine.any(jasmineUnderTest.MatchersUtil));
@@ -556,6 +567,7 @@ describe("matchersUtil", function() {
             matchersUtil = new jasmineUnderTest.MatchersUtil({customTesters: [symmetricTester], pp: function() {}}),
             shim;
 
+          spyOn(jasmineUnderTest.getEnv(), 'deprecated'); // suppress warning
           matchersUtil.equals(true, asymmetricTester);
           shim = asymmetricTester.asymmetricMatch.calls.argsFor(0)[1];
           expect(shim).toEqual(jasmine.any(jasmineUnderTest.MatchersUtil));
@@ -809,10 +821,11 @@ describe("matchersUtil", function() {
           },
           actual = {x: 42},
           expected = {x: tester},
-          diffBuilder = jasmine.createSpyObj('diffBuilder', ['recordMismatch', 'withPath', 'setRoots']);
+          diffBuilder = jasmine.createSpyObj('diffBuilder', ['recordMismatch', 'withPath', 'setRoots']),
+          matchersUtil = new jasmineUnderTest.MatchersUtil();
 
         diffBuilder.withPath.and.callFake(function(p, block) { block(); });
-        jasmineUnderTest.matchersUtil.equals(actual, expected, [], diffBuilder);
+        matchersUtil.equals(actual, expected, diffBuilder);
 
         expect(diffBuilder.setRoots).toHaveBeenCalledWith(actual, expected);
         expect(diffBuilder.withPath).toHaveBeenCalledWith('x', jasmine.any(Function));
@@ -825,9 +838,11 @@ describe("matchersUtil", function() {
           },
           actual = {x: 42},
           expected = {x: tester},
-          diffBuilder = jasmine.createSpyObj('diffBuilder', ['recordMismatch', 'withPath', 'setRoots']);
+          diffBuilder = jasmine.createSpyObj('diffBuilder', ['recordMismatch', 'withPath', 'setRoots']),
+          matchersUtil = new jasmineUnderTest.MatchersUtil();
+
         diffBuilder.withPath.and.callFake(function(p, block) { block(); });
-        jasmineUnderTest.matchersUtil.equals(actual, expected, [], diffBuilder);
+        matchersUtil.equals(actual, expected, diffBuilder);
 
         expect(diffBuilder.setRoots).toHaveBeenCalledWith(actual, expected);
         expect(diffBuilder.withPath).toHaveBeenCalledWith('x', jasmine.any(Function));
@@ -835,11 +850,34 @@ describe("matchersUtil", function() {
       });
     });
 
+    it('logs a deprecation warning when custom equality testers are passed', function() {
+      var matchersUtil = new jasmineUnderTest.MatchersUtil(),
+        deprecated = spyOn(jasmineUnderTest.getEnv(), 'deprecated');
+
+      matchersUtil.equals(0, 0, []);
+
+      expect(deprecated).toHaveBeenCalledWith('Passing custom equality testers ' +
+        'to MatchersUtil#equals is deprecated. ' +
+        'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
+    });
+
+    it('logs a deprecation warning when a diffBuilder is provided as the fourth argument', function() {
+      var matchersUtil = new jasmineUnderTest.MatchersUtil(),
+        deprecated = spyOn(jasmineUnderTest.getEnv(), 'deprecated');
+
+      matchersUtil.equals(0, 0, null, new jasmineUnderTest.NullDiffBuilder());
+
+      expect(deprecated).toHaveBeenCalledWith('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.');
+    });
+
     it('uses a diffBuilder if one is provided as the fourth argument', function() {
       // TODO: remove this in the next major release.
       var diffBuilder = new jasmineUnderTest.DiffBuilder(),
         matchersUtil = new jasmineUnderTest.MatchersUtil();
 
+      spyOn(jasmineUnderTest.getEnv(), 'deprecated'); // suppress warning
       spyOn(diffBuilder, 'recordMismatch');
       spyOn(diffBuilder, 'withPath').and.callThrough();
 
@@ -893,9 +931,14 @@ describe("matchersUtil", function() {
     it("uses custom equality testers if passed to contains and actual is an Array", function() {
       // TODO: remove this in the next major release.
       var customTester = function(a, b) {return true;},
-        matchersUtil = new jasmineUnderTest.MatchersUtil();
+        matchersUtil = new jasmineUnderTest.MatchersUtil(),
+        deprecated = spyOn(jasmineUnderTest.getEnv(), 'deprecated');
 
         expect(matchersUtil.contains([1, 2], 3, [customTester])).toBe(true);
+
+      expect(deprecated).toHaveBeenCalledWith('Passing custom equality testers ' +
+        'to MatchersUtil#contains is deprecated. ' +
+        'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.');
     });
 
     it("uses custom equality testers if passed to the constructor and actual is an Array", function() {

spec/helpers/integrationMatchers.js

@@ -42,9 +42,9 @@
                 : 'Expected runnable "' +
                   fullName +
                   '" to have failures ' +
-                  jasmine.pp(expectedFailures) +
+                  jasmine.basicPrettyPrinter_(expectedFailures) +
                   ' but it had ' +
-                  jasmine.pp(foundFailures)
+                  jasmine.basicPrettyPrinter_(foundFailures)
             };
           }
         };

src/core/Env.js

@@ -278,6 +278,17 @@ getJasmineRequireObj().Env = function(j$) {
         runnableResources[currentRunnable().id].customMatchers;
 
       for (var matcherName in matchersToAdd) {
+        if (matchersToAdd[matcherName].length > 1) {
+          self.deprecated(
+            'The matcher factory for "' +
+              matcherName +
+              '" ' +
+              'accepts custom equality testers, but this parameter will no longer be ' +
+              'passed in a future release. ' +
+              'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
+          );
+        }
+
         customMatchers[matcherName] = matchersToAdd[matcherName];
       }
     };
@@ -292,6 +303,17 @@ getJasmineRequireObj().Env = function(j$) {
         runnableResources[currentRunnable().id].customAsyncMatchers;
 
       for (var matcherName in matchersToAdd) {
+        if (matchersToAdd[matcherName].length > 1) {
+          self.deprecated(
+            'The matcher factory for "' +
+              matcherName +
+              '" ' +
+              'accepts custom equality testers, but this parameter will no longer be ' +
+              'passed in a future release. ' +
+              'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
+          );
+        }
+
         customAsyncMatchers[matcherName] = matchersToAdd[matcherName];
       }
     };

src/core/ExceptionFormatter.js

@@ -90,7 +90,7 @@ getJasmineRequireObj().ExceptionFormatter = function(j$) {
       }
 
       if (!empty) {
-        return 'error properties: ' + j$.pp(result) + '\n';
+        return 'error properties: ' + j$.basicPrettyPrinter_(result) + '\n';
       }
 
       return '';

src/core/Spy.js

@@ -164,7 +164,7 @@ getJasmineRequireObj().Spy = function(j$) {
             "Spy '" +
               strategyArgs.name +
               "' received a call with arguments " +
-              j$.pp(Array.prototype.slice.call(args)) +
+              j$.basicPrettyPrinter_(Array.prototype.slice.call(args)) +
               ' but all configured strategies specify other arguments.'
           );
         } else {

src/core/asymmetricEqualityTesterArgCompatShim.js

@@ -56,10 +56,10 @@ getJasmineRequireObj().asymmetricEqualityTesterArgCompatShim = function(j$) {
       i,
       k;
 
-    copy(self, customEqualityTesters, 'length');
+    copyAndDeprecate(self, customEqualityTesters, 'length');
 
     for (i = 0; i < customEqualityTesters.length; i++) {
-      copy(self, customEqualityTesters, i);
+      copyAndDeprecate(self, customEqualityTesters, i);
     }
 
     var props = arrayProps();
@@ -67,16 +67,22 @@ getJasmineRequireObj().asymmetricEqualityTesterArgCompatShim = function(j$) {
     for (i = 0; i < props.length; i++) {
       k = props[i];
       if (k !== 'length') {
-        copy(self, Array.prototype, k);
+        copyAndDeprecate(self, Array.prototype, k);
       }
     }
 
     return self;
   }
 
-  function copy(dest, src, propName) {
+  function copyAndDeprecate(dest, src, propName) {
     Object.defineProperty(dest, propName, {
       get: function() {
+        j$.getEnv().deprecated(
+          'The second argument to asymmetricMatch is now a ' +
+            'MatchersUtil. Using it as an array of custom equality testers is ' +
+            'deprecated and will stop working in a future release. ' +
+            'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
+        );
         return src[propName];
       }
     });

src/core/asymmetric_equality/ArrayContaining.js

@@ -5,7 +5,7 @@ getJasmineRequireObj().ArrayContaining = function(j$) {
 
   ArrayContaining.prototype.asymmetricMatch = function(other, matchersUtil) {
     if (!j$.isArray_(this.sample)) {
-      throw new Error('You must provide an array to arrayContaining, not ' + j$.pp(this.sample) + '.');
+      throw new Error('You must provide an array to arrayContaining, not ' + j$.basicPrettyPrinter_(this.sample) + '.');
     }
 
     // If the actual parameter is not an array, we can fail immediately, since it couldn't

src/core/asymmetric_equality/ArrayWithExactContents.js

@@ -6,7 +6,7 @@ getJasmineRequireObj().ArrayWithExactContents = function(j$) {
 
   ArrayWithExactContents.prototype.asymmetricMatch = function(other, matchersUtil) {
     if (!j$.isArray_(this.sample)) {
-      throw new Error('You must provide an array to arrayWithExactContents, not ' + j$.pp(this.sample) + '.');
+      throw new Error('You must provide an array to arrayWithExactContents, not ' + j$.basicPrettyPrinter_(this.sample) + '.');
     }
 
     if (this.sample.length !== other.length) {

src/core/asymmetric_equality/MapContaining.js

@@ -1,7 +1,7 @@
 getJasmineRequireObj().MapContaining = function(j$) {
   function MapContaining(sample) {
     if (!j$.isMap(sample)) {
-      throw new Error('You must provide a map to `mapContaining`, not ' + j$.pp(sample));
+      throw new Error('You must provide a map to `mapContaining`, not ' + j$.basicPrettyPrinter_(sample));
     }
 
     this.sample = sample;

src/core/asymmetric_equality/SetContaining.js

@@ -1,7 +1,7 @@
 getJasmineRequireObj().SetContaining = function(j$) {
   function SetContaining(sample) {
     if (!j$.isSet(sample)) {
-      throw new Error('You must provide a set to `setContaining`, not ' + j$.pp(sample));
+      throw new Error('You must provide a set to `setContaining`, not ' + j$.basicPrettyPrinter_(sample));
     }
 
     this.sample = sample;

src/core/matchers/matchersUtil.js

@@ -1,6 +1,4 @@
 getJasmineRequireObj().MatchersUtil = function(j$) {
-  // TODO: convert all uses of j$.pp to use the injected pp
-
   /**
    * _Note:_ Do not construct this directly. Jasmine will construct one and
    * pass it to matchers and asymmetric equality testers.
@@ -30,10 +28,17 @@ getJasmineRequireObj().MatchersUtil = function(j$) {
    * @name MatchersUtil#contains
    * @param {*} haystack The collection to search
    * @param {*} needle The value to search for
-   * @param [customTesters] An array of custom equality testers
+   * @param [customTesters] An array of custom equality testers. Deprecated.
+   * As of 3.6 this parameter no longer needs to be passed. It will be removed in 4.0.
    * @returns {boolean} True if `needle` was found in `haystack`
    */
   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.');
+    }
+
     if (j$.isSet(haystack)) {
       return haystack.has(needle);
     }
@@ -122,7 +127,8 @@ getJasmineRequireObj().MatchersUtil = function(j$) {
    * @name MatchersUtil#equals
    * @param {*} a The first value to compare
    * @param {*} b The second value to compare
-   * @param [customTesters] An array of custom equality testers
+   * @param [customTesters] An array of custom equality testers. Deprecated.
+   * As of 3.6 this parameter no longer needs to be passed. It will be removed in 4.0.
    * @returns {boolean} True if the values are equal
    */
   MatchersUtil.prototype.equals = function(a, b, customTestersOrDiffBuilder, diffBuilderOrNothing) {
@@ -131,6 +137,18 @@ getJasmineRequireObj().MatchersUtil = function(j$) {
     if (isDiffBuilder(customTestersOrDiffBuilder)) {
       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.');
+      }
+
+      if (diffBuilderOrNothing) {
+        j$.getEnv().deprecated('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.');
+      }
+
       customTesters = customTestersOrDiffBuilder;
       diffBuilder = diffBuilderOrNothing;
     }

src/core/requireCore.js

@@ -55,11 +55,34 @@ var getJasmineRequireObj = (function(jasmineGlobal) {
       j$
     );
     j$.makePrettyPrinter = jRequire.makePrettyPrinter(j$);
-    j$.pp = j$.makePrettyPrinter();
+    j$.basicPrettyPrinter_ = j$.makePrettyPrinter();
+    Object.defineProperty(j$, 'pp', {
+      get: function() {
+        j$.getEnv().deprecated(
+          '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 " +
+            'instead. See ' +
+            '<https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
+        );
+        return j$.basicPrettyPrinter_;
+      }
+    });
     j$.MatchersUtil = jRequire.MatchersUtil(j$);
-    j$.matchersUtil = new j$.MatchersUtil({
+    var staticMatchersUtil = new j$.MatchersUtil({
       customTesters: [],
-      pp: j$.pp
+      pp: j$.basicPrettyPrinter_
+    });
+    Object.defineProperty(j$, 'matchersUtil', {
+      get: function() {
+        j$.getEnv().deprecated(
+          '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. " +
+            'See <https://jasmine.github.io/tutorials/upgrading_to_4.0> for details.'
+        );
+        return staticMatchersUtil;
+      }
     });
 
     j$.ObjectContaining = jRequire.ObjectContaining(j$);