From aef82a2a8ae9b249c40bcd558552bfb11ca43894 Mon Sep 17 00:00:00 2001
From: Dana Woodman <dana@danawoodman.com>
Date: Thu, 1 Mar 2018 15:00:36 -0800
Subject: [PATCH] Add some docs on using `jest.mock(...)` (#5648)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* 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          | 10 ++++++++--
 docs/MockFunctions.md | 45 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 396ecdc27cf2..d5121964bfc2 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/docs/MockFunctions.md b/docs/MockFunctions.md
index a4894752e7f6..6407db8d2510 100644
--- a/docs/MockFunctions.md
+++ b/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