[XRAY] add get_test_run_iteration method and add more meaningful error raising for incorrect token in XRAY (atlassian-api#1504)

* [XRAY] add get_test_run_iteration method

* [XRAY] added raise_for_status method - could solve atlassian-api#1059, atlassian-api#1159

* [XRAY] updated docs

---------

Co-authored-by: Maksym Charuta <your_jlr_email>

Author: bigmac7

atlassian/xray.py

@@ -1,6 +1,7 @@
 # coding=utf-8
 import logging
 import re
+from requests import HTTPError
 from .rest_client import AtlassianRestAPI
 
 log = logging.getLogger(__name__)
@@ -13,6 +14,25 @@ def __init__(self, *args, **kwargs):
         kwargs["api_root"] = "rest/raven"
         super(Xray, self).__init__(*args, **kwargs)
 
+    def raise_for_status(self, response):
+        """
+        Checks the response for an error status and raises an exception with the error message provided by the server
+        :param response:
+        :return:
+        """
+        if response.status_code == 401 and response.headers.get("Content-Type") != "application/json;charset=UTF-8":
+            raise HTTPError("Unauthorized (401)", response=response)
+
+        if 400 <= response.status_code < 600:
+            try:
+                j = response.json()
+                error_msg = j["message"]
+            except Exception as e:
+                log.error(e)
+                response.raise_for_status()
+            else:
+                raise HTTPError(error_msg, response=response)
+
     def resource_url(self, resource, api_root=None, api_version=None):
         """
         Overloading the method from AtlassianRestAPI to be compatible with the "middle man" version used by Xray.
@@ -463,6 +483,16 @@ def update_test_run_assignee(self, test_run_id, assignee):
         url = self.resource_url("testrun/{0}".format(test_run_id))
         return self.put(url, update)
 
+    def get_test_run_iteration(self, test_run_id, iteration_id):
+        """
+        Retrieve the specified iteration for the given test run.
+        :param test_run_id: ID of the test run (e.g. 100).
+        :param iteration_id: ID of the iteration.
+        :return: Returns the specified iteration for the given test run.
+        """
+        url = self.resource_url("testrun/{0}/iteration/{1}".format(test_run_id, iteration_id))
+        return self.get(url)
+
     def get_test_run_status(self, test_run_id):
         """
         Retrieve the status for the given test run.

docs/xray.rst

@@ -136,6 +136,9 @@ Manage Test Runs
     # Update the assignee for the given test run
     xray.update_test_run_assignee(100, 'bob')
 
+    # Retrieve a iteration of the given test run
+    xray.get_test_run_iteration(100, 200)
+
     # Retrieve the status for the given test run
     xray.get_test_run_status(100)