[ Home | Latest changes | Image gallery | ​Video tutorial on Youtube | Quick setup guide | ​Download | ​Source | Bugs/Feature requests ]

Test Manager for Trac Plugin - The XML-RPC API

The 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 XmlRpcPlugin, which must be installed in Trac for you to be able to use the following API.

This API is present in the TestManager plugin since rel. 1.4.3.

The exported functions

createTestCatalog(parent_catalog_id, title, description)

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.

createTestCase(catalog_id, title, description)

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.

createTestPlan(catalog_id, name)

Creates a new test plan, on the catalog specified, with the specified name. Returns the generated object ID, or '-1' if an error occurs.

deleteTestObject(objtype, id)

Deletes the test object of the specified type identified by the given id. Returns True if successful, False otherwise.

modifyTestObject(objtype, id, attributes)

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 Python API. Custom fields ARE supported. Returns True if successful, False otherwise.

setTestCaseStatus(testcase_id, plan_id, status)

Sets the test case status. Returns True if successful, False otherwise.

getTestCatalog(catalog_id)

Returns the catalog properties. The result is in the form, all strings: (wiki_page_name, title, description)

getTestCase(testcase_id [, plan_id])

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)

getTestPlan(catalog_id, plan_id)

Returns the test plan properties. The result is in the form, all strings: (wiki_page_name, name)

listRootCatalogs()

Returns an iterator over the root catalogs. Each result is in the form, all strings: (test_catalog_id, wiki_page_name, title, description)

listSubCatalogs(catalog_id)

Returns an 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)

listTestPlans(catalog_id)

Returns a iterator over the test plans associated to the specified catalog. Each result is in the form, all strings: (testplan_id, name)

listTestCases(catalog_id [, plan_id])

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, custom fields)

If plan_id is provided:

(testcase_id, wiki_page_name, status)

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.

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"

trac_project_url = "http://anonymous@localhost:8000/test01/rpc"

print ""
print "-------- Connecting to '%s'" % trac_project_url
print ""

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.", {'remarks': 'These are the Remarks'})
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.", {'component': 'Framework'})
print tc_1
tc_2 = server.testmanager.createTestCase(root_cat, "Test Case 2", "This is an even more wonderful test case.", {'testeffort': '1000'})
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 root-level catalogs"
for tc in server.testmanager.listRootCatalogs():
    for v in tc:
        print v

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", {'longdescription': 'This is a veeeeeery long description.'})
print tplan

print ">> Listing test plans available on specified test catalog"
for tp in server.testmanager.listTestPlans(root_cat):
    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

print ">> Verifying root test catalog properties has been changed"
for v in server.testmanager.getTestCatalog(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-plan 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 (note: this actually creates the TestCaseInPlan object into the DB)"
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 ">> Modifying test case in plan custom field"
print server.testmanager.modifyTestObject('testcaseinplan', tc_2, {'planid': tplan, 'operating_system': "Macosx"})

print ">> Verifying the test case status and custom field have 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)