Added Zephyr Squad Server support

This commit introduces initial support for the Zephyr Squad (server)
variant. Only a number of the available Zephyr API calls are introduced
by this commit.

All testing for this commit was done on a self-hosted Zephyr Squad instance.

Author: crapitea

examples/server.py renamed to examples/scale-server.py

@@ -0,0 +1,113 @@
+"""
+Usage examples of Zephyr Squad Server API wrappers.
+"""
+import logging
+
+from zephyr import ZephyrSquad
+
+# Enable logging with level Debug for more verbosity
+logging.basicConfig(level=logging.DEBUG)
+
+
+# Specify your Jira context to operate with:
+base_url = "https://jira.hosted.com/"
+
+# Use the Jira certificate for TLS connections
+session_params = {
+    "verify": "<path-to-certificate>"
+}
+
+# Create an instance of Zephyr Squad
+zsquad = ZephyrSquad(
+    base_url=base_url,
+    token="<your_token>",
+    session_attrs=session_params
+)
+
+# Now we can start playing with the Zephyr API!
+
+# Obtain a project's information
+project_info = zsquad.api.project.get_project_info("<your_project_key>")
+
+# Obtain a project's versions/releases
+project_versions = zsquad.api.project.get_project_versions_by_id("<your_project_id>")
+
+# Get the data of a testcase
+test_case = zsquad.api.test_cases.get_test_case("<your_case_key>", fields="id")
+
+# Get the test steps from a testcase
+test_steps = zsquad.api.test_cases.get_test_steps("<your_step_id>")
+
+# Get the list of all test cycles for a specific release
+test_cycle = zsquad.api.test_cycles.get_test_cycle(project_id="<your_project_id>", version_id="<your_version_id>")
+
+# Get all folders from a test cycle
+test_cycle_folders = zsquad.api.folder.get_folder(cycle_id="<your_cycle_id>", project_id="<your_project_id>", version_id="<your_version_id>")
+
+# Get all test executions from a test case
+test_executions = zsquad.api.test_executions.get_test_execution(test_id_or_key="<your_case_id_or_key>")
+
+# Create a new test case for a project
+data = {
+    "fields": {
+        "assignee": {
+            "name": "<jira_username>"
+        },
+        "description": "<your_case_description>"
+    }
+}
+ret_data = zsquad.api.test_cases.create_test_case(project_id="<your_project_id>", summary="<your_case_summary>", data=data)
+
+# Execute ZQL search query
+demo_query = "project = '<your_project_id>' AND cycleName = '<your_cycle_name>'"
+zql_search_res = zsquad.api.utils.run_zql_search(query=demo_query, maxRecords=200)
+
+# Create a new test cycle for a project based on an existing test case
+data = {
+    "clonedCycleId": "<your_cycle_id>",
+    "description": "<your_cycle_description>",
+    "build": "",
+    "startDate": "29/Nov/22",
+    "endDate": "4/Dec/22",
+    "environment": ""
+}
+ret_data = zsquad.api.test_cycles.create_test_cycle(project_id="<your_project_id>", version_id="<your_version_id>", cycle_name="<your_cycle_name>", data=data)
+
+# Create a new test folder for a test cycle
+data = {
+    "cycleId": 1508,  # it will be rewritten by the function
+    "name": "<your_folder_name>",
+    "description": "<your_folder_description>",
+    "projectId": 10600,  # it will be rewritten by the function
+    "versionId": -1,  # it will be rewritten by the function
+    "clonedFolderId": -1
+}
+ret_data = zsquad.api.folder.create_folder(project_id="<your_project_id>", version_id="<your_version_id>", cycle_id="<your_cycle_id>", data=data)
+
+# Add a new test case for a test cycle
+data = {
+    "issues":["<your_case_key>"],
+}
+ret_data = zsquad.api.test_cases.add_test_to_cycle(project_id="<your_project_id>", cycle_id="<your_cycle_id>", method="1", data=data)
+
+# Obtain the execution details
+exec_details = zsquad.api.test_executions.get_execution_properties(exec_id="<execution_id>")
+# print(exec_details)
+
+# Obtain the execution steps from an execution
+exec_steps = zsquad.api.test_executions.get_test_steps(exec_id="<execution_id>")
+
+# Update the status of an execution step
+step_status = zsquad.api.test_executions.update_test_step_status(step_id="<execution_step_id>", status=2)
+
+# Update the status of an execution step
+exec_status = zsquad.api.test_executions.update_execution_status(exec_id="<execution_id>", status=2)
+
+# Update a folder name and description
+data = {
+    "description": "<new_folder_decription>"
+}
+ret_data = zsquad.api.folder.update_folder(project_id="<your_project_id>", version_id="<your_version_id>", cycle_id="<your_cycle_id>", folder_id="<your_folder_id>", name="<your_new_folder_name>")
+
+# Delete 3 test executions
+delete_status = zsquad.api.test_executions.delete_bulk_execution(execution_id=["<your_exec_id_1>", "<your_exec_id_2>", "<your_exec_id_3>"])

examples/squad-server.py

@@ -1,6 +1,6 @@
 [metadata]
 name = zephyr-python-api
-version = 0.0.3
+version = 0.0.4
 author = Petr Sharapenko
 author_email = [email protected]
 description = Zephyr (TM4J) Python REST API wrapper

setup.cfg

@@ -1,2 +1,3 @@
 from zephyr.scale import API_V1, API_V2, ZephyrScale
+from zephyr.squad import API_V1, ZephyrSquad
 from zephyr.utils.common import cookie_str_to_dict

zephyr/__init__.py

@@ -0,0 +1 @@
+from zephyr.squad.squad import API_V1, ZephyrSquad

zephyr/squad/__init__.py

@@ -0,0 +1,6 @@
+from .endpoints import (ProjectEndpoints,
+                        TestCaseEndpoints,
+                        TestCyclesEndpoints,
+                        FolderEndpoints,
+                        TestExecutionEndpoints,
+                        TestUtilsEndpoints)

zephyr/squad/server/__init__.py

@@ -0,0 +1,224 @@
+from copy import deepcopy
+from ...zephyr_session import ZephyrSession
+from .paths import ServerPaths as Paths
+
+
+class EndpointTemplate:
+    """Class with basic constructor for endpoint classes"""
+    def __init__(self, session: ZephyrSession):
+        self.session = session
+
+    def _dict_merge(self, a, b):
+        """Recursively merges 2 dictionaries and return the merged dictionary"""
+        result = deepcopy(a)
+        for k, v in b.items():
+            if k in result and isinstance(result[k], dict):
+                    result[k] = self._dict_merge(result[k], v)
+            else:
+                result[k] = deepcopy(v)
+        return result
+
+class TestCaseEndpoints(EndpointTemplate):
+    """Api wrapper for "Test Case" endpoints"""
+
+    def get_test_case(self, test_case_key, **params):
+        """Retrieve the Test Case matching the given key"""
+        return self.session.get(Paths.CASE_KEY.format(test_case_key),
+                                params=params)
+
+    def get_test_steps(self, test_case_id):
+        """Retrieve the Test Case matching the given key"""
+        return self.session.get(Paths.CASE_KEY_STEPS.format(test_case_id))
+
+    def _get_test_case_type(self):
+        """Retrieve the Test Case matching the given key"""
+        case_type = self.session.get(Paths.CASE_ISSUE_TYPE)
+        return case_type["testcaseIssueTypeId"]
+
+    def create_test_case(self, project_id, summary, data):
+        """
+        Creates a new Test Case based on a minimum required fields.
+        (https://support.smartbear.com/zephyr-squad-server/docs/api/how-to/create-tests.html)
+        See Zephyr Squad Test Case creation documentation to better understand what can be
+        modified.
+        """
+        case_type = self._get_test_case_type()
+        json = {
+            "fields": {
+                "project": {
+                    "id": project_id
+                },
+                'issuetype': {
+                    'id': case_type
+                },
+                "summary": summary,
+            }
+        }
+        merged_json = self._dict_merge(data, json)
+        return self.session.post(Paths.CASE, json=merged_json)
+
+    def add_test_to_cycle(self, project_id, cycle_id, method, data):
+        """
+        Add an existing Test Case to a Test Cycle based on a minimum required fields.
+        (https://support.smartbear.com/zephyr-squad-server/docs/api/how-to/add-tests-to-cycle.html)
+        See Zephyr Squad documentation to better understand what can be modified.
+        """
+        json = {
+            'cycleId': cycle_id,
+            'projectId': project_id,
+            'method': method
+        }
+        merged_json = self._dict_merge(data, json)
+        return self.session.post(Paths.CASE_TO_CYCLE, json=merged_json)
+
+
+class TestUtilsEndpoints(EndpointTemplate):
+    """Api wrapper for different helpers endpoints like ZQL search"""
+
+    def run_zql_search(self, query, **params):
+        """Retrieve the Test Cycle matching the given key"""
+        params.update(zqlQuery=f'({query})')
+        return self.session.get(Paths.ZQL_SEARCH, params=params)
+
+
+class TestCyclesEndpoints(EndpointTemplate):
+    """Api wrapper for "Test Cycles" endpoints"""
+
+    def get_test_cycle(self, project_id, version_id, **params):
+        """Retrieve the Test Cycle matching the given key"""
+        params.update(projectId=project_id, versionId=version_id)
+        return self.session.get(Paths.CYCLE, params=params)
+
+    def create_test_cycle(self, project_id, version_id, cycle_name, data):
+        """
+        Creates a new Test Cycle based on a minimum required fields.
+        (https://support.smartbear.com/zephyr-squad-server/docs/api/how-to/create-cycle.html)
+        See Zephyr Squad Test Cycle creation documentation to better understand what can be
+        modified.
+        """
+        json = {
+            'name': cycle_name,
+            'projectId': project_id,
+            'versionId': version_id
+        }
+        merged_json = self._dict_merge(data, json)
+        return self.session.post(Paths.CYCLE, json=merged_json)
+
+
+class TestExecutionEndpoints(EndpointTemplate):
+    """Api wrapper for "Test Execution" endpoints"""
+
+    def get_test_execution(self, test_id_or_key, **params):
+        """Retrieve all execution of a test case by the issue id or issue key"""
+        params.update(testIdOrKey=test_id_or_key)
+        return self.session.get(Paths.EXEC_BY_TEST, params=params)
+
+    def get_execution_properties(self, exec_id, **params):
+        """Retrieve all execution details"""
+        return self.session.get(Paths.EXEC_PROP.format(exec_id),
+                                params=params)
+
+    def get_test_steps(self, exec_id, **params):
+        """Retrieve all execution steps"""
+        params.update(executionId=exec_id)
+        params.update(expand="")
+        return self.session.get(Paths.STEP, params=params)
+
+    def update_test_step_status(self, step_id, status):
+        """
+        Updates a Test Step Status. Available status values:
+        -1 = UNEXECUTED | 1 = PASS | 2 = FAIL | 3 = WIP | 4 = BLOCKED
+        """
+        json = {
+            "status": status
+        }
+        return self.session.put(Paths.STEP_ID.format(step_id), json=json)
+
+    def update_execution_status(self, exec_id, status):
+        """
+        Updates an Test Execution Status. Available status values:
+        -1 = UNEXECUTED | 1 = PASS | 2 = FAIL | 3 = WIP | 4 = BLOCKED
+        """
+        json = {
+            "status": status
+        }
+        return self.session.put(Paths.EXEC.format(exec_id), json=json)
+
+    def delete_bulk_execution(self, execution_id):
+        """Delete bulk Execution by Execution Id"""
+        if not isinstance(execution_id, list):
+            execution_id = [ execution_id ]
+
+        json = {
+            "executions": execution_id
+        }
+        return self.session.delete(Paths.EXEC_DEL, json=json)
+
+
+class FolderEndpoints(EndpointTemplate):
+    """Api wrapper for "Folder" endpoints"""
+
+    def get_folder(self, project_id, version_id, cycle_id, **params):
+        """Retrieve the Folders from a Test Cycle"""
+        params.update(projectId=project_id, versionId=version_id)
+        return self.session.get(Paths.FOLDER.format(cycle_id), params=params)
+
+    def create_folder(self, project_id, version_id, cycle_id, data):
+        """
+        Create a Folder in a Test Cycle based on a minimum required fields.
+        (https://support.smartbear.com/zephyr-squad-server/docs/api/how-to/create-folder-in-cycle.html)
+        See Zephyr Squad Folder creation documentation to better understand what can be
+        modified.
+        """
+        json = {
+            'cycleId': cycle_id,
+            'projectId': project_id,
+            'versionId': version_id
+        }
+        merged_json = self._dict_merge(data, json)
+        return self.session.post(Paths.FOLDER_CREATE, json=merged_json)
+
+    def update_folder(self, project_id, cycle_id, version_id, folder_id, name, data=dict()):
+        """
+        Updates a Test Folder information.
+        (https://zephyrsquadserver.docs.apiary.io/#reference/folderresource/update-a-folder-information/update-a-folder-information)
+        """
+        json = {
+            'cycleId': cycle_id,
+            'projectId': project_id,
+            'versionId': version_id,
+            "folderId": folder_id,
+            "name": name,
+        }
+        merged_json = self._dict_merge(data, json)
+        return self.session.put(Paths.FOLDER_ID.format(folder_id), json=merged_json)
+
+
+class ProjectEndpoints(EndpointTemplate):
+    """Api wrapper for "Project" endpoints"""
+
+    def get_project_info(self, project_key):
+        """
+        Retrieve project information
+        :params project_key: project key (Ex: DEMOPROJ)
+        :returns: dictionary containing the project information
+        """
+        return self.session.get(Paths.PRJ_ID.format(project_key))
+
+    def get_project_versions_by_key(self, project_key):
+        """
+        Retrieve all project versions (releases) by project key using Jira API
+        :params project_key: project key (Ex: DEMOPROJ)
+        :returns: dictionary containing the project information
+        """
+        return self.session.get(Paths.PRJ_VERSIONS_BY_KEY.format(project_key))
+
+    def get_project_versions_by_id(self, project_id, **params):
+        """
+        Retrieve all project versions (releases) by project id using Zephyr API
+        :params project_key: project id (Ex: 77303)
+        :returns: dictionary containing the project information
+        """
+        params.update(projectId=project_id)
+        return self.session.get(Paths.PRJ_VERSIONS_BY_ID.format(project_id),
+                                params=params)