Don't require matchers and asymmetric equality testers to pass custom object formatters back to Jasmine

This makes it easier to write high quality matchers and asymmetric equality
testers, and is also a step toward supporting custom object formatters.

Previously, Jasmine passed custom object formatters as the second argument
to matcher factories and as and the second argument to asymmetric equality
testers' `asymmetricMatch` method. Matchers and asymmetric equality testers
were responsible for passing the custom object formatters to methods like
`matchersUtil#equals`:

  function toEqual(util, customEqualityTesters) {
    return {
      compare: function(actual, expected) {
        // ...
        result.pass = util.equals(actual, expected, customEqualityTesters, diffBuilder);

And:

  ArrayContaining.prototype.asymmetricMatch = function(other, customTesters) {
    // ...
    for (var i = 0; i < this.sample.length; i++) {
      var item = this.sample[i];
      if (!j$.matchersUtil.contains(other, item, customTesters)) {
        return false;
      }
    }

With this change, that is no longer necessary. Matchers and asymmetric
equality testers can ignore the existence of custom equality testers and
still fully support them:

  function toEqual(util) {
    return {
      compare: function(actual, expected) {
        // ...
        result.pass = util.equals(actual, expected, diffBuilder);

And:

  ArrayContaining.prototype.asymmetricMatch = function(other, matchersUtil) {
    // ...
    for (var i = 0; i < this.sample.length; i++) {
      var item = this.sample[i];
      if (!matchersUtil.contains(other, item)) {
        return false;
      }
    }

The old interfaces are still supported, for now, but will be deprecated
in a future commit and removed in the next major release after that.

In addition to making matchers and custom equality testers simpler,
this change sets the stage for adding support for custom object
formatters. Those will be architecturally similar to custom equality
testers, and by injecting a `MatchersUtil` instance everywhere we can
add them without requiring user code to pass them around as used to be
the case with custom object formatters.

spec/core/integration/CustomAsyncMatchersSpec.js

@@ -111,4 +111,36 @@ describe('Custom Async Matchers (Integration)', function() {
     env.addReporter({ specDone: specExpectations, jasmineDone: done });
     env.execute();
   });
+
+  it("provides custom equality testers to the matcher factory via matchersUtil", function(done) {
+    jasmine.getEnv().requirePromises();
+
+    var matcherFactory = function (matchersUtil) {
+        return {
+          compare: function (actual, expected) {
+            return Promise.resolve({pass: matchersUtil.equals(actual[0], expected)});
+          }
+        };
+      },
+      customEqualityFn = jasmine.createSpy("customEqualityFn").and.callFake(function (a, b) {
+        return a.toString() === b;
+      });
+
+    env.it("spec with expectation", function() {
+      env.addCustomEqualityTester(customEqualityFn);
+      env.addAsyncMatchers({
+        toBeArrayWithFirstElement: matcherFactory
+      });
+
+      return env.expectAsync([1, 2]).toBeArrayWithFirstElement("1");
+    });
+
+    var specExpectations = function(result) {
+      expect(customEqualityFn).toHaveBeenCalledWith(1, "1");
+      expect(result.failedExpectations).toEqual([]);
+    };
+
+    env.addReporter({ specDone: specExpectations, jasmineDone: done });
+    env.execute();
+  });
 });

spec/core/integration/CustomMatchersSpec.js

@@ -1,19 +1,19 @@
-describe("Custom Matchers (Integration)", function() {
+describe("Custom Matchers (Integration)", function () {
   var env;
   var fakeTimer;
 
-  beforeEach(function() {
+  beforeEach(function () {
     env = new jasmineUnderTest.Env();
     env.configure({random: false});
   });
 
-  it("allows adding more matchers local to a spec", function(done) {
-    env.it('spec defining a custom matcher', function() {
+  it("allows adding more matchers local to a spec", function (done) {
+    env.it('spec defining a custom matcher', function () {
       env.addMatchers({
-        matcherForSpec: function() {
+        matcherForSpec: function () {
           return {
-            compare: function(actual, expected) {
-              return { pass: false, message: "matcherForSpec: actual: " + actual + "; expected: " + expected };
+            compare: function (actual, expected) {
+              return {pass: false, message: "matcherForSpec: actual: " + actual + "; expected: " + expected};
             }
           }
         }
@@ -83,6 +83,8 @@ 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);
+
     env.it("spec using custom asymmetric equality tester", function() {
       var customEqualityFn = function(a, b) {
         if (a === 2 && b === "two") {
@@ -229,4 +231,34 @@ describe("Custom Matchers (Integration)", function() {
     env.addReporter({ specDone: specExpectations, jasmineDone: done });
     env.execute();
   });
+
+  it("provides custom equality testers to the matcher factory via matchersUtil", function (done) {
+    var matcherFactory = function (matchersUtil) {
+        return {
+          compare: function (actual, expected) {
+            return {pass: matchersUtil.equals(actual[0], expected)};
+          }
+        };
+      },
+      customEqualityFn = jasmine.createSpy("customEqualityFn").and.callFake(function (a, b) {
+        return a.toString() === b;
+      });
+
+    env.it("spec with expectation", function () {
+      env.addCustomEqualityTester(customEqualityFn);
+      env.addMatchers({
+        toBeArrayWithFirstElement: matcherFactory
+      });
+
+      env.expect([1, 2]).toBeArrayWithFirstElement("1");
+    });
+
+    var specExpectations = function (result) {
+      expect(customEqualityFn).toHaveBeenCalledWith(1, "1");
+      expect(result.failedExpectations).toEqual([]);
+    };
+
+    env.addReporter({specDone: specExpectations, jasmineDone: done});
+    env.execute();
+  });
 });

spec/core/integration/EnvSpec.js

@@ -2149,7 +2149,7 @@ describe("Env integration", function() {
         env.it('is a spec without any expectations', function() {
           // does nothing, just a mock spec without expectations
         });
-        
+
       });
 
       it('should report "failed" status if "failSpecWithNoExpectations" is enabled', function(done) {
@@ -2556,4 +2556,33 @@ describe("Env integration", function() {
 
     env.execute();
   });
+
+  it("supports asymmetric equality testers that take a matchersUtil", function(done) {
+    var env = new jasmineUnderTest.Env();
+
+    env.it("spec using custom asymmetric equality tester", function() {
+      var customEqualityFn = function(a, b) {
+        if (a === 2 && b === "two") {
+          return true;
+        }
+      };
+      var arrayWithFirstElement = function(sample) {
+        return {
+          asymmetricMatch: function (actual, matchersUtil) {
+            return matchersUtil.equals(sample, actual[0]);
+          }
+        };
+      };
+
+      env.addCustomEqualityTester(customEqualityFn);
+      env.expect(["two"]).toEqual(arrayWithFirstElement(2));
+    });
+
+    var specExpectations = function(result) {
+      expect(result.status).toEqual('passed');
+    };
+
+    env.addReporter({ specDone: specExpectations, jasmineDone: done });
+    env.execute();
+  });
 });

spec/core/integration/MatchersSpec.js

@@ -449,7 +449,10 @@ describe('Matchers (Integration)', function() {
 
   describe('toThrow', function() {
     verifyPasses(function(env) {
-      env.expect(function() { throw new Error(); }).toThrow();
+      env.addCustomEqualityTester(function(a, b) {
+        return a.toString() === b.toString();
+      });
+      env.expect(function() { throw '5'; }).toThrow(5);
     });
 
     verifyFails(function(env) {