Add some docs on using jest.mock(...)

CHANGELOG.md

@@ -3,8 +3,9 @@
 ### Features
 
 * `[jest-jasmine2]` Adds error throwing and descriptive errors to `it`/ `test`
-  for invalid arguements. `[jest-circus]` Adds error throwing and descriptive
-  errors to `it`/ `test` for invalid arguements.
+  for invalid arguments. `[jest-circus]` Adds error throwing and descriptive
+  errors to `it`/ `test` for invalid arguments
+  ([#5558](https://github.com/facebook/jest/pull/5558))
 * `[jest-matcher-utils]` Add `isNot` option to `matcherHint` function
   ([#5512](https://github.com/facebook/jest/pull/5512))
 
@@ -21,6 +22,11 @@
 * `[jest-cli]` Fix update snapshot issue when using watchAll
   ([#5696](https://github.com/facebook/jest/pull/5696))
 
+### Chore & Maintenance
+
+* `[docs]` Add docs on using `jest.mock(...)`
+  ([#5648](https://github.com/facebook/jest/pull/5648))
+
 ## 22.4.2
 
 ### Fixes

docs/MockFunctions.md

@@ -127,6 +127,51 @@ dependent component and configuring that, but the technique is the same. In
 these cases, try to avoid the temptation to implement logic inside of any
 function that's not directly being tested.
 
+## Mocking Modules
+
+Suppose we have a class that fetches users from our API. The class uses
+[axios](https://github.com/axios/axios) to call the API then returns the `data`
+attribute which contains all the users:
+
+```js
+// users.js
+import axios from 'axios';
+
+class Users {
+  static all() {
+    return axios.get('/users.json').then(resp => resp.data);
+  }
+}
+
+export default Users;
+```
+
+Now, in order to test this method without actually hitting the API (and thus
+creating slow and fragile tests), we can use the `jest.mock(...)` function to
+automatically mock the axios module.
+
+Once we mock the module we can provide a `mockReturnValue` for `.get` that
+returns the data we want our test to assert against. In effect, we are saying
+that we want axios.get('/users.json') to return a fake response.
+
+```js
+// users.test.js
+import axios from 'axios';
+import Users from './users';
+
+jest.mock('axios');
+
+test('should fetch users', () => {
+  const resp = {data: [{name: 'Bob'}]};
+  axios.get.mockResolvedValue(resp);
+
+  // or you could use the follwing depending on your use case:
+  // axios.get.mockImpementation(() => Promise.resolve(resp))
+
+  return Users.all().then(users => expect(users).toEqual(resp.data));
+});
+```
+
 ## Mock Implementations
 
 Still, there are cases where it's useful to go beyond the ability to specify