(Add tests to) document how multiple inceptors work (axios#3564)

* Add a group for the multiple-interceptors tests.

The current test contains a lot of details that are worth being tested
separately and also made explicit. This is what is coming with the next changes.

* Fix indentation.

* Make explicit that the test only tests the interception of the fulfilled part.

* Indent.

* Make the test just test a tiny bit, as described.

The more explicit the test, the better we can 1) describe what it does
and use that for the docs to make them understandable 2) have a better
explicit description of the API (in case we want to modify it) and 3) have
a regression test when changing.

* Add a test that explicitly shows that the order of interceptors is as they were added.

* Pull out reusable code, to make the tests more explicitly stating the things they care about.

* Write a test showing that the responses are not merged or anything,
only the last one in the chain is returned.

* Make visible that the interceptors are a chain, one receives its predecessor's data.

* Test what happens when the interceptor throws.

* Refactor, add another group of tests and pull helper function there.

The previous change to also catch in the helper function was not needed
for any of the tests above, so remove it and put it in the describe-block
below where it is needed.
Just trying to write the specific code needed, not more.
Not sure about the impact for failing tests, I am glad about input.
But the main intention here is to have minimal code, explicit tests and
not too much generic code which might break itself eventually.

* Documenting that the following reject-interceptor gets called.

* Documenting how the interceptor chain handles caught rejections.

* Document "multiple interceptors".

I just extracted the test descriptions from the new/modified tests.
And I also learned that I should improve the test descriptions, the
tests are just in a GIVEN-WHEN-THEN structure, so I can also use those
terms better. Will do this next.

* Transfer the better readable descriptions as I changed them in the README back into the tests.

After I had updated the README using the test descriptions I realized how
the test descriptions can be improved, so I did this "moving" the learnings
back into the code.

* Be a bit more explicit, it was not clear when reading, imho.

* Add new lines to be kinda consistent with the rest of the file.

Co-authored-by: Jay <jasonsaayman@gmail.com>

README.md

@@ -32,6 +32,7 @@ Promise based HTTP client for the browser and node.js
     - [Custom instance defaults](#custom-instance-defaults)
     - [Config order of precedence](#config-order-of-precedence)
   - [Interceptors](#interceptors)
+    - [Multiple Interceptors](#multiple-interceptors)
   - [Handling Errors](#handling-errors)
   - [Cancellation](#cancellation)
   - [Using application/x-www-form-urlencoded format](#using-applicationx-www-form-urlencoded-format)
@@ -645,6 +646,21 @@ axios.interceptors.request.use(function (config) {
 }, null, { runWhen: onGetCall });
 ```
 
+### Multiple Interceptors
+
+Given you add multiple response interceptors
+and when the response was fulfilled
+- then each interceptor is executed
+- then they are executed in the order they were added
+- then only the last interceptor's result is returned
+- then every interceptor receives the result of it's predecessor
+- and when the fulfillment-interceptor throws
+    - then the following fulfillment-interceptor is not called
+    - then the following rejection-interceptor is called
+    - once caught, another following fulfill-interceptor is called again (just like in a promise chain).
+
+Read [the interceptor tests](./test/specs/interceptors.spec.js) for seeing all this in code.
+
 ## Handling Errors
 
 ```js

test/specs/interceptors.spec.js

@@ -337,36 +337,143 @@ describe('interceptors', function () {
     });
   });
 
-  it('should add multiple response interceptors', function (done) {
-    var response;
+  describe('given you add multiple response interceptors', function () {
+
+    describe('and when the response was fulfilled', function () {
+
+      function fireRequestAndExpect(expectation) {
+        var response;
+        axios('/foo').then(function(data) {
+          response = data;
+        });
+        getAjaxRequest().then(function (request) {
+          request.respondWith({
+            status: 200,
+            responseText: 'OK'
+          });
+
+          setTimeout(function() {
+            expectation(response)
+          }, 100);
+        });
+      }
+
+      it('then each interceptor is executed', function (done) {
+        var interceptor1 = jasmine.createSpy('interceptor1');
+        var interceptor2 = jasmine.createSpy('interceptor2');
+        axios.interceptors.response.use(interceptor1);
+        axios.interceptors.response.use(interceptor2);
+
+        fireRequestAndExpect(function () {
+          expect(interceptor1).toHaveBeenCalled();
+          expect(interceptor2).toHaveBeenCalled();
+          done();
+        });
+      });
 
-    axios.interceptors.response.use(function (data) {
-      data.data = data.data + '1';
-      return data;
-    });
-    axios.interceptors.response.use(function (data) {
-      data.data = data.data + '2';
-      return data;
-    });
-    axios.interceptors.response.use(function (data) {
-      data.data = data.data + '3';
-      return data;
-    });
+      it('then they are executed in the order they were added', function (done) {
+        var interceptor1 = jasmine.createSpy('interceptor1');
+        var interceptor2 = jasmine.createSpy('interceptor2');
+        axios.interceptors.response.use(interceptor1);
+        axios.interceptors.response.use(interceptor2);
 
-    axios('/foo').then(function (data) {
-      response = data;
-    });
+        fireRequestAndExpect(function () {
+          expect(interceptor1).toHaveBeenCalledBefore(interceptor2);
+          done();
+        });
+      });
 
-    getAjaxRequest().then(function (request) {
-      request.respondWith({
-        status: 200,
-        responseText: 'OK'
+      it('then only the last interceptor\'s result is returned', function (done) {
+        axios.interceptors.response.use(function() {
+          return 'response 1';
+        });
+        axios.interceptors.response.use(function() {
+          return 'response 2';
+        });
+
+        fireRequestAndExpect(function (response) {
+          expect(response).toBe('response 2');
+          done();
+        });
       });
 
-      setTimeout(function () {
-        expect(response.data).toBe('OK123');
-        done();
-      }, 100);
+      it('then every interceptor receives the result of it\'s predecessor', function (done) {
+        axios.interceptors.response.use(function() {
+          return 'response 1';
+        });
+        axios.interceptors.response.use(function(response) {
+          return [response, 'response 2'];
+        });
+
+        fireRequestAndExpect(function (response) {
+          expect(response).toEqual(['response 1', 'response 2']);
+          done();
+        });
+      });
+
+      describe('and when the fulfillment-interceptor throws', function () {
+
+        function fireRequestCatchAndExpect(expectation) {
+          axios('/foo').catch(function(data) {
+            // dont handle result
+          });
+          getAjaxRequest().then(function (request) {
+            request.respondWith({
+              status: 200,
+              responseText: 'OK'
+            });
+
+            setTimeout(function() {
+              expectation()
+            }, 100);
+          });
+        }
+
+        it('then the following fulfillment-interceptor is not called', function (done) {
+          axios.interceptors.response.use(function() {
+            throw Error('throwing interceptor');
+          });
+          var interceptor2 = jasmine.createSpy('interceptor2');
+          axios.interceptors.response.use(interceptor2);
+
+          fireRequestCatchAndExpect(function () {
+            expect(interceptor2).not.toHaveBeenCalled();
+            done();
+          });
+        });
+
+        it('then the following rejection-interceptor is called', function (done) {
+          axios.interceptors.response.use(function() {
+            throw Error('throwing interceptor');
+          });
+          var unusedFulfillInterceptor = function() {};
+          var rejectIntercept = jasmine.createSpy('rejectIntercept');
+          axios.interceptors.response.use(unusedFulfillInterceptor, rejectIntercept);
+
+          fireRequestCatchAndExpect(function () {
+            expect(rejectIntercept).toHaveBeenCalled();
+            done();
+          });
+        });
+
+        it('once caught, another following fulfill-interceptor is called again (just like in a promise chain)', function (done) {
+          axios.interceptors.response.use(function() {
+            throw Error('throwing interceptor');
+          });
+
+          var unusedFulfillInterceptor = function() {};
+          var catchingThrowingInterceptor = function() {};
+          axios.interceptors.response.use(unusedFulfillInterceptor, catchingThrowingInterceptor);
+
+          var interceptor3 = jasmine.createSpy('interceptor3');
+          axios.interceptors.response.use(interceptor3);
+
+          fireRequestCatchAndExpect(function () {
+            expect(interceptor3).toHaveBeenCalled();
+            done();
+          });
+        });
+      });
     });
   });