Create Tests

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

A Zephyrtest is a Jira item of the Test type. You can create these items through the Jira API – you do this the same way you create other Jira tickets with the Jira API.

1. Get the ID of the Test item type

Before creating a Test item through the Jira API, you need to get the identifier of the Test item type. To do this, send a GET request to /rest/zapi/latest/util/zephyrTestIssueType. Don’t forget to include authentication parameters in your request:

curl --request GET https://15.20.184.119:8089/rest/zapi/latest/util/zephyrTestIssueType ^
     --user "admin:password"

See also request reference in Zephyr Squad Server API reference.

A successful response has the HTTP status 200 OK, and the desired type ID is in the response body:

{
  "testcaseIssueTypeId": "10005"
}

If the specified authentication parameters are wrong, the server returns 200 OK, but the response body contains the following error message:

{
  "errorDesc": "You do not have the permission to make this request. Login Required.",
  "errorId": "ERROR"
}

2. Create a new Test item

To create a new item of the Test type, send a POST request to /rest/api/2/issue to your Jira instance and pass values of item fields in the request body in the JSON format. Below is a brief description of this request and its parameters. For complete information, see Jira API reference: https://docs.atlassian.com/software/jira/docs/api/REST/latest/#issue-createIssue.

Request URL

POST /rest/api/2/issue

Request body

The request body has values of item fields in the JSON format, for example:

{
  "fields": {
    "project": {
      "id": "10100"
    },
    "summary": "My test",
    "issuetype": {
      "id": "10005"
    },     "assignee": {
       "name": "admin"
    },
    "reporter": {
      "name": "admin"
    },
    "description": "Some description"
  }
}

The list of required fields can differ from one Jira instance to another. So, in general, the fields to be passed in the request body depend on your Jira settings. Typically, you need to specify the following:

Field Description
fields/project/id

The Jira ID (integer) of the project to which the new item will belong. See how to get this ID. Don’t confuse this ID with the project key. The project ID is used by Jira internally, while the project key is visible and identifies the project to users in the Jira UI. For instance, in the issue key PROJ-22, the substring PROJ is the project key.

fields/issuetype

The type ID of the new item. Pass the ID that you received on step 1.

fields/summary

The value of the item’s Summary field. This field typically serves as the item title.

In the example above, we’ve also set the following frequently used fields:

Field Description
fields/description

The value of the item’s Description field.

fields/reporter

The Jira user account, who is creating the item. In the Jira UI, this user will be shown as the issue reporter.

fields/assignee

The user account in your Jira instance to whom the new item will be assigned.

Example

curl --request POST https://15.207.184.119:8089/rest/api/2/issue ^
     --user "admin:password" ^
     --header "Content-Type: application/json" ^
     --data "{\"fields\": {\"project\": {\"id\": \"10100\"}, \"summary\": \"My test\", \"issuetype\": {\"id\": \"10005\"} } }"

Response

A successful response has the HTTP status 200 OK, and the response body contains information about the new Test item, for example:

{
  "id": "24620",
  "key": "PROJ-22",
  "self": "http://15.20.184.119:8089/rest/api/2/issue/24620"
}

Field Description
id

The internal Jira identifier of the new item. You can use it in Zephyr API operations you call later.

key

The key of the new item. This key identifies the item to users in the Jira UI. It is also frequently used in URLs.

self

A URL that provides information about the new item. Send a GET request to this URL to receive item fields’ values.

In case of an error, the server returns a 4xx response code and the error description in the response body. Here are some examples:

  • If the request body doesn’t include a required field like project/id, issuetype/id or summary, or has invalid (non-existing) IDs, the response will be 400 Bad Request and the response body will contain an error message like these –

    {
      "errorMessages": [],
      "errors": {
        "project": "project is required"
      }
    }

    {
      "errorMessages": [],
      "errors": {
        "issuetype": "valid issue type is required"
      }
    }

  • In case of an authentication error, the response code will be 400 Bad Request, and the response body will contain several messages: one per each field that cannot be set –

    {
      "errorMessages": [],
      "errors": {
        "summary": "Field 'summary' cannot be set. It is not on the appropriate screen, or unknown.",
        "description": "Field 'description' cannot be set. It is not on the appropriate screen, or unknown.",
        "reporter": "Field 'reporter' cannot be set. It is not on the appropriate screen, or unknown.",
        "assignee": "Field 'assignee' cannot be set. It is not on the appropriate screen, or unknown."
      }
    }

  • If the request body contains invalid JSON code, the response will be 400 Bad Request and the response body will have the description of the error.

    If the request’s Content-Type header specifies an unsupported data type (like application/xml), the response code will be 415 Unsupported Media Type.

Next steps

After you created tests, you can add test steps to them.

Add Steps to Tests

See Also

Zephyr Squad Server REST API

Highlight search results