Updated expect API docs with .resolves and .rejects

docs/ExpectAPI.md

@@ -286,6 +286,58 @@ test('the best flavor is not coconut', () => {
 });
 ```
 
+### `.resolves`
+
+##### available in Jest **20.0.0+**
+
+If your code uses Promises, use the `.resolves` keyword, and Jest will wait for the Promise to resolve and then run an assertion on the resulting value.
+
+For example, this code tests that the Promise returned by `fetchData()` resolves and that the resulting value is peanut butter:
+
+```js
+test('fetchData() resolves and is peanut butter', () => {
+  // make sure to add a return statement
+  return expect(fetchData()).resolves.toBe('peanut butter');
+});
+```
+
+Alternatively, you can use `async/await` in combination with `.resolves`:
+
+```js
+test('fetchData() resolves and is peanut butter', async () => {
+  await expect(fetchData()).resolves.toBe('peanut butter');
+  await expect(fetchData()).resolves.not.toBe('coconut');
+});
+```
+
+### `.rejects`
+
+##### available in Jest **20.0.0+**
+
+If your code uses Promises, use the `.rejects` keyword, and Jest will wait for that Promise to reject and then run an assertion on the resulting value.
+
+For example, this code tests that the Promise returned by `fetchData()` rejects and that the resulting value is an error:
+
+```js
+test('fetchData() rejects to be error', () => {
+  // make sure to add a return statement
+  return expect(fetchData()).rejects.toEqual({
+    error: 'User not found',
+  });
+});
+```
+
+Alternatively, you can use `async/await` in combination with `.rejects`:
+
+```js
+test('fetchData() rejects to be error', async () => {
+  await expect(fetchData()).rejects.toEqual({
+    error: 'User not found',
+  });
+  await expect(fetchData()).rejects.not.toBe('Mark');
+});
+```
+
 ### `.toBe(value)`
 
 `toBe` just checks that a value is what you expect. It uses `===` to check

docs/TestingAsyncCode.md

@@ -48,15 +48,13 @@ If `done()` is never called, the test will fail, which is what you want to happe
 
 ### Promises
 
-If your code uses promises, there is a simpler way to handle asynchronous tests. Just return a promise from your test, and Jest will wait for that promise to resolve. If the promise is rejected, the test will automatically fail.
+If your code uses promises, there is a simpler way to handle asynchronous tests. Just use the `resolves` keyword in your expect statement, and Jest will wait for that promise to resolve. If the promise is rejected, the test will automatically fail.
 
 For example, let's say that `fetchData`, instead of using a callback, returns a promise that is supposed to resolve to the string `"peanut butter"`. We could test it with:
 
 ```js
 test('the data is peanut butter', () => {
-  return fetchData().then(data => {
-    expect(data).toBe('peanut butter');
-  });
+  return expect(fetchData()).resolves.toBe('peanut butter');
 });
 ```
 
@@ -68,8 +66,7 @@ If your code uses `async` and `await`, you can use these in your tests as well.
 
 ```js
 test('the data is peanut butter', async () => {
-  const data = await fetchData();
-  expect(data).toBe('peanut butter');
+  await expect(fetchData()).resolves.toBe('peanut butter');
 });
 ```
 

docs/TutorialAsync.md

@@ -68,7 +68,7 @@ export default function request(url) {
 }
 ```
 
-Now let's write a test for our async functionality.
+Now let's write a test for our async functionality. Using the `resolves` keyword
 ```js
 // __tests__/user-test.js
 jest.mock('../request');
@@ -77,8 +77,7 @@ import * as user from '../user';
 
 // The promise that is being tested should be returned.
 it('works with promises', () => {
-  return user.getUserName(5)
-    .then(name => expect(name).toEqual('Paul'));
+  return expect(user.getUserName(5)).resolves.toEqual('Paul');
 });
 ```
 
@@ -94,8 +93,7 @@ how you'd write the same example from before:
 ```js
 // async/await can also be used.
 it('works with async/await', async () => {
-  const userName = await user.getUserName(4);
-  expect(userName).toEqual('Mark');
+  await expect(user.getUserName(4)).resolves.toEqual('Mark');
 });
 ```
 
@@ -106,32 +104,21 @@ and enable the feature in your `.babelrc` file.
 
 ### Error handling
 
-Errors can be handled in the standard JavaScript way: Either using `.catch()`
-directly on a Promise or through `try-catch` when using async/await. Note that
-if a Promise throws and the error is not handled, the test will fail. `expect.assertion(1)` makes sure that expectation was checked once. In this example it will fail if promise was resolved without throwing.
+Errors can be handled using the keyword `rejects` in your expect statement. This will verify that the promise rejects and perform an assertion on the resulting error.
 
 ```js
 // Testing for async errors can be done using `catch`.
 it('tests error with promises', () => {
-  // to be sure that `Promise` rejected and `expect` has been called once
-  expect.assertions(1); 
-
-  return user.getUserName(3)
-    .catch(e => expect(e).toEqual({
-      error: 'User with 3 not found.',
-    }));
+  return expect(user.getUserName(3)).rejects.toEqual({
+    error: 'User with 3 not found.',
+  });
 });
 
 // Or try-catch.
 it('tests error with async/await', async () => {
-  // to be sure that `await` throws error and `expect` has been called once
-  expect.assertions(1); 
-
-  try {
-    await user.getUserName(2);
-  } catch (object) {
-    expect(object.error).toEqual('User with 2 not found.');
-  }
+  await expect(user.getUserName(3)).rejects.toEqual({
+    error: 'User with 3 not found.',
+  });
 });
 ```