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

Test Manager for Trac Plugin - The Python API

TODO The main API is to be described. What follows is a subset of functions recently requested by Users.

Test objects

Test objects are represented by Python classes.

TestCatalog

A container for test cases and sub-catalogs.

Test catalogs are organized in a tree. Since wiki pages are instead on a flat plane, we use a naming convention to flatten the tree into page names. These are examples of wiki page names for a tree:

TC --> root of the tree. This page is automatically created at plugin installation time.

TC_TT0 --> test catalog at the first level. Note that 0 is the catalog ID, generated at creation time.

TC_TT0_TT34 --> sample sub-catalog, with ID '34', of the catalog with ID '0'.

TC_TT27 --> sample other test catalog at first level, with ID '27'.

There is no limit to the depth of a test tree.

Test cases are contained in test catalogs, and are always leaves of the tree:

TC_TT0_TT34_TC65 --> sample test case, with ID '65', contained in sub-catalog '34'.

Note that test case IDs are independent on test catalog IDs.

Attributes:

For the following attributes, use the dictionary assignment syntax: obj['attribute_name'] = new_value

id: A string identifier
page_name: The name of the associated Wiki page holding the title and description.

For the following attributes, use the python object assignment syntax: obj.attribute_name = new_value

title: The title.
description: The catalog body text.

TestCase

A single test case definition, usually specifying the steps required to test a particular condition, and the expected result.

Attributes:

For the following attributes, use the dictionary assignment syntax: obj['attribute_name'] = new_value

id: A string identifier
page_name: The name of the associated Wiki page holding the title and description.

For the following attributes, use the python object assignment syntax: obj.attribute_name = new_value

title: The title.
description: The test case body text.

TestPlan

A test plan represents a particular instance of test execution for a test catalog. You can create any number of test plans on any test catalog (or sub-catalog). A test plan is associated to a test catalog, and to every test case in it, with the initial state equivalent to "to be executed". The association with test cases is achieved through the TestCaseInPlan objects.

For optimization purposes, a TestCaseInPlan is created in the database only as soon as its status is changed (ie from "to be executed" to something else). So you cannot always count on the fact that a TestCaseInPlan actually exists for every test case in a catalog, when a particular test plan has been created for it.

Attributes:

For the following attributes, use the dictionary assignment syntax: obj['attribute_name'] = new_value

id: A string identifier
catid: The string identifier of the associated test catalog
page_name: The name of the associated catalog Wiki page.
name: The test plan name
author: The creator of the test plan
time: The timestamp of the test plan creation, as a long

TestCaseInPlan

This object represents a test case in a test plan. It keeps the latest test execution status (aka verdict).

The status, as far as this class is concerned, can be any string. The plugin logic currently recognizes three hardcoded statuses, but this can be evolved without a need to modify this class.

The history of test execution status changes is instead currently kept in another table, testcasehistory, which is not backed by any Python class. This is a duplication, since the 'changes' table also keeps track of status changes, so the testcasehistory table may be removed in the future.

Attributes:

For the following attributes, use the dictionary assignment syntax: obj['attribute_name'] = new_value

id: A string identifier
planid: The string identifier of the associated test plan
page_name: The name of the associated test case Wiki page.
status: The test case current status. The available default values for this field are "to_be_tested", "successful", "failed", but the USer can customize these in the trac.ini file. See Custom Test Case Outcomes (i.e. states, verdicts) for details.

Getting all the Tickets related to a Test Case

Since: 1.4.1

You now have the ability to programmatically get all of the tickets that have been (explicitly) opened against a test case.

From a TestCase object, you can list the tickets opened against it in any test plan.

From a TestCaseInPlan object, you can list the tickets opened against the test case in the specific plan.

from testmanager.model import TestCase, TestCaseInPlan

tc = TestCase(self.env, id, path)
for t in tc.get_related_tickets():
    # t is the ticket ID

tc = TestCaseInPlan(self.env, id, planid, path)
for t in tc.get_related_tickets():
    # t is the ticket ID

This is achieved by adding two custom fields to the ticket object, named 'testcaseid' for the test case ID, and 'planid' for the test plan ID.

Registering listeners to Test objects lifecycle events

Being based on the Generic Persistent Class plugin, every test object supports a listener interface for components interested in test lifecycle events.

Note: The same stands for any workflow you may have attached to our test objects, by means of the Generic Workflow Engine. Anyway, in this case a specific listener interface has been provided.

To register a listener inside the Generic Persistent Class framework, follow this guide.