= 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. This API is present in the [wiki:TestManagerForTracPlugin TestManager plugin] since rel. 1.4.3. [[BR]] == The exported functions == [[BR]]'''createTestCatalog'''(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'''(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'''(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'''(objtype, id)[[BR]] Deletes the test object of the specified type identified by the given id. Returns True if successful, False otherwise. [[BR]]'''modifyTestObject'''(objtype, id, attributes)[[BR]] Modifies the test object of the specified type identified by the given id. Attributs is a dictionary object with the properties to change and their new values. For documentation about each test object's properties, refer to the [wiki:TestManagerForTracPluginPythonApi Python API]. Returns True if successful, False otherwise. [[BR]]'''setTestCaseStatus'''(testcase_id, plan_id, status)[[BR]] Sets the test case status. Returns True if successful, False otherwise. [[BR]]'''getTestCatalog(catalog_id)[[BR]] Returns the catalog properties. The result is in the form, all strings: (wiki_page_name, title, description) [[BR]]'''getTestCase'''(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'''(catalog_id, plan_id)[[BR]] Returns the test plan properties. The result is in the form, all strings: (wiki_page_name, name) [[BR]]'''listSubCatalogs'''(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'''(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'''(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 named {{{rpc_example.py}}}, '''adapt the initial URL to point to your server, port and project''', and run it from a command line with {{{python rpc_example.py}}}. [[BR]] {{{ import xmlrpclib # # Remember to change the following URL with your information!!! # # For example: # # trac_project_url = "http://anonymous@localhost:8000/my_test_project/rpc" # trac_project_url = "http://user@yourserver:port/yourproject/rpc" print ">> Connecting to '%s'" % trac_project_url server = xmlrpclib.ServerProxy(trac_project_url) 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") 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, indent): tcat = server.testmanager.getTestCatalog(cat_id) indent_blanks = '' for i in range(indent): indent_blanks += ' ' print indent_blanks + tcat[1] for subc in server.testmanager.listSubCatalogs(cat_id): subc_id = subc[0] printSubCatalog(subc_id, indent + 1) for tc in server.testmanager.listTestCases(cat_id): tc_title = tc[2] print indent_blanks + ' ' + tc_title # 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) indent_blanks = '' for i in range(indent): indent_blanks += ' ' print indent_blanks + 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 indent_blanks + ' ' + 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, 0) 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 print ">> Printing again complete test plan tree, showing modified test case status" printPlan(root_cat, tplan) }}}