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

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

I find the current docs on mocking lacking in the area of mocking an existing module. The hope is this example will show people a simple, real-world way to mock node modules (whether from npm or in their own projects). 

I looked through all the docs and couldn't find a clear example like this so I hope it is helpful to others!

* Update based on PR feedback

* Link markdown.

* Fix example code to actually run 🤦‍♂️

* Ugh missing ) 🤦‍♂️

* Use "mockResolvedValue" instead"

* Update CHANGELOG.md

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