API Cookbook

In Jama Connect, there is a flow for executing test cases through the API. This guide will give you an overview of the testing-related objects in Jama Connect and show you the API calls needed to take a test all the way through execution. Some examples will be given from some of our own implementations at Jama.

Getting Familiar with Jama Connect Test Center Objects and Concepts

There are some core objects and concepts to have in mind when working with the Test Center.

Test Case Item

A Test Case Item is like a regular item in Jama, with extra fields (such as steps) and capabilities (it can be executed). Test Cases are created inside Projects just like items, independent of Test Plans. They are also versioned like other items.

Test Run Items

A Test Run Item can be thought of as an execution instance of a Test Case Item. They are created by the system when a Test Cycle is created inside a Test Plan, and they are updated with a status and actual results when executed. A Test Case could have many Test Runs associated with it. These cannot be created directly; this is the reason there is no POST in the /testruns REST endpoint.

Test Plans

A Test Plan is a collection of Test Cases grouped into Groups for organization and Cycles for execution. Test Plans can be created directly.

Test Groups

Test Groups are a grouping of Test Cases inside a Test Plan. They have no direct impact on the way Test Cases are executed; they exist mostly to allow users to group Test Cases into some sort of meaningful sections. For instance, a Test Plan could have groups based on functional breakdowns like “Tree Operations”, “Items”, etc. Although they are not pertinent to execution, each Test Plan must have at least one Test Group in which to place tests. Test Plans are created with a group called “Default Test Group” which can be used or replaced with custom groups.

Test Cycles

Test Cycles are a collection of Test Run Items that correspond to a particular execution of a Test Plan. For example, you could have a Test Cycle for each release candidate build, or Test Cycles for different browsers, depending on what makes sense for your testing. This terminology may be a bit confusing at first when coming from other test management systems, but the thing to keep in mind is that a “Test Run” is a single item, and a “Test Cycle” is a collection of Test Runs that have been run together at the same time for the same organizational purpose.

When a Test Cycle is created, all Test Case Items in that Test Plan have corresponding Test Run Items created in the system for that Test Cycle. Accordingly, a Test Cycle must be created before any Test Case can be executed. Test Cycles cannot be created independently of a Test Plan (there is no POST in the /testcycles endpoint).

An Example: These concepts as written definitions are a bit tricky, so here is a bit of a rundown on how we test internally:

We have a master regression library with hundreds of Test Case Items that we can test. At the time of each release regression, we create a few different Test Plans based on different configurations of the product, in our case, “Release 8.20 – Hosted”, “Release 8.20 – Clients”, “Release 8.20 – Server & Database”. Inside those Test Plans, we add all, or a subset, of the Test Cases in the regression library, grouped by hierarchy, which, in our case, corresponds to areas of the product like “Stream” and “Projects”. To execute these tests, we create one or more Test Cycles in the Test Plan. The “Release 8.20 – Clients” plan, for instance, tests different browsers, so there are cycles like “MacOS Chrome”, “Windows Firefox”, “Internet Explorer”, etc.

Much of our regression library is automated, and our automation tooling executes, and updates results via the API using methods similar (but with much more wrapping) to what will be outlined below.

The Process

This process assumes you already have created Test Case Items that you want to execute. If you are only updating existing executions, you may need to skip further down in the guide.

Creating a Test Plan

First, a Test Plan must be created. If you are planning to use an existing Test Plan that has already been created (using the API or UI), you can skip this section.

POST /testplans with a payload like:

{
"project": 43,
"fields": {
"name": "Connect Plan 1"
}
}
							

project
is the API ID of the project where the Test Plan will be created

name
is the only required field in the payload

If successful, you will get a response like:

{
"meta": {
"status": "Created",
"timestamp": "2018-06-07T18:46:54.094+0000",
"location": "https://yourjama.jamasoftware.net/rest/v1/testplans/20494",
"id": 20494
}
}
							

You will need the id for further operations.

Adding Test Cases to a Test Plan

Test Cases are organized in Test Plans by groups. These groups are only for classification and have no bearing on the way that Test Cases are executed. However, test cases must be added to a Group in the Test Plan; they cannot be added to a Test Plan directly. You can either use the “Default Test Group” present in every Test Plan or create new groups.

To find the default group:
GET /testplans/{testPlanId}/testgroups
where {testPlanId} is the API ID of the existing test plan, (from above, 20494)

If successful, you will get a response like:

{
"meta": {
"status": "OK",
"timestamp": "2018-06-07T19:16:01.311+0000",
"pageInfo": {
"startIndex": 0,
"resultCount": 1,
"totalResults": 1
}
},
"links": {},
"data": [
{
"id": 157,
"name": "Default Test Group"
}
]
}
							

In a brand-new Test Plan, “Default Test Group” will be the only group. You will need its id if you plan to add test cases to it, or:

To add your own group:

POST /testplans/{testPlanId}/testgroups
with a payload like:
where {testPlanId} is the API ID of the existing test plan (from above, 20494)

{
"name": "Stream"
}
							

name
is the only required field in the payload

If successful, you will get a response like:

{
"meta": {
"status": "Created",
"timestamp": "2018-06-07T19:20:35.340+0000",
"location": "https://yourjama.jamasoftware.net/rest/v1/testplans/20494/testgroups/160",
"id": 160
}
}
							

You will need the id for further operations

To add a Test Case to a Group:

At this time, there is no batch operation for adding Test Cases, so each test case must be added individually using:

POST /testplans/{testPlanId}/testgroups/{testGroupId}/testcases
with a payload containing a single test case id like:

where {testPlanId} is the API ID of the existing test plan (from above, 20494) and {testGroupId} is the API ID of the Test Group (from above, 157 for the default group, 160 for the custom)

{
"testCase": 20497
}
							

testCase
is the only item in the payload and should be set to the API ID of the Test Case you want to add

If successful, you will get a response like:

{
"meta": {
"status": "Created",
"timestamp": "2018-06-07T19:36:44.452+0000",
"location": "https://yourjama.jamasoftware.net/rest/v1/testplans/20494/testgroups/160/testcases/20497",
"id": 20497
}
}
							

The id returned in this case should match the id of the Test Case you provided in the payload

Creating a Test Cycle

A Test Cycle must be created to execute tests. Test Cycles are created through an existing Test Plan.

POST /testplans/{testPlanId}/testcycles
with a payload like:
where {testPlanId} is the API ID of the existing test plan (from above, 20494)

{
"fields": {
"name": "Internet Explorer",
"startDate": "2018-06-06",
"endDate": "2018-06-13"
}
}
							

name, startDate, and endDate are the only required fields in the payload. Note that there are other payload options for specifying which Test Groups and statuses are added to the Cycle, but those won’t be discussed here. Consult the API documentation for those options.

If successful, you will get a response like:

{
"meta": {
"status": "Created",
"timestamp": "2018-06-07T20:39:05.921+0000",
"location": "https://yourjama.jamasoftware.net/rest/v1/testcycles/20536",
"id": 20536
}
}
							

You will need the id for further operations

Finding an Existing Test Cycle:

If you need to work with an existing Test Cycle, it can be found in this manner.

GET /testplans/{testPlanId}/testcycles where {testPlanId} is the API ID of the existing test plan (from above, 20494)

If successful, you will get a response like:

{
"meta": {
"status": "OK",
"timestamp": "2018-06-08T15:57:09.863+0000",
"pageInfo": {
"startIndex": 0,
"resultCount": 2,
"totalResults": 2
}
},
"links": {
... omitted for brevity ...
},
"data": [
{
"id": 20510,
"documentKey": "JEET1-TSTCY-17",
"globalId": "70957",
"itemType": 36,
"project": 43,
"createdDate": "2018-06-07T19:58:19.000+0000",
"modifiedDate": "2018-06-07T19:58:19.000+0000",
"lastActivityDate": "2018-06-07T19:58:19.000+0000",
"createdBy": 5,
"modifiedBy": 5,
"fields": {
"documentKey": "JEET1-TSTCY-17",
"globalId": "70957",
"name": "Build 2018-06-06",
"testPlan": 20494,
"startDate": "2018-06-07",
"endDate": "2018-06-15",
"description": "",
"project": 43
},
"resources": {
"self": {
"allowed": [
"GET",
"PUT",
"PATCH",
"DELETE"
]
}
},
"type": "testcycles"
},
... second object omitted for cookbook example brevity ...
]
}
							

You will need the id for further operations

Executing a Test

You now have almost all the data needed to record a test execution. Before you can do that, though, you need to find the actual Test Run object created when you created the Test Cycle. You will need the id of the Test Case Item, the Test Plan, and the Test Cycle

GET /rest/v1/testruns?testCycle={testCycleId}&testCase={testCaseId}&testPlan={testPlanId}
where {testPlanId} is the API ID of the existing test plan (from above, 20494), {testCycleId} is the API ID of the Test Cycle (from above, 20536 for the created one, 20510 for the existing), {testCaseId} is the API ID of the Test Case to be executed (from above, 20497)

If successful, you will get a response that looks like:

{
"meta": {
"status": "OK",
"timestamp": "2018-06-07T21:01:36.530+0000",
"pageInfo": {
"startIndex": 0,
"resultCount": 1,
"totalResults": 1
}
},
"links": { ... removed for cookbook example brevity ...
},
"data": [
{
"id": 20539,
"documentKey": "JEET1-TSTRN-520",
"globalId": "70962",
"itemType": 37,
"project": 43,
"createdDate": "2018-06-07T20:39:02.000+0000",
"modifiedDate": "2018-06-07T20:39:02.000+0000",
"lastActivityDate": "2018-06-07T20:39:02.000+0000",
"createdBy": 5,
"modifiedBy": 5,
"fields": {
"documentKey": "JEET1-TSTRN-520",
"globalId": "70962",
"name": "One",
"testPlan": 20494,
"testCycle": 20536,
"testRunSetName": "Internet Explorer",
"testCase": 20497,
"description": "",
"modifiedDate": "2018-06-07",
"testRunStatus": "NOT_RUN",
"project": 43,
"forcePassed": false
},
"resources": {
"self": {
"allowed": [
"GET",
"PUT",
"PATCH"
]
}
},
"testCaseVersionNumber": 1,
"testCaseCurrentVersionNumber": 1,
"sortOrderFromTestGroup": 1,
"testGroup": [
20536,
160
],
"type": "testruns"
}
]
}
							

If you have specified the id for Test Case, Test Plan, and Test Cycle, you should get one Test Run result in the data. You will need the id for further operations.

Next, you will need to either use PUT or PATCH to update the status of this test run:

Test Runs without Steps:

On test runs without steps, you can simply update the testRunStatus field.

PATCH /rest/v1/testruns/{testRunId}
with a payload like:
where {testRunId} is the API ID of the Test Run (from above, 20539)

[
{
"op": "REPLACE",
"path": "/fields/testRunStatus",
"value": "PASSED"
}
]
							

PUT /rest/v1/testruns/{testRunId}
with a payload like:
where {testRunId} is the API ID of the Test Run (from above, 20539)

{
"fields": {
"testRunStatus": "BLOCKED"
}
}
							

Valid values for /fields/testRunStatus are PASSED, NOT_RUN, FAILED, INPROGRESS, and BLOCKED.

If successful, you will get a response like:

{
"meta": {
"status": "OK",
"timestamp": "2018-06-07T21:14:14.611+0000"
}
}
							

Test Runs with Steps

On test runs with steps, you must pass the entire array of test steps (in the original order) with new statuses.

Here is an example of a Test Run object with steps. Note that the testRunSteps array is implicitly ordered by the step number as seen in the UI:

{
"id": 20569,
"documentKey": "JEET1-TSTRN-525",
"globalId": "70967",
"itemType": 37,
"project": 43,
"createdDate": "2018-06-11T21:34:09.000+0000",
"modifiedDate": "2018-06-11T21:34:09.000+0000",
"lastActivityDate": "2018-06-11T21:34:09.000+0000",
"createdBy": 5,
"modifiedBy": 5,
"fields": {
"documentKey": "JEET1-TSTRN-525",
"globalId": "70967",
"name": "One",
"testPlan": 20494,
"testCycle": 20536,
"testRunSetName": "Internet Explorer",
"testCase": 20497,
"description": "",
"testRunSteps": [
{
"action": "You do something",
"expectedResult": "Something happens",
"notes": "",
"status": "NOT_RUN"
},
{
"action": "You do something else",
"expectedResult": "Something else happens",
"notes": "",
"status": "NOT_RUN"
}
],
"modifiedDate": "2018-06-11",
"testRunStatus": "NOT_RUN",
"project": 43,
"forcePassed": false
}
							

Given the two steps above, you can do the following:

PUT /rest/v1/testruns/{testRunId}
with a payload like:

{
"fields": {
"testRunSteps": [
{
"status": "PASSED"
},
{
"status": "PASSED"
}
]
}
}
							

or

{
"fields": {
"testRunSteps": [
{
"status": "FAILED"
},
{
"status": "PASSED"
}
]
}
}
							

The testRunStatus for the Test Run will then be set automatically according to the status field on the steps.

Congratulations! You’ve executed a Test Case through the API!