Add custom async matchers

lib/jasmine-core/jasmine.js

@@ -1172,6 +1172,19 @@ getJasmineRequireObj().Env = function(j$) {
       }
     };
 
+    this.addAsyncMatchers = function(matchersToAdd) {
+      if (!currentRunnable()) {
+        throw new Error(
+          'Async Matchers must be added in a before function or a spec'
+        );
+      }
+      var customAsyncMatchers =
+        runnableResources[currentRunnable().id].customAsyncMatchers;
+      for (var matcherName in matchersToAdd) {
+        customAsyncMatchers[matcherName] = matchersToAdd[matcherName];
+      }
+    };
+
     j$.Expectation.addCoreMatchers(j$.matchers);
     j$.Expectation.addAsyncCoreMatchers(j$.asyncMatchers);
 
@@ -1203,6 +1216,7 @@ getJasmineRequireObj().Env = function(j$) {
       return j$.Expectation.asyncFactory({
         util: j$.matchersUtil,
         customEqualityTesters: runnableResources[spec.id].customEqualityTesters,
+        customAsyncMatchers: runnableResources[spec.id].customAsyncMatchers,
         actual: actual,
         addExpectationResult: addExpectationResult
       });
@@ -1217,6 +1231,7 @@ getJasmineRequireObj().Env = function(j$) {
         spies: [],
         customEqualityTesters: [],
         customMatchers: {},
+        customAsyncMatchers: {},
         customSpyStrategies: {},
         defaultStrategyFn: undefined
       };
@@ -1228,6 +1243,9 @@ getJasmineRequireObj().Env = function(j$) {
         resources.customMatchers = j$.util.clone(
           runnableResources[parentRunnableId].customMatchers
         );
+        resources.customAsyncMatchers = j$.util.clone(
+          runnableResources[parentRunnableId].customAsyncMatchers
+        );
         resources.defaultStrategyFn =
           runnableResources[parentRunnableId].defaultStrategyFn;
       }
@@ -3235,12 +3253,6 @@ getJasmineRequireObj().ExceptionFormatter = function(j$) {
 };
 
 getJasmineRequireObj().Expectation = function(j$) {
-  var promiseForMessage = {
-    jasmineToString: function() {
-      return 'a promise';
-    }
-  };
-
   /**
    * Matchers that come with Jasmine out of the box.
    * @namespace matchers
@@ -3298,8 +3310,12 @@ getJasmineRequireObj().Expectation = function(j$) {
       );
     }
 
-    if (!j$.isPromiseLike(this.expector.actual)) {
+    var customAsyncMatchers = options.customAsyncMatchers || {};
-      throw new Error('Expected expectAsync to be called with a promise.');
+    for (var matcherName in customAsyncMatchers) {
+      this[matcherName] = wrapAsyncCompare(
+        matcherName,
+        customAsyncMatchers[matcherName]
+      );
     }
   }
 
@@ -3349,7 +3365,7 @@ getJasmineRequireObj().Expectation = function(j$) {
       return this.expector
         .compare(name, matcherFactory, arguments)
         .then(function(result) {
-          self.expector.processResult(result, errorForStack, promiseForMessage);
+          self.expector.processResult(result, errorForStack);
         });
     };
   }
@@ -3404,7 +3420,7 @@ getJasmineRequireObj().Expectation = function(j$) {
         return matcher.compare.apply(this, arguments).then(negate);
       }
 
-      return defaultNegativeCompare;
+      return matcher.negativeCompare || defaultNegativeCompare;
     },
     buildFailureMessage: negatedFailureMessage
   };
@@ -3621,12 +3637,7 @@ getJasmineRequireObj().Expector = function(j$) {
     return result;
   };
 
-  Expector.prototype.processResult = function(
+  Expector.prototype.processResult = function(result, errorForStack) {
-    result,
-    errorForStack,
-    actualOverride
-  ) {
-    this.args[0] = actualOverride || this.args[0];
     var message = this.buildMessage(result);
 
     if (this.expected.length === 1) {
@@ -3754,9 +3765,12 @@ getJasmineRequireObj().toBeRejected = function(j$) {
    * @example
    * return expectAsync(aPromise).toBeRejected();
    */
-  return function toBeResolved(util) {
+  return function toBeRejected(util) {
     return {
       compare: function(actual) {
+        if (!j$.isPromiseLike(actual)) {
+          throw new Error('Expected toBeRejected to be called on a promise.');
+        }
         return actual.then(
           function() { return {pass: false}; },
           function() { return {pass: true}; }
@@ -3782,6 +3796,10 @@ getJasmineRequireObj().toBeRejectedWith = function(j$) {
   return function toBeRejectedWith(util, customEqualityTesters) {
     return {
       compare: function(actualPromise, expectedValue) {
+        if (!j$.isPromiseLike(actualPromise)) {
+          throw new Error('Expected toBeRejectedWith to be called on a promise.');
+        }
+
         function prefix(passed) {
           return 'Expected a promise ' +
             (passed ? 'not ' : '') +
@@ -3833,6 +3851,10 @@ getJasmineRequireObj().toBeRejectedWithError = function(j$) {
   return function toBeRejectedWithError() {
     return {
       compare: function(actualPromise, arg1, arg2) {
+        if (!j$.isPromiseLike(actualPromise)) {
+          throw new Error('Expected toBeRejectedWithError to be called on a promise.');
+        }
+
         var expected = getExpectedFromArgs(arg1, arg2);
 
         return actualPromise.then(
@@ -3919,6 +3941,10 @@ getJasmineRequireObj().toBeResolved = function(j$) {
   return function toBeResolved(util) {
     return {
       compare: function(actual) {
+        if (!j$.isPromiseLike(actual)) {
+          throw new Error('Expected toBeResolved to be called on a promise.');
+        }
+
         return actual.then(
           function() { return {pass: true}; },
           function() { return {pass: false}; }
@@ -3944,6 +3970,10 @@ getJasmineRequireObj().toBeResolvedTo = function(j$) {
   return function toBeResolvedTo(util, customEqualityTesters) {
     return {
       compare: function(actualPromise, expectedValue) {
+        if (!j$.isPromiseLike(actualPromise)) {
+          throw new Error('Expected toBeResolvedTo to be called on a promise.');
+        }
+
         function prefix(passed) {
           return 'Expected a promise ' +
             (passed ? 'not ' : '') +
@@ -6731,6 +6761,20 @@ getJasmineRequireObj().interface = function(jasmine, env) {
     return env.addMatchers(matchers);
   };
 
+  /**
+   * Add custom async matchers for the current scope of specs.
+   *
+   * _Note:_ This is only callable from within a {@link beforeEach}, {@link it}, or {@link beforeAll}.
+   * @name jasmine.addMatchers
+   * @since 3.5.0
+   * @function
+   * @param {Object} matchers - Keys from this object will be the new async matcher names.
+   * @see custom_matcher
+   */
+  jasmine.addAsyncMatchers = function(matchers) {
+    return env.addAsyncMatchers(matchers);
+  };
+
   /**
    * Get the currently booted mock {Clock} for this Jasmine environment.
    * @name jasmine.clock

spec/core/AsyncExpectationSpec.js

@@ -16,16 +16,6 @@ describe('AsyncExpectation', function() {
         'expectAsync is unavailable because the environment does not support promises.'
       );
     });
-
-    it('throws an Error if the argument is not a promise', function() {
-      jasmine.getEnv().requirePromises();
-      function f() {
-        jasmineUnderTest.Expectation.asyncFactory({ actual: 'not a promise' });
-      }
-      expect(f).toThrowError(
-        'Expected expectAsync to be called with a promise.'
-      );
-    });
   });
 
   describe('#not', function() {
@@ -45,7 +35,7 @@ describe('AsyncExpectation', function() {
           false,
           jasmine.objectContaining({
             passed: false,
-            message: 'Expected a promise not to be resolved.'
+            message: 'Expected [object Promise] not to be resolved.'
           })
         );
       });
@@ -203,7 +193,8 @@ describe('AsyncExpectation', function() {
           expect(addExpectationResult).toHaveBeenCalledWith(
             false,
             jasmine.objectContaining({
-              message: 'Some context: Expected a promise not to be resolved.'
+              message:
+                'Some context: Expected [object Promise] not to be resolved.'
             })
           );
         });
@@ -235,6 +226,611 @@ describe('AsyncExpectation', function() {
     });
   });
 
+  describe('async matchers', function() {
+    it('makes custom matchers available to this expectation', function() {
+      var asyncMatchers = {
+          toFoo: function() {},
+          toBar: function() {}
+        },
+        expectation;
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        customAsyncMatchers: asyncMatchers
+      });
+
+      expect(expectation.toFoo).toBeDefined();
+      expect(expectation.toBar).toBeDefined();
+    });
+
+    it("wraps matchers's compare functions, passing in matcher dependencies", function() {
+      jasmine.getEnv().requirePromises();
+
+      var fakeCompare = function() {
+          return Promise.resolve({ pass: true });
+        },
+        matcherFactory = jasmine
+          .createSpy('matcher')
+          .and.returnValue({ compare: fakeCompare }),
+        matchers = {
+          toFoo: matcherFactory
+        },
+        util = {
+          buildFailureMessage: jasmine.createSpy('buildFailureMessage')
+        },
+        customEqualityTesters = ['a'],
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        expectation;
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        util: util,
+        customAsyncMatchers: matchers,
+        customEqualityTesters: customEqualityTesters,
+        actual: 'an actual',
+        addExpectationResult: addExpectationResult
+      });
+
+      return expectation.toFoo('hello').then(function() {
+        expect(matcherFactory).toHaveBeenCalledWith(
+          util,
+          customEqualityTesters
+        );
+      });
+    });
+
+    it("wraps matchers's compare functions, passing the actual and expected", function() {
+      jasmine.getEnv().requirePromises();
+
+      var fakeCompare = jasmine
+          .createSpy('fake-compare')
+          .and.returnValue(Promise.resolve({ pass: true })),
+        matchers = {
+          toFoo: function() {
+            return {
+              compare: fakeCompare
+            };
+          }
+        },
+        util = {
+          buildFailureMessage: jasmine.createSpy('buildFailureMessage')
+        },
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        expectation;
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        util: util,
+        customAsyncMatchers: matchers,
+        actual: 'an actual',
+        addExpectationResult: addExpectationResult
+      });
+
+      return expectation.toFoo('hello').then(function() {
+        expect(fakeCompare).toHaveBeenCalledWith('an actual', 'hello');
+      });
+    });
+
+    it('reports a passing result to the spec when the comparison passes', function() {
+      jasmine.getEnv().requirePromises();
+
+      var matchers = {
+          toFoo: function() {
+            return {
+              compare: function() {
+                return Promise.resolve({ pass: true });
+              }
+            };
+          }
+        },
+        util = {
+          buildFailureMessage: jasmine.createSpy('buildFailureMessage')
+        },
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        errorWithStack = new Error('errorWithStack'),
+        expectation;
+
+      spyOn(jasmineUnderTest.util, 'errorWithStack').and.returnValue(
+        errorWithStack
+      );
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        customAsyncMatchers: matchers,
+        util: util,
+        actual: 'an actual',
+        addExpectationResult: addExpectationResult
+      });
+
+      return expectation.toFoo('hello').then(function() {
+        expect(addExpectationResult).toHaveBeenCalledWith(true, {
+          matcherName: 'toFoo',
+          passed: true,
+          message: '',
+          error: undefined,
+          expected: 'hello',
+          actual: 'an actual',
+          errorForStack: errorWithStack
+        });
+      });
+    });
+
+    it('reports a failing result to the spec when the comparison fails', function() {
+      jasmine.getEnv().requirePromises();
+
+      var matchers = {
+          toFoo: function() {
+            return {
+              compare: function() {
+                return Promise.resolve({ pass: false });
+              }
+            };
+          }
+        },
+        util = {
+          buildFailureMessage: function() {
+            return '';
+          }
+        },
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        errorWithStack = new Error('errorWithStack'),
+        expectation;
+
+      spyOn(jasmineUnderTest.util, 'errorWithStack').and.returnValue(
+        errorWithStack
+      );
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        customAsyncMatchers: matchers,
+        util: util,
+        actual: 'an actual',
+        addExpectationResult: addExpectationResult
+      });
+
+      return expectation.toFoo('hello').then(function() {
+        expect(addExpectationResult).toHaveBeenCalledWith(false, {
+          matcherName: 'toFoo',
+          passed: false,
+          expected: 'hello',
+          actual: 'an actual',
+          message: '',
+          error: undefined,
+          errorForStack: errorWithStack
+        });
+      });
+    });
+
+    it('reports a failing result and a custom fail message to the spec when the comparison fails', function() {
+      jasmine.getEnv().requirePromises();
+
+      var matchers = {
+          toFoo: function() {
+            return {
+              compare: function() {
+                return Promise.resolve({
+                  pass: false,
+                  message: 'I am a custom message'
+                });
+              }
+            };
+          }
+        },
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        errorWithStack = new Error('errorWithStack'),
+        expectation;
+
+      spyOn(jasmineUnderTest.util, 'errorWithStack').and.returnValue(
+        errorWithStack
+      );
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        actual: 'an actual',
+        customAsyncMatchers: matchers,
+        addExpectationResult: addExpectationResult
+      });
+
+      return expectation.toFoo('hello').then(function() {
+        expect(addExpectationResult).toHaveBeenCalledWith(false, {
+          matcherName: 'toFoo',
+          passed: false,
+          expected: 'hello',
+          actual: 'an actual',
+          message: 'I am a custom message',
+          error: undefined,
+          errorForStack: errorWithStack
+        });
+      });
+    });
+
+    it('reports a failing result with a custom fail message function to the spec when the comparison fails', function() {
+      jasmine.getEnv().requirePromises();
+
+      var matchers = {
+          toFoo: function() {
+            return {
+              compare: function() {
+                return Promise.resolve({
+                  pass: false,
+                  message: function() {
+                    return 'I am a custom message';
+                  }
+                });
+              }
+            };
+          }
+        },
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        errorWithStack = new Error('errorWithStack'),
+        expectation;
+
+      spyOn(jasmineUnderTest.util, 'errorWithStack').and.returnValue(
+        errorWithStack
+      );
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        customAsyncMatchers: matchers,
+        actual: 'an actual',
+        addExpectationResult: addExpectationResult
+      });
+
+      return expectation.toFoo('hello').then(function() {
+        expect(addExpectationResult).toHaveBeenCalledWith(false, {
+          matcherName: 'toFoo',
+          passed: false,
+          expected: 'hello',
+          actual: 'an actual',
+          message: 'I am a custom message',
+          error: undefined,
+          errorForStack: errorWithStack
+        });
+      });
+    });
+
+    it('reports a passing result to the spec when the comparison fails for a negative expectation', function() {
+      jasmine.getEnv().requirePromises();
+
+      var matchers = {
+          toFoo: function() {
+            return {
+              compare: function() {
+                return Promise.resolve({ pass: false });
+              }
+            };
+          }
+        },
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        actual = 'an actual',
+        errorWithStack = new Error('errorWithStack'),
+        expectation;
+
+      spyOn(jasmineUnderTest.util, 'errorWithStack').and.returnValue(
+        errorWithStack
+      );
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        customAsyncMatchers: matchers,
+        actual: 'an actual',
+        addExpectationResult: addExpectationResult
+      }).not;
+
+      return expectation.toFoo('hello').then(function() {
+        expect(addExpectationResult).toHaveBeenCalledWith(true, {
+          matcherName: 'toFoo',
+          passed: true,
+          message: '',
+          error: undefined,
+          expected: 'hello',
+          actual: actual,
+          errorForStack: errorWithStack
+        });
+      });
+    });
+
+    it('reports a failing result to the spec when the comparison passes for a negative expectation', function() {
+      jasmine.getEnv().requirePromises();
+
+      var matchers = {
+          toFoo: function() {
+            return {
+              compare: function() {
+                return Promise.resolve({ pass: true });
+              }
+            };
+          }
+        },
+        util = {
+          buildFailureMessage: function() {
+            return 'default message';
+          }
+        },
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        actual = 'an actual',
+        errorWithStack = new Error('errorWithStack'),
+        expectation;
+
+      spyOn(jasmineUnderTest.util, 'errorWithStack').and.returnValue(
+        errorWithStack
+      );
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        customAsyncMatchers: matchers,
+        actual: 'an actual',
+        util: util,
+        addExpectationResult: addExpectationResult
+      }).not;
+
+      return expectation.toFoo('hello').then(function() {
+        expect(addExpectationResult).toHaveBeenCalledWith(false, {
+          matcherName: 'toFoo',
+          passed: false,
+          expected: 'hello',
+          actual: actual,
+          message: 'default message',
+          error: undefined,
+          errorForStack: errorWithStack
+        });
+      });
+    });
+
+    it('reports a failing result and a custom fail message to the spec when the comparison passes for a negative expectation', function() {
+      jasmine.getEnv().requirePromises();
+
+      var matchers = {
+          toFoo: function() {
+            return {
+              compare: function() {
+                return Promise.resolve({
+                  pass: true,
+                  message: 'I am a custom message'
+                });
+              }
+            };
+          }
+        },
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        actual = 'an actual',
+        errorWithStack = new Error('errorWithStack'),
+        expectation;
+
+      spyOn(jasmineUnderTest.util, 'errorWithStack').and.returnValue(
+        errorWithStack
+      );
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        customAsyncMatchers: matchers,
+        actual: 'an actual',
+        addExpectationResult: addExpectationResult
+      }).not;
+
+      return expectation.toFoo('hello').then(function() {
+        expect(addExpectationResult).toHaveBeenCalledWith(false, {
+          matcherName: 'toFoo',
+          passed: false,
+          expected: 'hello',
+          actual: actual,
+          message: 'I am a custom message',
+          error: undefined,
+          errorForStack: errorWithStack
+        });
+      });
+    });
+
+    it("reports a passing result to the spec when the 'not' comparison passes, given a negativeCompare", function() {
+      jasmine.getEnv().requirePromises();
+
+      var matchers = {
+          toFoo: function() {
+            return {
+              compare: function() {
+                return Promise.resolve({ pass: true });
+              },
+              negativeCompare: function() {
+                return Promise.resolve({ pass: true });
+              }
+            };
+          }
+        },
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        actual = 'an actual',
+        errorWithStack = new Error('errorWithStack'),
+        expectation;
+
+      spyOn(jasmineUnderTest.util, 'errorWithStack').and.returnValue(
+        errorWithStack
+      );
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        customAsyncMatchers: matchers,
+        actual: 'an actual',
+        addExpectationResult: addExpectationResult
+      }).not;
+
+      return expectation.toFoo('hello').then(function() {
+        expect(addExpectationResult).toHaveBeenCalledWith(true, {
+          matcherName: 'toFoo',
+          passed: true,
+          expected: 'hello',
+          actual: actual,
+          message: '',
+          error: undefined,
+          errorForStack: errorWithStack
+        });
+      });
+    });
+
+    it("reports a failing result and a custom fail message to the spec when the 'not' comparison fails, given a negativeCompare", function() {
+      jasmine.getEnv().requirePromises();
+
+      var matchers = {
+          toFoo: function() {
+            return {
+              compare: function() {
+                return Promise.resolve({ pass: true });
+              },
+              negativeCompare: function() {
+                return Promise.resolve({
+                  pass: false,
+                  message: "I'm a custom message"
+                });
+              }
+            };
+          }
+        },
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        actual = 'an actual',
+        errorWithStack = new Error('errorWithStack'),
+        expectation;
+
+      spyOn(jasmineUnderTest.util, 'errorWithStack').and.returnValue(
+        errorWithStack
+      );
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        customAsyncMatchers: matchers,
+        actual: 'an actual',
+        addExpectationResult: addExpectationResult
+      }).not;
+
+      return expectation.toFoo('hello').then(function() {
+        expect(addExpectationResult).toHaveBeenCalledWith(false, {
+          matcherName: 'toFoo',
+          passed: false,
+          expected: 'hello',
+          actual: actual,
+          message: "I'm a custom message",
+          error: undefined,
+          errorForStack: errorWithStack
+        });
+      });
+    });
+
+    it('reports errorWithStack when a custom error message is returned', function() {
+      jasmine.getEnv().requirePromises();
+
+      var customError = new Error('I am a custom error');
+      var matchers = {
+          toFoo: function() {
+            return {
+              compare: function() {
+                return Promise.resolve({
+                  pass: false,
+                  message: 'I am a custom message',
+                  error: customError
+                });
+              }
+            };
+          }
+        },
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        errorWithStack = new Error('errorWithStack'),
+        expectation;
+
+      spyOn(jasmineUnderTest.util, 'errorWithStack').and.returnValue(
+        errorWithStack
+      );
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        actual: 'an actual',
+        customAsyncMatchers: matchers,
+        addExpectationResult: addExpectationResult
+      });
+
+      return expectation.toFoo('hello').then(function() {
+        expect(addExpectationResult).toHaveBeenCalledWith(false, {
+          matcherName: 'toFoo',
+          passed: false,
+          expected: 'hello',
+          actual: 'an actual',
+          message: 'I am a custom message',
+          error: undefined,
+          errorForStack: errorWithStack
+        });
+      });
+    });
+
+    it("reports a custom message to the spec when a 'not' comparison fails", function() {
+      jasmine.getEnv().requirePromises();
+
+      var matchers = {
+          toFoo: function() {
+            return {
+              compare: function() {
+                return Promise.resolve({
+                  pass: true,
+                  message: 'I am a custom message'
+                });
+              }
+            };
+          }
+        },
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        errorWithStack = new Error('errorWithStack'),
+        expectation;
+
+      spyOn(jasmineUnderTest.util, 'errorWithStack').and.returnValue(
+        errorWithStack
+      );
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        actual: 'an actual',
+        customAsyncMatchers: matchers,
+        addExpectationResult: addExpectationResult
+      }).not;
+
+      return expectation.toFoo('hello').then(function() {
+        expect(addExpectationResult).toHaveBeenCalledWith(false, {
+          matcherName: 'toFoo',
+          passed: false,
+          expected: 'hello',
+          actual: 'an actual',
+          message: 'I am a custom message',
+          error: undefined,
+          errorForStack: errorWithStack
+        });
+      });
+    });
+
+    it("reports a custom message func to the spec when a 'not' comparison fails", function() {
+      jasmine.getEnv().requirePromises();
+
+      var matchers = {
+          toFoo: function() {
+            return {
+              compare: function() {
+                return Promise.resolve({
+                  pass: true,
+                  message: function() {
+                    return 'I am a custom message';
+                  }
+                });
+              }
+            };
+          }
+        },
+        addExpectationResult = jasmine.createSpy('addExpectationResult'),
+        errorWithStack = new Error('errorWithStack'),
+        expectation;
+
+      spyOn(jasmineUnderTest.util, 'errorWithStack').and.returnValue(
+        errorWithStack
+      );
+
+      expectation = jasmineUnderTest.Expectation.asyncFactory({
+        actual: 'an actual',
+        customAsyncMatchers: matchers,
+        addExpectationResult: addExpectationResult
+      }).not;
+
+      return expectation.toFoo('hello').then(function() {
+        expect(addExpectationResult).toHaveBeenCalledWith(false, {
+          matcherName: 'toFoo',
+          passed: false,
+          expected: 'hello',
+          actual: 'an actual',
+          message: 'I am a custom message',
+          error: undefined,
+          errorForStack: errorWithStack
+        });
+      });
+    });
+  });
+
   function dummyPromise() {
     return new Promise(function(resolve, reject) {});
   }

spec/core/integration/CustomAsyncMatchersSpec.js

@@ -0,0 +1,78 @@
+describe('Custom Async Matchers (Integration)', function() {
+  var env;
+
+  beforeEach(function() {
+    env = new jasmineUnderTest.Env();
+    env.configure({random: false});
+  });
+
+  it('passes the spec if the custom async matcher passes', function(done) {
+    jasmine.getEnv().requirePromises();
+
+    env.it('spec using custom async matcher', function() {
+      env.addAsyncMatchers({
+        toBeReal: function() {
+          return { compare: function() { return Promise.resolve({ pass: true }); } };
+        }
+      });
+
+      return env.expectAsync(true).toBeReal();
+    });
+
+    var specExpectations = function(result) {
+      expect(result.status).toEqual('passed');
+    };
+
+    env.addReporter({ specDone: specExpectations, jasmineDone: done });
+    env.execute();
+  });
+
+  it('uses the negative compare function for a negative comparison, if provided', function(done) {
+    jasmine.getEnv().requirePromises();
+
+    env.it('spec with custom negative comparison matcher', function() {
+      env.addAsyncMatchers({
+        toBeReal: function() {
+          return {
+            compare: function() { return Promise.resolve({ pass: true }); },
+            negativeCompare: function() { return Promise.resolve({ pass: true }); }
+          };
+        }
+      });
+
+      return env.expectAsync(true).not.toBeReal();
+    });
+
+    var specExpectations = function(result) {
+      expect(result.status).toEqual('passed');
+    };
+
+    env.addReporter({ specDone: specExpectations, jasmineDone: done });
+    env.execute();
+  });
+
+  it('generates messages with the same rules as built in matchers absent a custom message', function(done) {
+    jasmine.getEnv().requirePromises();
+
+    env.it('spec with an expectation', function() {
+      env.addAsyncMatchers({
+        toBeReal: function() {
+          return {
+            compare: function() {
+              return Promise.resolve({ pass: false });
+            }
+          };
+        }
+      });
+
+      return env.expectAsync('a').toBeReal();
+    });
+
+    var specExpectations = function(result) {
+      expect(result.failedExpectations[0].message).toEqual("Expected 'a' to be real.");
+    };
+
+    env.addReporter({ specDone: specExpectations, jasmineDone: done });
+    env.execute();
+  });
+});

spec/core/integration/EnvSpec.js

@@ -2432,20 +2432,20 @@ describe("Env integration", function() {
       suiteDone: suiteDone,
       jasmineDone: function(result) {
         expect(result.failedExpectations).toEqual([jasmine.objectContaining({
-            message: 'Expected a promise to be rejected.'
+            message: 'Expected [object Promise] to be rejected.'
         })]);
 
         expect(specDone).toHaveBeenCalledWith(jasmine.objectContaining({
           description: 'has an async failure',
           failedExpectations: [jasmine.objectContaining({
-            message: 'Expected a promise to be rejected.'
+            message: 'Expected [object Promise] to be rejected.'
           })]
         }));
 
         expect(suiteDone).toHaveBeenCalledWith(jasmine.objectContaining({
           description: 'a suite',
           failedExpectations: [jasmine.objectContaining({
-            message: 'Expected a promise to be rejected.'
+            message: 'Expected [object Promise] to be rejected.'
           })]
         }));
 

spec/core/matchers/async/toBeRejectedSpec.js

@@ -20,4 +20,17 @@ describe('toBeRejected', function() {
       expect(result).toEqual(jasmine.objectContaining({pass: false}));
     });
   });
+
+  it('fails if actual is not a promise', function() {
+    var matcher = jasmineUnderTest.asyncMatchers.toBeRejected(jasmineUnderTest.matchersUtil),
+      actual = 'not a promise';
+
+    function f() {
+      return matcher.compare(actual);
+    }
+
+    expect(f).toThrowError(
+      'Expected toBeRejected to be called on a promise.'
+    );
+  });
 });

spec/core/matchers/async/toBeRejectedWithErrorSpec.js

@@ -138,4 +138,17 @@ describe('#toBeRejectedWithError', function () {
       }));
     });
   });
+
+  it('fails if actual is not a promise', function() {
+    var matcher = jasmineUnderTest.asyncMatchers.toBeRejectedWithError(jasmineUnderTest.matchersUtil),
+      actual = 'not a promise';
+
+    function f() {
+      return matcher.compare(actual);
+    }
+
+    expect(f).toThrowError(
+      'Expected toBeRejectedWithError to be called on a promise.'
+    );
+  });
 });

spec/core/matchers/async/toBeRejectedWithSpec.js

@@ -60,4 +60,17 @@ describe('#toBeRejectedWith', function () {
       expect(result).toEqual(jasmine.objectContaining({pass: true}));
     });
   });
+
+  it('fails if actual is not a promise', function() {
+    var matcher = jasmineUnderTest.asyncMatchers.toBeRejectedWith(jasmineUnderTest.matchersUtil),
+      actual = 'not a promise';
+
+    function f() {
+      return matcher.compare(actual);
+    }
+
+    expect(f).toThrowError(
+      'Expected toBeRejectedWith to be called on a promise.'
+    );
+  });
 });

spec/core/matchers/async/toBeResolvedSpec.js

@@ -20,4 +20,17 @@ describe('toBeResolved', function() {
       expect(result).toEqual(jasmine.objectContaining({pass: false}));
     });
   });
+
+  it('fails if actual is not a promise', function() {
+    var matcher = jasmineUnderTest.asyncMatchers.toBeResolved(jasmineUnderTest.matchersUtil),
+      actual = 'not a promise';
+
+    function f() {
+      return matcher.compare(actual);
+    }
+
+    expect(f).toThrowError(
+      'Expected toBeResolved to be called on a promise.'
+    );
+  });
 });

spec/core/matchers/async/toBeResolvedToSpec.js

@@ -63,4 +63,17 @@ describe('#toBeResolvedTo', function() {
       expect(result).toEqual(jasmine.objectContaining({pass: true}));
     });
   });
+
+  it('fails if actual is not a promise', function() {
+    var matcher = jasmineUnderTest.asyncMatchers.toBeResolvedTo(jasmineUnderTest.matchersUtil),
+      actual = 'not a promise';
+
+    function f() {
+      return matcher.compare(actual);
+    }
+
+    expect(f).toThrowError(
+      'Expected toBeResolvedTo to be called on a promise.'
+    );
+  });
 });

src/core/Env.js

@@ -266,6 +266,19 @@ getJasmineRequireObj().Env = function(j$) {
       }
     };
 
+    this.addAsyncMatchers = function(matchersToAdd) {
+      if (!currentRunnable()) {
+        throw new Error(
+          'Async Matchers must be added in a before function or a spec'
+        );
+      }
+      var customAsyncMatchers =
+        runnableResources[currentRunnable().id].customAsyncMatchers;
+      for (var matcherName in matchersToAdd) {
+        customAsyncMatchers[matcherName] = matchersToAdd[matcherName];
+      }
+    };
+
     j$.Expectation.addCoreMatchers(j$.matchers);
     j$.Expectation.addAsyncCoreMatchers(j$.asyncMatchers);
 
@@ -297,6 +310,7 @@ getJasmineRequireObj().Env = function(j$) {
       return j$.Expectation.asyncFactory({
         util: j$.matchersUtil,
         customEqualityTesters: runnableResources[spec.id].customEqualityTesters,
+        customAsyncMatchers: runnableResources[spec.id].customAsyncMatchers,
         actual: actual,
         addExpectationResult: addExpectationResult
       });
@@ -311,6 +325,7 @@ getJasmineRequireObj().Env = function(j$) {
         spies: [],
         customEqualityTesters: [],
         customMatchers: {},
+        customAsyncMatchers: {},
         customSpyStrategies: {},
         defaultStrategyFn: undefined
       };
@@ -322,6 +337,9 @@ getJasmineRequireObj().Env = function(j$) {
         resources.customMatchers = j$.util.clone(
           runnableResources[parentRunnableId].customMatchers
         );
+        resources.customAsyncMatchers = j$.util.clone(
+          runnableResources[parentRunnableId].customAsyncMatchers
+        );
         resources.defaultStrategyFn =
           runnableResources[parentRunnableId].defaultStrategyFn;
       }

src/core/Expectation.js

@@ -1,10 +1,4 @@
 getJasmineRequireObj().Expectation = function(j$) {
-  var promiseForMessage = {
-    jasmineToString: function() {
-      return 'a promise';
-    }
-  };
-
   /**
    * Matchers that come with Jasmine out of the box.
    * @namespace matchers
@@ -62,8 +56,12 @@ getJasmineRequireObj().Expectation = function(j$) {
       );
     }
 
-    if (!j$.isPromiseLike(this.expector.actual)) {
+    var customAsyncMatchers = options.customAsyncMatchers || {};
-      throw new Error('Expected expectAsync to be called with a promise.');
+    for (var matcherName in customAsyncMatchers) {
+      this[matcherName] = wrapAsyncCompare(
+        matcherName,
+        customAsyncMatchers[matcherName]
+      );
     }
   }
 
@@ -113,7 +111,7 @@ getJasmineRequireObj().Expectation = function(j$) {
       return this.expector
         .compare(name, matcherFactory, arguments)
         .then(function(result) {
-          self.expector.processResult(result, errorForStack, promiseForMessage);
+          self.expector.processResult(result, errorForStack);
         });
     };
   }
@@ -168,7 +166,7 @@ getJasmineRequireObj().Expectation = function(j$) {
         return matcher.compare.apply(this, arguments).then(negate);
       }
 
-      return defaultNegativeCompare;
+      return matcher.negativeCompare || defaultNegativeCompare;
     },
     buildFailureMessage: negatedFailureMessage
   };

src/core/Expector.js

@@ -68,12 +68,7 @@ getJasmineRequireObj().Expector = function(j$) {
     return result;
   };
 
-  Expector.prototype.processResult = function(
+  Expector.prototype.processResult = function(result, errorForStack) {
-    result,
-    errorForStack,
-    actualOverride
-  ) {
-    this.args[0] = actualOverride || this.args[0];
     var message = this.buildMessage(result);
 
     if (this.expected.length === 1) {

src/core/matchers/async/toBeRejected.js

@@ -10,9 +10,12 @@ getJasmineRequireObj().toBeRejected = function(j$) {
    * @example
    * return expectAsync(aPromise).toBeRejected();
    */
-  return function toBeResolved(util) {
+  return function toBeRejected(util) {
     return {
       compare: function(actual) {
+        if (!j$.isPromiseLike(actual)) {
+          throw new Error('Expected toBeRejected to be called on a promise.');
+        }
         return actual.then(
           function() { return {pass: false}; },
           function() { return {pass: true}; }

src/core/matchers/async/toBeRejectedWith.js

@@ -14,6 +14,10 @@ getJasmineRequireObj().toBeRejectedWith = function(j$) {
   return function toBeRejectedWith(util, customEqualityTesters) {
     return {
       compare: function(actualPromise, expectedValue) {
+        if (!j$.isPromiseLike(actualPromise)) {
+          throw new Error('Expected toBeRejectedWith to be called on a promise.');
+        }
+
         function prefix(passed) {
           return 'Expected a promise ' +
             (passed ? 'not ' : '') +

src/core/matchers/async/toBeRejectedWithError.js

@@ -17,6 +17,10 @@ getJasmineRequireObj().toBeRejectedWithError = function(j$) {
   return function toBeRejectedWithError() {
     return {
       compare: function(actualPromise, arg1, arg2) {
+        if (!j$.isPromiseLike(actualPromise)) {
+          throw new Error('Expected toBeRejectedWithError to be called on a promise.');
+        }
+
         var expected = getExpectedFromArgs(arg1, arg2);
 
         return actualPromise.then(

src/core/matchers/async/toBeResolved.js

@@ -13,6 +13,10 @@ getJasmineRequireObj().toBeResolved = function(j$) {
   return function toBeResolved(util) {
     return {
       compare: function(actual) {
+        if (!j$.isPromiseLike(actual)) {
+          throw new Error('Expected toBeResolved to be called on a promise.');
+        }
+
         return actual.then(
           function() { return {pass: true}; },
           function() { return {pass: false}; }

src/core/matchers/async/toBeResolvedTo.js

@@ -14,6 +14,10 @@ getJasmineRequireObj().toBeResolvedTo = function(j$) {
   return function toBeResolvedTo(util, customEqualityTesters) {
     return {
       compare: function(actualPromise, expectedValue) {
+        if (!j$.isPromiseLike(actualPromise)) {
+          throw new Error('Expected toBeResolvedTo to be called on a promise.');
+        }
+
         function prefix(passed) {
           return 'Expected a promise ' +
             (passed ? 'not ' : '') +

src/core/requireInterface.js

@@ -302,6 +302,20 @@ getJasmineRequireObj().interface = function(jasmine, env) {
     return env.addMatchers(matchers);
   };
 
+  /**
+   * Add custom async matchers for the current scope of specs.
+   *
+   * _Note:_ This is only callable from within a {@link beforeEach}, {@link it}, or {@link beforeAll}.
+   * @name jasmine.addMatchers
+   * @since 3.5.0
+   * @function
+   * @param {Object} matchers - Keys from this object will be the new async matcher names.
+   * @see custom_matcher
+   */
+  jasmine.addAsyncMatchers = function(matchers) {
+    return env.addAsyncMatchers(matchers);
+  };
+
   /**
    * Get the currently booted mock {Clock} for this Jasmine environment.
    * @name jasmine.clock