Add Tests to Cycle
Before you add Zephyrtests to a cycle, you need to create these items – Jira issues of Zephyr’s Test type – in your Jira project. You can do this through the Jira UI or through the API. For details on the latter, see Create Tests.
Once you have Test items in your Jira project, you can add them to a cycle by sending a POST request to /rest/zapi/latest/execution/addTestsToCycle with a JSON body containing information on the tests to be added. You can specify this information in several ways, see below. A test instance added to a cycle is called a test execution in Zephyr.
Request URL
POST /rest/zapi/latest/execution/addTestsToCycleRequest body
The request body contains a JSON object that specifies the tests to be added and the destination cycle and folder. This JSON object has the method parameter (required, number) that specifies the way in which you add tests:
"method": 1– The tests are added by their issue keys (like PROJ-1234, PROJ-1235, and so on)."method": 2– The tests are added from search results."method": 3– The tests are cloned from an existing cycle or folder.
Each of these methods requires different parameters to be passed in the request body.
Let’s consider the first and the last variants as the most frequently used ones when working with Zephyr via API.
"method": 1 – Add tests by their keys
Use "method": 1 when you need to append tests by their Jira keys (the keys look like PROJ-1234).
{
"method": 1,
"issues":["SAM-1","SAM-2","SAM-3"],
"versionId": -1,
"cycleId": 1500,
"projectId": 10600,
"folderId": 877,
"assigneeType": null
}Property description
Property | Description |
|---|---|
| Required. An array of strings in which items specify the keys of the Jira Test item to be added to a cycle. |
| Required. Number. The Jira ID of the project to which the cycle and folder belong. See how to get this ID. |
| Required. Number. The Jira ID of the project version (version or release) to which the cycle and folder belong. See how to get this ID. If you are not going to use any version, set |
| Required. Number. The identifier of the cycle to which tests will be added. You can get this ID from the response to an API request that created this cycle. See also other ways to get this ID. |
| Optional. Number. The identifier of the folder to which the tests will be added. You can get this ID from the response to an API request that created this folder. See also other ways to get this ID. To add tests to the cycle’s root, use |
| Optional. Specifies the Jira ID of the user to whom new test executions will be assigned. |
"method": 3 - Cloning tests from another cycle or folder
Use "method": 3 if you want to copy tests from some cycle to your cycle or folder.
Note
Cloning works within the same project only.
{
"method": 3,
"projectId": "10600",
"fromVersionId": 11700,
"fromCycleId": -1,
"cycleId": 1500,
"folderId": 877,
"labels": "",
"priorities": "",
"statuses": "",
"hasDefects": false,
"components": "",
"versionId": -1
}Property description
Property | Description |
|---|---|
| Required. Number. The Jira ID of the project to which the target cycle belongs. See how to get this ID. |
| Required. Number. The Jira ID of the project’s version (version or release) to which the source test belongs. See how to get this ID. If you don’t have versions in your project, use |
| Required. Number. The ID of the source cycle to which the desired tests belong. See how you can get this ID. If the desired tests don't belong to any cycle, use |
| Required. Number. The Jira ID of the target project version (version or release) to which the target cycle and folder belong. See how to get this ID If you are not going to use any version, set |
| Required. Number. The identifier of the cycle to which tests will be added. See how you can get this ID. |
| Optional. Number. The identifier of the folder to which the tests will be added. See how you can get this ID. To add tests to the cycle’s root, use |
| Optional. Specifies the ID of the Jira user to whom new test executions will be assigned. If you don’t need to assign them to any users, set |
| |
| |
| |
| |
|
Other request parameters
Every request must include authentication parameters. See Zephyr Squad Server REST API.
Example
This is an example for one of the ways of using the operation ("method": 1). Other ways work similarly:
Operation reference
Response
The request parameters can specify several tests to be added to a cycle. The operation can be successful for some of them and can be failed for others. So, the response you get for the request depends on the operation result and error type.
A request with an invalid JSON format in its body causes an exception on the server side. In this case, the response code is
500 Internal Server Error, and the response body contains the exception text and call stack.In case you miss the authentication data, or your account doesn’t have the needed permissions, the operation returns the
200 OKresponse and the following response body:{ errorDesc": "You do not have the permission to make this request. Login Required.", "errorId": "ERROR" }In other cases, the operation returns the
200 OKresponse. The response body contains the jobProgressToken value –{ "jobProgressToken": "0001638373647292-abc80545a0e-0001" }You need to pass this token to the following request to get the operation result:
GET /rest/zapi/latest/execution/jobProgress/{jobProgressToken-value}?type=bulk_execution_copy_move_job_progressThe response to this second request tells which of your tests were added to the cycle and which were not. To understand this, look at the
messageproperty in the response body:{ "zipped": false, "summaryMessage": "", "total steps": 1, "errorMessage": "", "entityId": "", "message": "The following just happened: <br/> Tests added: <strong><a href='http://15.20.184.119:8089/browse/SAM-13'>SAM-13</a></strong> <br/> <p>These Tests could not be added <br/> Invalid: <strong>-</strong> <br/> Belongs to another project: <strong>-</strong> <br/> Already present in this Test Folder: <strong>-</strong><br/> Not a Test: <strong>-</strong><br/> Permission Denied: <strong>-</strong><br/>", "completedSteps": 1, "timeTaken": "0 min, 12 sec", "stepMessage": "", "progress": 1.0, "id": "0001638372037854-abc80545a0e-0001", "stepLabel": "", "entity": "", "stepMessages": [] }The phrase “Tests added: ” in the
messageincludes the Jira keys of the added tests. If Zephyr Squad failed to add some tests, then another phrase in the response – “These Tests could not be added” – will explain the cause.