wiki:TestManagerForTracPluginApi

Version 15 (modified by seccanj, 4 years ago) (diff)

--

Test Manager for Trac Plugin - Public 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.

There are two main APIs available:

  • A 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 RESTful API

In the following, because of the spam filter not allowing more than a few URLs in a page, I have replaced:

http://yourserver/yourproject

with:

<yourserver/yourproject>

Working with Test Catalogs and Test Cases

You can create test catalogs and cases programmatically by means of the following http requests.

Create a root test catalog

Get the following URL:

<yourserver/yourproject>/testcreate?type=catalog&path=TC&title=My%20new%20catalog

this will assign a unique ID (the number 0 in the URL below) to the new catalog, create the corresponding Wiki page and redirect to it. You may discard the response if you don't need to know the catalog ID (last number in the URL):

<yourserver/yourproject>/wiki/TC_TT0

Create a sub-catalog

Get the wollowing URL, where "path" is the name of the parent catalog.

<yourserver/yourproject>/testcreate?type=catalog&path=TC_TT0&title=My%20sub%20catalog this will assign a unique ID (the number 1 in the URL below) to the new catalog, create the corresponding Wiki page and redirect to it. You may discard the response if you don't need to know the catalog ID (last number in the URL):

<yourserver/yourproject>/wiki/TC_TT0_TT1

Create a Test Case

Get the following URL, where "path" is the name of the parent (sub-)catalog.

<yourserver/yourproject>/testcreate?type=testcase&path=TC_TT0_TT1&title=My%20new%20Test%20Case

this will assign a unique ID (the number 0 in the URL below) to the new test case, create the corresponding Wiki page and redirect to it. You may discard the response if you don't need to know the test case ID (last number in the URL):

<yourserver/yourproject>/wiki/TC_TT0_TT1_TC0

Working with Test Plans and setting the status of a Test Case

You can also create a new Test Plan (e.g. for each nightly build) programmatically as follows.

Create a Test Plan from a specific catalog

Get the following URL, where "path" is the name of the (sub-)catalog to create the test plan against.

<yourserver/yourproject>/testcreate?type=testplan&path=TC_TT0&title=Test%20Plan%20for%2020100818

this will assign a unique ID (the number 1 in the URL below) to the new test plan and redirect to displaying the Test Plan: You may discard the response if you don't need to know the plan ID (planid parameter in the URL):

<yourserver/yourproject>/wiki/TC_TT0?planid=1

The Test Plan will contain all of the test cases in the specified catalog, with a status of "Untested".

Note: As you can notice, you can always pass from a test catalog to one of its test plans by adding the "planid=<plan id>" parameter to the test catalog URL. The same also stands for test cases. You can pass to a test case in a particular plan by adding the planid parameter to its URL.

Set a Test Case execution verdict, in the context of a Test Plan

Then, you can set the verdict for any test case in the plan, by means of the following.

Get the following URL, where "id" is the Test Case ID and planid is the Test Plan ID:

<yourserver/yourproject>/teststatusupdate?id=5&planid=1&status=SUCCESSFUL

The supported statuses are currently:

  • TO_BE_TESTED
  • SUCCESSFUL
  • FAILED

Change a [custom] property of any test object

Any property, either standard or custom, of any test object can be set programmatically through the RESTful API.

A test object is identified by its realm (i.e. type) and its key (i.e. in most cases the ID, for test cases in the context of a plan, also the plan ID is required).

The realms that identify the test objects are the following:

  • Test Catalog: testcatalog
  • Test Case: testcase
  • Test Case in the context of a plan (i.e. with a status): testcaseinplan
  • Test Plan: testplan

The realm must be provided to the property update service through the "realm" parameter.

The corresponding key properties, needed to identify any particular object, are:

  • Test Catalog: id
  • Test Case: id
  • Test Case in the context of a plan (i.e. with a status): id, planid
  • Test Plan: id

The key properties are provided to the property update service through the "key" parameter, in the form of a dictionary.

The next things to pass to the service are the name of the property to modify and the new value. Guess what... you use the "name" and "value" parameters, respectively.

For example, to change a Test Case - with ID 5 - custom property "platform" (which has been previously added to the test case type in the trac.ini file) to the new value "Windows", this is the URL to GET:

<yourserver/yourproject>/testpropertyupdate?realm=testcase&key={'id':'5'}&name=platform&value=Windows

Traceability between Test Cases and Tickets

You can open a Ticket and have a traceback to the (e.g. failed) Test Case as follows.

Open a Ticket on a Test Case

Whether you deploy TracTicketTemplatePlugin or not, you can get the following URL, where testCaseNumber is the Test Case complete path, planid is the Test Plan ID and planName is its name:

<yourserver/yourproject>/newticket?testCaseNumber=TC_TT0_TC0&planId=1&planName=Test%20Plan%20for%2020100818&description=Test%20Case:%20[wiki:TC_TT0_TC0],%20Test%20Plan:%20Test%20Plan%20for%2020100818%20(1)

this will redirect to a Ticket edit page, with the Test Case in Test Plan hyperlink in the description (as Wiki page references). You can simply post the form to create the Ticket.



The Python API

TODO: To be described.

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.