Merge branch 'winh-axios-mock-adapter-docs' into 'master'

Document advantages of axios-mock-adapter

See merge request gitlab-org/gitlab-ce!16645

1 files changed, 16 insertions, 3 deletions

diff --git a/doc/development/fe_guide/axios.md b/doc/development/fe_guide/axios.md
index 34fa684c5d6..dcd8f5cb839 100644
--- a/doc/development/fe_guide/axios.md
+++ b/doc/development/fe_guide/axios.md
@@ -27,10 +27,23 @@ This exported module should be used instead of directly using `axios` to ensure
     });
 ```
 
-## Mock axios response on tests
+## Mock axios response in tests
 
-To help us mock the responses we need we use [axios-mock-adapter][axios-mock-adapter]
+To help us mock the responses we are using [axios-mock-adapter][axios-mock-adapter].
 
+Advantages over [`spyOn()`]:
+
+- no need to create response objects
+- does not allow call through (which we want to avoid)
+- simple API to test error cases 
+- provides `replyOnce()` to allow for different responses
+
+We have also decided against using [axios interceptors] because they are not suitable for mocking.
+
+[axios interceptors]: https://github.com/axios/axios#interceptors
+[`spyOn()`]: https://jasmine.github.io/api/edge/global.html#spyOn
+
+### Example
 
 ```javascript
   import axios from '~/lib/utils/axios_utils';
@@ -54,7 +67,7 @@ To help us mock the responses we need we use [axios-mock-adapter][axios-mock-ada
   });
 ```
 
-### Mock poll requests on tests with axios
+### Mock poll requests in tests with axios
 
 Because polling function requires a header object, we need to always include an object as the third argument: