Add Tests to Cycle

Applies to Zephyr Squad Server 9.0.1 and 4.8, last modified on September 19, 2022

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/addTestsToCycle

Request 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
issues

Required. An array of strings in which items specify the keys of the Jira Test item to be added to a cycle.

projectId

Required. Number. The Jira ID of the project to which the cycle and folder belong. See how to get this ID.

versionId

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 "versionId": -1.

cycleId

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.

folderId

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 "folderId": -1.

assigneeType

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
projectId

Required. Number. The Jira ID of the project to which the target cycle belongs. See how to get this ID.

fromVersionId

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 "versionId": -1.

fromCycleId

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 "fromCycleId": -1.

versionId

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 "versionId": -1.

cycleId

Required. Number. The identifier of the cycle to which tests will be added. See how you can get this ID.

folderId

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 "folderId": -1.

assigneeType

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 "assigneeType": null.

labels

priorities

statuses

hasDefects

components

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:

curl --request POST http://15.20.184.119:8089/rest/zapi/latest/execution/addTestsToCycle ^
     --user "admin:password" ^
     --header "Content-Type:application/json" ^
     --data "{\"method\": 1, \"projectId\": 10600, \"issues\":[\"SAM-1\",\"SAM-2\",\"SAM-3\"], \"versionId\":-1, \"cycleId\": 1500, \"folderId\": 877 }"

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 OK response 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 OK response. 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_progress

    The 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 message property in the response body:

    {
        "zipped": false,
        "summaryMessage": "",
        "totalSteps": 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 message includes the Jira keys of the added tests. If Zephyr Squad failed to add some tests, then other phrase in the response – “These Tests could not be added” – will explain the cause.

Next steps

See Also

Zephyr Squad Server REST API

Highlight search results