ETM samples

Author: ROMAIN BARTH

elmclient/examples/etm_scenario1.py

@@ -9,7 +9,21 @@
 
 #ETM scenario1: Run a query for all Test Case modified since 01/01/2025 -> Display their URLs, identifier and title
 #
+#parameters
+jazzhost = 'https://jazz.ibm.com:9443'
+
+username = 'ibm'
+password = 'ibm'
+
+jtscontext = 'jts'
+qmappdomain  = 'qm'
 
+# the project+component+config that will be queried
+proj = "SGC Quality Management"
+comp = "SGC MTM"
+conf = "SGC MTM Production stream"
+
+#### DO NOT TOUCH elmclient initializing####### Go to scenario1
 import sys
 import os
 import csv
@@ -34,21 +48,6 @@
 logger = logging.getLogger(__name__)
 utils.log_commandline( os.path.basename(sys.argv[0]) )
 
-#parameters
-jazzhost = 'https://jazz.ibm.com:9443'
-
-username = 'ibm'
-password = 'ibm'
-
-jtscontext = 'jts'
-qmappdomain  = 'qm'
-
-# the project+component+config that will be queried
-proj = "SGC Quality Management"
-comp = "SGC MTM"
-conf = "SGC MTM Production stream"
-
-
 # caching control
 # 0=fully cached (but code below specifies queries aren't cached) - if you need to clear the cache, delet efolder .web_cache
 # 1=clear cache initially then continue with cache enabled
@@ -95,21 +94,28 @@
 #####################################################################################################
 #SCENARIO 1 
 # find the test cases with dcterms modified > 2025-01-01
+
+#Get the query base of the QM configuration
 tcquerybase = c.get_query_capability_uri("oslc_qm:TestCaseQuery")
 if not tcquerybase:
     raise Exception( "TestCaseQueryBase not found !!!" )
 
+# OSLC query to find all the test cases modified after the 1st of January 2025, returns dcterms:identifier, dcterms:title, rqm_qm:shortIdentifier
 tcs = c.execute_oslc_query(
         tcquerybase,
         whereterms=[['dcterms:modified','>','"2025-01-01T00:00:00.000Z"^^xsd:dateTime']],
         select=['dcterms:identifier,dcterms:title,rqm_qm:shortIdentifier'],
         prefixes={rdfxml.RDF_DEFAULT_PREFIX["dcterms"]:'dcterms',rdfxml.RDF_DEFAULT_PREFIX["rqm_qm"]:'rqm_qm'} # note this is reversed - url to prefix
         )
 
-nbTC = len(tcs) #count the number of Test case returned by the query
+nbTC = len(tcs) #count the number of Test case returned by the query and display it
 print(f"The query returned {nbTC} Test Cases")
 print("----------------------------------------------------------")
+
+#initialize a count variable to zero
 count = 0
+
+#looping through the test cases returned by the query -> print data
 for TCurl in tcs:
     count+=1
     print(f"Test case #{count}")

elmclient/examples/etm_scenario2.py

@@ -11,7 +11,21 @@
 #• Modify its title and description
 #• Delete an existing validates Requirement link if it exists
 #• Add 2 Validated By links, 1 to a DNG requirement – 1 to a DWA requirement
+#parameters
+jazzhost = 'https://jazz.ibm.com:9443'
+
+username = 'ibm'
+password = 'ibm'
 
+jtscontext = 'jts'
+qmappdomain  = 'qm'
+
+# the project+component+config that will be queried
+proj = "SGC Quality Management"
+comp = "SGC MTM"
+conf = "SGC MTM Production stream" #conf="" if project is optout
+
+#### DO NOT TOUCH elmclient initializing####### Go to scenario2
 import sys
 import os
 import csv
@@ -38,20 +52,6 @@
 logger = logging.getLogger(__name__)
 utils.log_commandline( os.path.basename(sys.argv[0]) )
 
-#parameters
-jazzhost = 'https://jazz.ibm.com:9443'
-
-username = 'ibm'
-password = 'ibm'
-
-jtscontext = 'jts'
-qmappdomain  = 'qm'
-
-# the project+component+config that will be queried
-proj = "SGC Quality Management"
-comp = "SGC MTM"
-conf = "SGC MTM Production stream" #conf="" if project is optout
-
 
 # caching control
 # 0=fully cached (but code below specifies queries aren't cached) - if you need to clear the cache, delet efolder .web_cache
@@ -105,50 +105,56 @@
 #• Delete an existing validates Requirement link if it exists
 #• Add 2 Validated By links, 1 to a DNG requirement – 1 to a DWA requirement
 
+#Get the query base of the QM configuration
 tcquerybase = c.get_query_capability_uri("oslc_qm:TestCaseQuery")
 if not tcquerybase:
     raise Exception( "TestCaseQueryBase not found !!!" )
+
+#Put here the ID of a Test Case that exists and that has a validatedBy link
 tcid = 53
 print(f"Querying test case with identifier = {tcid}")
+
+#OSLC query to get the test case with the identifier defined above
 tcs = c.execute_oslc_query(
         tcquerybase,
         whereterms=[['rqm_qm:shortIdentifier','=',f'"{tcid}"']],
         select=['*'],
         prefixes={rdfxml.RDF_DEFAULT_PREFIX["rqm_qm"]:'rqm_qm'} # note this is reversed - url to prefix
         )
 
+#We check if we get only 1 test case in the response.
 if len(tcs.items())==1:
 
-    tc_u = list(tcs.keys())[0]
+    tc_u = list(tcs.keys())[0] #getting the test case URL, it is the first key of the list object tcs.
     print(f"Found Test Case URL: {tc_u}")
     print("Doing a Get on test case url")
-    xml_data,etag = c.execute_get_rdf_xml( tc_u, return_etag=True)
-    #print(ET.tostring(xml_data))
-    
+    xml_data,etag = c.execute_get_rdf_xml( tc_u, return_etag=True) #doing a GET on the Test Case URL, with option to return the etag in order to update the test case later.
     print("Etag:" + etag)
-    #put the TC data in a test case object
+    
+    #put the TC data in a test case object (Class TestCase of the framework)
     tcObject = TestCase.from_etree(xml_data)
 
     #get the title and description
     print(f"Test case title: {tcObject.title}")
     print(f"Test case description: {tcObject.description}")
     print("----------------------------------------------------------")
-    #displaying the links details
+    #displaying the links details, links are stored in the "links" list of the TestCase object
     print("Links details:")
     for link in tcObject.links:
         print(f" - {link.predicate} -> {link.target} (title: {link.title})")
 
     print("----------------------------------------------------------")
 
-    #modifying title and description
+    #modifying title and description, it just add the mention "added by Python" to the title and the description of the Test Case
     tcObject.title += " added by Python"
+    #Description can be empty so we need to check that before modifying it.
     if tcObject.description is None:
         tcObject.description = " added by Python"
     else:
         tcObject.description += " added by Python"
 
 
-    #delete an existing link
+    #delete the first existing link (if it exists), we loop through the link, delete the first link and exit the loop with the break key word
     for link in tcObject.links:
         tcObject.delete_validatesRequirementLink(link.target)
         print(f"Deleting the link to {link.target}")
@@ -172,20 +178,25 @@
 
     print("----------------------------------------------------------")
 
-    #get the data from the test case object
+    #get the data from the test case object, needed to send the PUT update request to actually update the Test Case. 
     xml_data = tcObject.to_etree()
-    #print(ET.tostring(xml_data))
+    
     print("sending the PUT request to update the test case")
+    #To do the PUT request, we need the Test Case URL, the updated XML data of the Test Case and the etag
     response = c.execute_post_rdf_xml(tc_u, data=xml_data, put=True, cacheable=False, headers={'If-Match':etag,'Content-Type':'application/rdf+xml'}, intent="Update the test case"  )
     if response.status_code==200:
         print("Update succesfull")
     else:
         print("Update failed")
 #####################################################################################################
 
+#check if we got no test case
 elif len(tcs.items())==0:
     print("No test case found")
 
+#check if we got more than 1 test case, impossible but we handled that possibility
 else:
     print(f"We found more than one test case with identififer {tcid} !!!???")
+
+#end of the script
 print( "Finished" )

elmclient/examples/etm_scenario3.py

@@ -12,6 +12,21 @@
 #• Save the test case
 #• Add 2 Validated By links, 1 to a DNG requirement – 1 to a DWA requirement
 
+#parameters
+jazzhost = 'https://jazz.ibm.com:9443'
+
+username = 'ibm'
+password = 'ibm'
+
+jtscontext = 'jts'
+qmappdomain  = 'qm'
+
+# the project+component+config that will be queried
+proj = "SGC Quality Management"
+comp = "SGC MTM"
+conf = "SGC MTM Production stream" #conf="" if project is optout
+
+#### DO NOT TOUCH elmclient initializing####### Go to scenario3
 import sys
 import os
 import csv
@@ -38,21 +53,6 @@
 logger = logging.getLogger(__name__)
 utils.log_commandline( os.path.basename(sys.argv[0]) )
 
-#parameters
-jazzhost = 'https://jazz.ibm.com:9443'
-
-username = 'ibm'
-password = 'ibm'
-
-jtscontext = 'jts'
-qmappdomain  = 'qm'
-
-# the project+component+config that will be queried
-proj = "SGC Quality Management"
-comp = "SGC MTM"
-conf = "SGC MTM Production stream" #conf="" if project is optout
-
-
 # caching control
 # 0=fully cached (but code below specifies queries aren't cached) - if you need to clear the cache, delet efolder .web_cache
 # 1=clear cache initially then continue with cache enabled
@@ -128,13 +128,15 @@
 #POST request to create the new test case
 response = c.execute_post_rdf_xml( tc_factory_u, data=xml_data, intent="Create a test case", headers={'Referer': 'https://jazz.ibm.com:9443/qm', 'X-Jazz-CSRF-Prevent': jsessionid }, remove_parameters=['oslc_config.context']  )
 
+#if response is 201, Test Case has been created succesfully
 if response.status_code==201:
     print("Test Case created succesfully")
     #Get the url of the new Test case created
     tcquerybase = c.get_query_capability_uri("oslc_qm:TestCaseQuery")
     if not tcquerybase:
         raise Exception( "TestCaseQueryBase not found !!!" )
 
+    #Getting the created TC to add links
     print(f"Querying test case with title = {tc_title}")
     tcs = c.execute_oslc_query(
             tcquerybase,