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

README.md

@@ -4,31 +4,33 @@
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/zephyr-python-api)
 ![PyPI](https://img.shields.io/pypi/v/zephyr-python-api)
 ![PyPI - License](https://img.shields.io/pypi/l/zephyr-python-api)
-### Project description
-This is a set of wrappers for Zephyr Scale (TM4J) REST API. This means you can interact with Zephyr Scale without GUI, access it with python code and create automation scripts for your every day interactions.
+## Project description
+This is a set of wrappers for both Zephyr Scale and Zephyr Squad (TM4J) REST APIs. This means you can interact with Zephyr without GUI, access it with python code and create automation scripts for your every day interactions.
 
 To be done:
 * More usage examples
 * Tests, tests and tests for gods of testing
 * Convenient docs
 * Implementing higher level wrappers representing Test Case, Test Cycle, etc.
 
-### Installation
+## Installation
 
 ```
 pip install zephyr-python-api
 ```
 
-### Example usage
+## Example usage
 
-Zephyr Cloud auth:
+### Zephyr Scale
+
+Zephyr Scale Cloud auth:
 ```python
 from zephyr import ZephyrScale
 
 zscale = ZephyrScale(token=<your_token>)
 ```
 
-Zephyr Server (TM4J) auth:
+Zephyr Scale Server (TM4J) auth:
 ```python
 from zephyr import ZephyrScale
 
@@ -58,17 +60,62 @@ test_case = zapi.test_cases.get_test_case("<test_case_id>")
 creation_result = zapi.test_cases.create_test_case("<project_key>", "test_case_name")
 ```
 
-### Troubleshooting
+### Zephyr Squad
+
+Zephyr Squad Server (TM4J) auth:
+```python
+from zephyr import ZephyrSquad
+
+# Auth can be made with Jira token
+auth = {"token": "<your_jira_token>"}
+
+# or with login and password (suggest using get_pass)
+auth = {"username": "<your_login>", "password": "<your_password>"}
+
+# or even session cookie dict
+auth = {"cookies": "<session_cookie_dict>"}
+
+zsquad = ZephyrSquad(base_url=base_url, **auth)
+```
+
+Then it is possible to interact with api wrappers:
+```python
+# Obtain a project's information
+project_info = zsquad.actions.project.get_project_info("<project_key>")
+
+# Obtain a project's versions/releases
+project_versions = zsquad.api.util_resource.get_all_versions("<project_id>")
+
+# Get a single test case by its id
+test_case = zsquad.actions.test_cases.get_test_case("<case_key>", fields="id")
+
+# Create a new test case for a project
+data = {
+    "fields": {
+        "assignee": {
+            "name": "<jira_username>"
+        },
+        "description": "<case_description>"
+    }
+}
+creation_result = zsquad.actions.test_cases.create_test_case(projectId="<project_id>", summary="<case_summary>", data=data)
+```
+
+## Troubleshooting
 
 For troubleshooting see [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
 
 
-### License
+## License
 
 This library is licensed under the Apache 2.0 License.
 
-### Links
+## Links
 
 [Zephyr Scale Cloud API docs](https://support.smartbear.com/zephyr-scale-cloud/api-docs/)
 
-[Zephyr Scale Server API docs](https://support.smartbear.com/zephyr-scale-server/api-docs/v1/)
+[Zephyr Scale Server API docs](https://support.smartbear.com/zephyr-scale-server/api-docs/v1/)
+
+[Zephyr Squad Server API docs](https://zephyrsquadserver.docs.apiary.io/)
+
+[Zephyr Squad Server How to API docs](https://support.smartbear.com/zephyr-squad-server/docs/api/index.html)

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

@@ -0,0 +1,127 @@
+"""
+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="<token>",
+    session_attrs=session_params
+)
+
+# Now we can start playing with the Zephyr API!
+
+# Obtain a project's information
+project_info = zsquad.actions.project.get_project_info("<project_key>")
+
+# Obtain a project's versions/releases
+project_versions = zsquad.api.util_resource.get_all_versions("<project_id>")
+
+# Get the data of a testcase
+test_case = zsquad.actions.test_cases.get_test_case("<case_key>", fields="id")
+
+# Get the test steps from a testcase
+test_steps = zsquad.api.teststep_resource.get_list_of_teststeps("<issue_id>")
+
+# Get the information about a test cycle
+test_cycle = zsquad.api.cycle_resource.get_cycle_information(id="<cycle_id>")
+
+# Get the list of all test cycles for a specific release
+test_cycles = zsquad.api.cycle_resource.get_list_of_cycle(projectId="<project_id>", versionId="<version_id>")
+
+# Get all folders from a test cycle
+test_cycle_folders = zsquad.api.cycle_resource.get_the_list_of_folder_for_a_cycle(cycleId="<cycle_id>", projectId="<project_id>", versionId="<version_id>")
+
+# Get all test executions from a test case
+test_executions = zsquad.api.traceability_resource.get_list_of_search_execution_by_test(testIdOrKey="<case_id_or_key>")
+
+# Create a new test case for a project
+data = {
+    "fields": {
+        "assignee": {
+            "name": "<jira_username>"
+        },
+        "description": "<case_description>"
+    }
+}
+ret_data = zsquad.actions.test_cases.create_test_case(projectId="<project_id>", summary="<case_summary>", data=data)
+
+# Execute ZQL search query
+demo_query = "project = '<project_id>' AND cycleName = '<cycle_name>'"
+zql_search_res = zsquad.api.execution_search_resource.execute_search_to_get_search_result(query=demo_query, maxRecords=200)
+
+# Create a new test cycle for a project based on an existing test case
+data = {
+    "clonedCycleId": "<cycle_id>",
+    "description": "<cycle_description>",
+    "build": "",
+    "startDate": "29/Nov/22",
+    "endDate": "4/Dec/22",
+    "environment": ""
+}
+ret_data = zsquad.api.cycle_resource.create_new_cycle(projectId="<project_id>", versionId="<version_id>", name="<cycle_name>", data=data)
+
+# Create a new test folder for a test cycle
+data = {
+    "cycleId": 1508,  # it will be rewritten by the function
+    "name": "<folder_name>",
+    "description": "<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_resource.create_folder_under_cycle(projectId="<project_id>", versionId="<version_id>", cycleId="<cycle_id>", data=data)
+
+# Add a new test case for a test cycle
+data = {
+    "issues":["<case_key>"],
+}
+ret_data = zsquad.api.execution_resource.add_test_to_cycle(projectId="<project_id>", cycleId="<cycle_id>", method="1", data=data)
+
+# Obtain the execution details
+exec_details = zsquad.api.execution_resource.get_execution_information(executionId="<execution_id>")
+
+# Obtain the execution steps from an execution
+exec_steps = zsquad.api.step_result_resource.get_list_of_step_result(executionId="<execution_id>")
+
+# Update the status of an execution step
+step_status = zsquad.api.step_result_resource.update_step_result_information(stepResultId="<execution_step_id>", status=2)
+
+# Update the execution status
+exec_status = zsquad.api.execution_resource.update_execution_details(executionId="<execution_id>", status=2)
+
+# Update a folder name and description
+data = {
+    "description": "<new_folder_decription>"
+}
+ret_data = zsquad.api.folder_resource.update_folder_information(projectId="<project_id>", versionId="<version_id>", cycleId="<cycle_id>", folderId="<folder_id>", name="<new_folder_name>")
+
+# Delete 3 test executions
+delete_status = zsquad.api.execution_resource.delete_bulk_execution(executionId=["<exec_id_1>", "<exec_id_2>", "<exec_id_3>"])
+
+# Show the progress of a job
+job_status = zsquad.api.execution_resource.get_job_progress_status(jobProgressToken="<job_progress_token>")
+
+# Get a test step's detailed information
+test_step = zsquad.api.teststep_resource.get_teststep_information(testStepId="<test_step_id>", issueId="<issue_id>")
+
+# Add a attachment (for a execution result: entityId=executionId and entityType='Execution')
+attach = zsquad.api.attachment_resource.add_attachment_into_entity(filePath="<file_path>", entityId="<entity_id>", entityType='<entity_type>')
+
+# Add a assignee to a execution result
+add_assignee = zsquad.api.execution_resource.add_assignee_to_execution(executionId="<exec_id>", assignee="<username>")

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 = nassauwinter@gmail.com
 description = Zephyr (TM4J) Python REST API wrapper

setup.cfg

@@ -2,7 +2,7 @@
 from requests import Session
 
 from zephyr.scale.scale import DEFAULT_BASE_URL, ZephyrSession
-from zephyr.scale.zephyr_session import INIT_SESSION_MSG, InvalidAuthData
+from zephyr.common.zephyr_session import INIT_SESSION_MSG, InvalidAuthData
 
 REQUESTS_SESSION_PATH = "requests.sessions.Session"
 GETLOGGER_PATH = "logging.getLogger"
@@ -20,7 +20,7 @@ def test_creation(self, mocker):
         assert zsession.base_url == DEFAULT_BASE_URL, (f"Attribute base_url expected to be {DEFAULT_BASE_URL}, "
                                                        f"not {zsession.base_url}")
         assert isinstance(zsession._session, Session)
-        logger_mock.assert_called_with("zephyr.scale.zephyr_session")
+        logger_mock.assert_called_with("zephyr.common.zephyr_session")
 
     def test_token_auth(self, mocker):
         """Test token auth"""

tests/unit/test_zephyr_session.py

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

zephyr/__init__.py

@@ -0,0 +1,7 @@
+from .zephyr_session import ZephyrSession
+
+
+class EndpointTemplate:
+    """Class with basic constructor for endpoint classes"""
+    def __init__(self, session: ZephyrSession):
+        self.session = session

zephyr/common/endpoint_template.py

@@ -13,7 +13,7 @@ class InvalidAuthData(Exception):
 
 class ZephyrSession:
     """
-    Zephyr Scale basic session object.
+    Zephyr basic session object.
 
     :param base_url: url to make requests to
     :param token: auth token
@@ -83,22 +83,38 @@ def delete(self, endpoint: str, **kwargs):
         """Delete request wrapper"""
         return self._request("delete", endpoint, **kwargs)
 
-    def get_paginated(self, endpoint, params=None):
+    def get_paginated(self, endpoint, params=None, zscale=True):
         """Get paginated data"""
         self.logger.debug(f"Get paginated data from endpoint={endpoint} and params={params}")
         if params is None:
             params = {}
 
         while True:
             response = self.get(endpoint, params=params)
-            if "values" not in response:
-                return
-            for value in response.get("values", []):
-                yield value
-            if response.get("isLast") is True:
-                break
-            params_str = urlparse(response.get("next")).query
-            params.update(parse_qs(params_str))
+            if zscale:  # Zephyr Scale
+                if "values" not in response:
+                    return
+                for value in response.get("values", []):
+                    yield value
+                if response.get("isLast") is True:
+                    break
+                params_str = urlparse(response.get("next")).query
+                params.update(parse_qs(params_str))
+
+            else:  # Zephyr Squad
+                if not response.get("executions"):
+                    return
+                for execution in response.get("executions", []):
+                    yield execution
+                if response.get("linksNew")[-1] == response.get("currentIndex") or \
+                    response.get("maxResultAllowed") + response.get("offset", 0) >= response.get("totalCount"):
+                    break
+
+                if params.get("offset"):
+                    new_offset = params['offset'] + response.get("maxResultAllowed")
+                else:
+                    new_offset = response.get("maxResultAllowed")
+                params.update(offset=new_offset)
         return
 
     def post_file(self, endpoint: str, file_path: str, to_files=None, **kwargs):

zephyr/scale/zephyr_session.py renamed to zephyr/common/zephyr_session.py

@@ -1,6 +1,6 @@
 import logging
 
-from zephyr.scale.zephyr_session import ZephyrSession
+from zephyr.common.zephyr_session import ZephyrSession
 from zephyr.scale.cloud.endpoints import (AutomationEndpoints,
                                           EnvironmentEndpoints,
                                           FolderEndpoints,

zephyr/scale/cloud/cloud_api.py

@@ -1,6 +1,6 @@
 from json import dumps
 
-from ...zephyr_session import ZephyrSession
+from zephyr.common.zephyr_session import ZephyrSession
 
 
 class AutomationEndpoints: