Add mock return matchers

CHANGELOG.md

@@ -77,6 +77,8 @@
   ([#5889](https://github.com/facebook/jest/pull/5889))
 * `[expect]` Introduce toStrictEqual
   ([#6032](https://github.com/facebook/jest/pull/6032))
+* `[expect]` Add return matchers
+  ([#5879](https://github.com/facebook/jest/pull/5879))
 
 ### Fixes
 
@@ -902,7 +904,9 @@
   ([#3805](https://github.com/facebook/jest/pull/3805))
 * Fix jest-circus ([#4290](https://github.com/facebook/jest/pull/4290))
 * Fix lint warning in master
+
   ([#4132](https://github.com/facebook/jest/pull/4132))
+
 * Fix linting ([#3946](https://github.com/facebook/jest/pull/3946))
 * fix merge conflict ([#4144](https://github.com/facebook/jest/pull/4144))
 * Fix minor typo ([#3729](https://github.com/facebook/jest/pull/3729))

docs/ExpectAPI.md

@@ -667,8 +667,6 @@ arguments it was nth called with. For example, let's say you have a
 flavors, and you want to ensure that when you call it, the first flavor it
 operates on is `'lemon'` and the second one is `'octopus'`. You can write:
 
-Note that, nth argument must be positive integer starting from 1.
-
 ```js
 test('drinkEach drinks each drink', () => {
   const drink = jest.fn();
@@ -678,6 +676,115 @@ test('drinkEach drinks each drink', () => {
 });
 ```
 
+Note: the nth argument must be positive integer starting from 1.
+
+### `.toHaveReturned()`
+
+Also under the alias: `.toReturn()`
+
+If you have a mock function, you can use `.toHaveReturned` to test that the mock
+function returned a value. For example, let's say you have a mock `drink` that
+returns `true`. You can write:
+
+```js
+test('drinks returns', () => {
+  const drink = jest.fn(() => true);
+
+  drink();
+
+  expect(drink).toHaveReturned();
+});
+```
+
+### `.toHaveReturnedTimes(number)`
+
+Also under the alias: `.toReturnTimes(number)`
+
+Use `.toHaveReturnedTimes` to ensure that a mock function returned an exact
+number of times. For example, let's say you have a mock `drink` that returns
+`true`. You can write:
+
+```js
+test('drink returns twice', () => {
+  const drink = jest.fn(() => true);
+
+  drink();
+  drink();
+
+  expect(drink).toHaveReturnedTimes(2);
+});
+```
+
+### `.toHaveReturnedWith(value)`
+
+Also under the alias: `.toReturnWith(value)`
+
+Use `.toHaveReturnedWith` to ensure that a mock function returned a specific
+value.
+
+For example, let's say you have a mock `drink` that returns the name of the
+beverage that was consumed. You can write:
+
+```js
+test('drink returns La Croix', () => {
+  const beverage = {name: 'La Croix'};
+  const drink = jest.fn(beverage => beverage.name);
+
+  drink(beverage);
+
+  expect(drink).toHaveReturnedWith('La Croix');
+});
+```
+
+### `.toHaveLastReturnedWith(value)`
+
+Also under the alias: `.lastReturnedWith(value)`
+
+Use `.toHaveLastReturnedWith` to test the specific value that a mock function
+last returned.
+
+For example, let's say you have a mock `drink` that returns the name of the
+beverage that was consumed. You can write:
+
+```js
+test('drink returns La Croix (Orange) last', () => {
+  const beverage1 = {name: 'La Croix (Lemon)'};
+  const beverage2 = {name: 'La Croix (Orange)'};
+  const drink = jest.fn(beverage => beverage.name);
+
+  drink(beverage1);
+  drink(beverage2);
+
+  expect(drink).toHaveLastReturnedWith('La Croix (Orange)');
+});
+```
+
+### `.toHaveNthReturnedWith(nthCall, value)`
+
+Also under the alias: `.nthReturnedWith(nthCall, value)`
+
+Use `.toHaveNthReturnedWith` to test the specific value that a mock function
+returned for the nth call.
+
+For example, let's say you have a mock `drink` that returns the name of the
+beverage that was consumed. You can write:
+
+```js
+test('drink returns expected nth calls', () => {
+  const beverage1 = {name: 'La Croix (Lemon)'};
+  const beverage2 = {name: 'La Croix (Orange)'};
+  const drink = jest.fn(beverage => beverage.name);
+
+  drink(beverage1);
+  drink(beverage2);
+
+  expect(drink).toHaveNthReturnedWith(1, 'La Croix (Lemon)');
+  expect(drink).toHaveNthReturnedWith(2, 'La Croix (Orange)');
+});
+```
+
+Note: the nth argument must be positive integer starting from 1.
+
 ### `.toBeCloseTo(number, numDigits)`
 
 Using exact equality with floating point numbers is a bad idea. Rounding means