feat: xray cli tool supports test-plan-key (#566)

Author: DianeMornas

docs/tools/xray.rst

@@ -6,8 +6,11 @@ Export results to Xray
 
 The ``xray`` CLI utility takes your Pykiso Junit test results report and export them on `Xray <https://xray.cloud.getxray.app/>`__.
 
-Upload your results
--------------------
+Upload your results on XRAY using JUNIT xml files
+-------------------------------------------------
+
+Upload the test results to a test execution ticket
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Upload the test results to an existing Xray test execution ticket
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -35,13 +38,14 @@ Options:
   --test-execution-description TEXT   Set or update the description (Jira ticket title) of the Xray test execution ticket
                                       [optional][default value: None] Required when creating a new test execution ticket;
                                       optional when updating an existing one.
+  --test-plan-key TEXT                Xray test plan ticket key's where to add a new test execution for the test results from a JUNIT xml
+                                      (e.g PROJ-456) [optional][default value: None]
   --merge-xml-files                   Merge all the xml files to be send in one xml file
   --not-append-test-results, -na      Do not append new test keys from the .xml(s) to the updated test execution,
                                       only overwrite already existing ones
   --help                              Show this message and exit.
 
 
-
 Upload the test results on a new Xray test execution ticket
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -87,6 +91,22 @@ This is useful when you want to:
 - Maintain a fixed set of tests in your test execution ticket
 - Prevent accidental addition of new tests to an existing test execution
 
+Upload the test results to a test plan ticket
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Upload the test results on an existing test plan ticket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A test plan contains multiple test executions.
+A test plan has a unique JIRA key. A test execution also has a unique JIRA key.
+The user must provide either a test plan key or a test execution key, not both.
+If a test plan key is given, results are uploaded only to new test execution(s) linked to the test plan.
+When creating a new test execution ticket, you must also specify the test execution **summary** and **description**.
+
+.. code:: bash
+
+    xray --user USER_ID --password MY_API_KEY --url "https://xray.cloud.getxray.app/" upload --path-results path/reports/folder --test-plan-key "PROJ-456" --test-execution-summary "My test execution summary" --test-execution-description "My test execution description"
+
 
 Add the Xray decorator to the test functions
 --------------------------------------------

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pykiso"
-version = "1.6.3"
+version = "1.6.4"
 description = "Embedded integration testing framework."
 authors = ["Sebastian Fischer <sebastian.fischer@de.bosch.com>"]
 license = "Eclipse Public License - v 2.0"

src/pykiso/tool/xray/cli.py

@@ -69,6 +69,13 @@ def cli_xray(ctx: dict, user: str, password: str, url: str) -> None:
     default=None,
     type=click.STRING,
 )
+@click.option(
+    "--test-plan-key",
+    help="Key of the test plan ticket where to add new test execution for the test results from a JUnit xml",
+    required=False,
+    default=None,
+    type=click.STRING,
+)
 @click.option(
     "-m",
     "--merge-xml-files",
@@ -91,6 +98,7 @@ def cli_upload(
     test_execution_key: str,
     test_execution_description: str,
     test_execution_summary: str,
+    test_plan_key: str,
     merge_xml_files: bool,
     not_append_test_results: bool,
 ) -> None:
@@ -101,10 +109,15 @@ def cli_upload(
     :param test_execution_key: test execution key where to upload the test results
     :param test_execution_description: update the test execution ticket description - otherwise, keep current description
     :param test_execution_summary: update the test execution ticket summary - otherwise, keep current summary
+    :param test_plan_key: test plan key where to create a new test execution ticket for the test results
     :param merge_xml_files: if True, merge the xml files, else do nothing
     :param not_append_test_results: if True, only overwrite the existing ones (update only), else append the new results from the .xml file(s) to the test execution
 
     """
+    if test_plan_key and test_execution_key:
+        raise ValueError(
+            "You cannot specify both a test plan key and a test execution key. " "Please use either one or the other."
+        )
     # If a new test execution ticket is being created (no key), the user should pass a description and a summary.
     if not test_execution_key and (not test_execution_description or not test_execution_summary):
         raise ValueError(
@@ -134,6 +147,7 @@ def cli_upload(
         test_execution_key=test_execution_key,
         test_execution_summary=test_execution_summary,
         test_execution_description=test_execution_description,
+        test_plan_key=test_plan_key,
     )
 
     responses = []

src/pykiso/tool/xray/xray.py

@@ -41,7 +41,9 @@ def __call__(self, r: requests.PreparedRequest) -> requests.PreparedRequest:
         auth_data = {"client_id": self.client_id, "client_secret": self.client_secret}
 
         try:
-            response = requests.post(self.endpoint_url, data=json.dumps(auth_data), headers=headers, verify=self.verify)
+            response = requests.post(
+                self.endpoint_url, data=json.dumps(auth_data), headers=headers, verify=self.verify
+            )
         except requests.exceptions.ConnectionError as exc:
             err_message = f"ConnectionError: cannot authenticate with {self.endpoint_url}"
             raise XrayException(err_message) from exc
@@ -59,7 +61,9 @@ def __init__(self, base_url: str, client_id: str, client_secret: str, verify: bo
         self.verify = verify
 
         # Create authentication
-        self.auth = ClientSecretAuth(base_url=base_url, client_id=client_id, client_secret=client_secret, verify=verify)
+        self.auth = ClientSecretAuth(
+            base_url=base_url, client_id=client_id, client_secret=client_secret, verify=verify
+        )
 
         # Define the endpoints
         self.rest_endpoint = f"{self.base_url}/api/v2/import/execution"
@@ -317,6 +321,7 @@ def extract_test_results(
     test_execution_key: str | None = None,
     test_execution_summary: str | None = None,
     test_execution_description: str | None = None,
+    test_plan_key: str | None = None,
 ) -> list[str]:
     """
     Extract the test results linked to an xray test key. Filter the JUnit xml files generated by the execution of tests,
@@ -330,6 +335,7 @@ def extract_test_results(
         if none is specified a new test execution ticket will be created
     :param test_execution_summary: update the test execution ticket summary - otherwise, keep current summary
     :param test_execution_description: update the test execution ticket description - otherwise, keep current description
+    :param test_plan_key: test plan key where to create a new test execution ticket for the test results
 
     :return: the filtered test results"""
     xml_results = []
@@ -359,7 +365,7 @@ def extract_test_results(
 
             test_suites = data_dict["testsuites"]["testsuite"]
             xray_dict = create_result_dictionary(
-                test_suites, jira_keys, test_execution_summary, test_execution_description
+                test_suites, jira_keys, test_execution_summary, test_execution_description, test_plan_key
             )
             xml_results = reformat_xml_results(xray_dict, test_execution_key)
         return xml_results

src/pykiso/tool/xray/xray_report.py

@@ -101,6 +101,7 @@ def create_result_dictionary(
     jira_keys: list[str],
     test_execution_summary: str | None = None,
     test_execution_description: str | None = None,
+    test_plan_key: str | None = None,
 ) -> dict:
     """
     Processes test suite data and generates a dictionary containing information
@@ -111,6 +112,7 @@ def create_result_dictionary(
     :param jira_keys: the list of jira keys inside the test execution ticket containing the test results
     :param test_execution_summary: update the test execution ticket description - otherwise, keep current summary
     :param test_execution_description: update the test execution ticket description - otherwise, keep current description
+    :param test_plan_key: test plan key where to create a new test execution ticket for the test results
 
     :return: A dictionary with two keys:
             - "info": Contains metadata about the test execution, including summary,
@@ -144,6 +146,10 @@ def create_result_dictionary(
             "startDate": start_time,
             "finishDate": end_time,
         }
+        if test_plan_key is not None:
+            # if a test plan key is specified, link the test results to the test plan
+            test_execution_ticket["testPlanKey"] = test_plan_key
+
         # if there is a test execution key, update the summary and the description of the test execution ticket
         if test_execution_summary is not None:
             test_execution_ticket["summary"] = test_execution_summary

tests/test_xray_report.py

@@ -359,6 +359,52 @@ def test_create_result_dictionary_with_single_testcase_with_test_execution_summa
     )
 
 
+def test_create_result_dictionary_with_single_testcase_with_test_plan_and_test_execution_summary_and_test_execution_description():
+    test_suites = [
+        {
+            "errors": "0",
+            "failures": "0",
+            "time": "10.5",
+            "timestamp": "2023-01-01T12:00:00",
+            "testcase": {
+                "name": "test_case_1",
+                "time": "10.5",
+                "timestamp": "2023-01-01T12:00:00",
+                "properties": {"property": [{"name": "test_key", "value": "TEST-1"}]},
+            },
+        }
+    ]
+
+    expected_result = {
+        "info": {
+            "description": "Ticket description",
+            "summary": "Ticket summary",
+            "startDate": "2023-01-01T12:00:00+0000",
+            "finishDate": "2023-01-01T12:00:10+0000",
+            "project": "TEST",
+            "testPlanKey": "PROJ-123",
+        },
+        "tests": [
+            {
+                "testKey": "TEST-1",
+                "comment": "test_case_1: Successful execution",
+                "status": "PASSED",
+            }
+        ],
+    }
+
+    assert (
+        create_result_dictionary(
+            test_suites,
+            jira_keys=["TEST-1"],
+            test_execution_summary="Ticket summary",
+            test_execution_description="Ticket description",
+            test_plan_key="PROJ-123",
+        )
+        == expected_result
+    )
+
+
 def test_create_result_dictionary_with_multiple_testcases():
     test_suites = [
         {