Changes between Initial Version and Version 1 of TestManagerForTracPluginRPCApi

Timestamp:

Jan 20, 2011, 4:40:42 PM (13 years ago)

Author:

Roberto Longobardi

Comment:

--

TestManagerForTracPluginRPCApi

@@ +1 @@
+= Test Manager for Trac Plugin - The XML-RPC API =
+
+[[BR]]
+The [wiki:TestManagerForTracPlugin TestManager plugin] can be used programmatically to create and manage Test Catalogs, Test Cases and Test Plans, and to set the test execution verdicts of Test Cases in a plan.
+
+This page describes the '''XML-RPC API''', but there are alternatives:
+
+ * A '''HTTP RESTful''' API, allowing you to remotely control your test artifacts by means of simple HTTP GET requests, 
+ * A '''Python''' API, allowing for a fine-grained control over any artifact, managing their life-cycle, listening to events, reacting to status changes and workflow transitions.
+
+The Test Manager RPC API leverages the [wiki:XmlRpcPlugin XmlRpcPlugin], which must be installed in Trac for you to be able to use the following API.
+
+[[BR]]
+== The exported functions ==
+
+[[BR]]'''createTestCatalog'''(self, req, parent_catalog_id, title, description)[[BR]]
+        Creates a new test catalog, in the parent catalog specified, 
+        with the specified title and description.
+        To create a root catalog, specify '' as the parent catalog.
+        Returns the generated object ID, or '-1' if an error occurs.
+
+[[BR]]'''createTestCase'''(self, req, catalog_id, title, description)[[BR]]
+        Creates a new test case, in the catalog specified, with the 
+        specified title and description.
+        Returns the generated object ID, or '-1' if an error occurs.
+        
+[[BR]]'''createTestPlan'''(self, req, catalog_id, name)[[BR]]
+        Creates a new test plan, on the catalog specified, with the 
+        specified name.
+        Returns the generated object ID, or '-1' if an error occurs.
+        
+[[BR]]'''deleteTestObject'''(self, req, objtype, id)[[BR]]
+        Deletes the test object of the specified type identified
+        by the given id. 
+        Returns True if successful, False otherwise.
+        
+[[BR]]'''modifyTestObject'''(self, req, objtype, id, attributes={})[[BR]]
+        Modifies the test object of the specified type identified
+        by the given id.
+        Returns True if successful, False otherwise.
+        
+[[BR]]'''setTestCaseStatus'''(self, req, testcase_id, plan_id, status)[[BR]]
+        Sets the test case status.
+        Returns True if successful, False otherwise.
+        
+[[BR]]'''getTestCatalog(self, req, catalog_id)[[BR]]
+        Returns the catalog properties.
+        The result is in the form, all strings:
+        (wiki_page_name, title, description)
+        
+[[BR]]'''getTestCase'''(self, req, testcase_id, plan_id='')[[BR]]
+        Returns the test case properties.
+        If plan_id is provided, also the status of the test case in the
+        plan will be returned.
+        Each result is in the form, all strings:
+                If plan_id is NOT provided:
+                        (wiki_page_name, title, description)
+                If plan_id is provided:
+                        (wiki_page_name, title, description, status)
+                        
+[[BR]]'''getTestPlan'''(self, req, catalog_id, plan_id)[[BR]]
+        Returns the test plan properties.
+        The result is in the form, all strings:
+        (wiki_page_name, name)
+        
+[[BR]]'''listSubCatalogs'''(self, req, catalog_id)[[BR]]
+        Returns a iterator over the direct sub-catalogs of the specified 
+        catalog.
+        Each result is in the form, all strings:
+        (test_catalog_id, wiki_page_name, title, description)
+        
+[[BR]]'''listTestPlans'''(self, req, catalog_id)[[BR]]
+        Returns a iterator over the test plans associated 
+        to the specified catalog.
+        Each result is in the form, all strings:
+        (testplan_id, name)
+        
+[[BR]]'''listTestCases'''(self, req, catalog_id, plan_id='')[[BR]]
+        Returns a iterator over the test cases directly in the 
+        specified catalog (no sub-catalogs).
+        If plan_id is provided, also the status of the test case in the
+        plan will be returned.
+        Each result is in the form, all strings:
+                If plan_id is NOT provided:
+                        (testcase_id, wiki_page_name, title, description)
+                If plan_id is provided:
+                        (testcase_id, wiki_page_name, status)
+
+[[BR]]
+[[BR]]
+== Examples ==
+
+This section presents a set of usage examples for this RPC API.
+
+Just copy this code and paste into a file with "example.py" extension, adapt the initial URL to point to your server, port and project, and run it from a command line with {{{python example.py}}}.
+
+{{{
+import xmlrpclib 
+                 
+server = xmlrpclib.ServerProxy("http://user@yourserver:port/yourproject/rpc")
+
+print ">> Creating test catalog"
+root_cat = server.testmanager.createTestCatalog('', "Test Root Catalog RPC", "This is a wonderful catalog.")
+print root_cat
+
+print ">> Creating sub-catalog"
+sub_cat = server.testmanager.createTestCatalog(root_cat, "Test Sub-Catalog RPC", "This is a wonderful sub-catalog.")
+print sub_cat
+
+print ">> Creating two test cases in the root catalog"
+tc_1 = server.testmanager.createTestCase(root_cat, "Test Case 1", "This is a wonderful test case.")
+print tc_1
+tc_2 = server.testmanager.createTestCase(root_cat, "Test Case 2", "This is an even more wonderful test case.")
+print tc_2
+
+print ">> Creating two test cases in the sub-catalog"
+tc_3 = server.testmanager.createTestCase(sub_cat, "Test Case Sub 3", "This is a wonderful test case.")
+print tc_3
+tc_4 = server.testmanager.createTestCase(sub_cat, "Test Case Sub 4", "This is an even more wonderful test case.")
+print tc_4
+
+print ">> Listing sub-catalogs of root test catalog"
+for tc in server.testmanager.listSubCatalogs(root_cat):
+    for v in tc:
+        print v
+
+print ">> Listing test cases in root test catalog"
+for tc in server.testmanager.listTestCases(root_cat):
+    for v in tc:
+        print v
+
+print ">> Creating a test plan on the root catalog"
+tplan = server.testmanager.createTestPlan(root_cat, "Test Root Plan RPC", "This is a wonderful test plan.")
+print tplan
+
+print ">> Listing test plans available on specified test catalog"
+for tp in server.testmanager.listTestPlans('0'):
+    for v in tp:
+        print v
+
+print ">> Listing test cases for root test plan on root test catalog, with their status"
+for tc in server.testmanager.listTestCases(root_cat, tplan):
+    for v in tc:
+        print v
+
+print ">> Getting root test catalog properties"
+for v in server.testmanager.getTestCatalog(root_cat):
+    print v
+
+print ">> Modifying root test catalog title and description"
+print server.testmanager.modifyTestObject('testcatalog', root_cat, {'title': "Test Root Catalog Modified", 'description': "This is no more a wonderful catalog."})
+
+print ">> Verifying root test catalog properties has been changed"
+for v in server.testmanager.getTestCatalog(root_cat):
+    print v
+
+print ">> Getting first test case properties"
+for v in server.testmanager.getTestCase(tc_1):
+    print v
+
+print ">> Getting test plan on root catalog properties"
+for v in server.testmanager.getTestPlan(tplan, root_cat):
+    print v
+
+#
+# These simple functions leverage the base functions to demostrate some more articulated usage.
+#
+
+# Recursive function to print a whole sub-catalog and its contained test cases
+def printSubCatalog(cat_id):
+    for subc in server.testmanager.listSubCatalogs(cat_id):
+        subc_id = subc[0]
+        print subc[2]
+        printSubCatalog(subc_id)
+
+    for tc in server.testmanager.listTestCases(cat_id):
+        print tc[2]
+
+# Recursive function to print a whole sub-catalog and its contained test cases with status
+def printSubPlan(cat_id, plan_id, indent):
+    tcat = server.testmanager.getTestCatalog(cat_id)
+    print str([' ' for i in range(indent)]) + tcat[1]
+
+    for subc in server.testmanager.listSubCatalogs(cat_id):
+        subc_id = subc[0]
+        printSubPlan(subc_id, plan_id, indent + 1)
+
+    for tcip in server.testmanager.listTestCases(cat_id, plan_id):
+        tc_id = tcip[0]
+        tc_status = tcip[2]
+        tc = server.testmanager.getTestCase(tc_id)
+        tc_title = tc[1]
+        print str([' ' for i in range(indent)]) + tc_title + ": "+tc_status
+
+# Entry point to print a whole test plan and its contained test cases with status
+def printPlan(cat_id, plan_id):
+    p = server.testmanager.getTestPlan(plan_id, cat_id)
+    
+    print p[1]
+
+    printSubPlan(cat_id, plan_id, 0)
+
+
+# Now, let's use the functions defined above
+
+print ">> Printing complete test catalog tree"
+printSubCatalog(root_cat)
+
+print ">> Printing complete test plan tree"
+printPlan(root_cat, tplan)
+
+print ">> Setting test case status"
+print server.testmanager.setTestCaseStatus(tc_2, tplan, 'successful')
+
+print ">> Printing test case status just set"
+for v in server.testmanager.getTestCase(tc_2, tplan):
+    print v
+
+print ">> Changing test case status"
+print server.testmanager.setTestCaseStatus(tc_2, tplan, 'failed')
+
+print ">> Verifying the test case status has been changed"
+for v in server.testmanager.getTestCase(tc_2, tplan):
+    print v
+
+}}}