The Xray REST API provides the following endpoints for managing the Test Repository information of a given project.
Some endpoints support pagination, using the page
and limit
query parameters.
Hierarchy
- To obtain a list of all Test Repository folders of a given project, including their hierarchy information, you need to specify the key of the respective project.
Returns a JSON object with a list of the folders of the Test Repository.
Request
PATH PARAMETERS
parameter | type | description |
---|---|---|
projectKey | String | project key |
Example Request
Responses
200 OK : application/json : Successful. Returns a JSON object.
Each folder will provide some information, including:
id
: internal folder Id; "-1" corresponds to the Test Repository root folderrank
: rank of the folder in the parent folder ("1" corresponds to the first element)name
: folder's nametestRepositoryPath
: the full Test Repository path of this folderfolders
: sub-folderstestCount
: count of direct child TeststotalTestCount
: total count of all childs Tests
{ "folders": [ { "id": 6, "rank": 1, "name": "Folder1", "testRepositoryPath": "/Folder1" "folders": [], "testCount": 0, "totalTestCount": 0 }, { "id": 7, "rank": 2, "name": "Folder2", "testRepositoryPath": "/Core", "folders": [ { "id": 8, "rank": 1, "name": "Sub2", "testRepositoryPath": "/Core/UI", "folders": [], "testCount": 1, "totalTestCount": 1 }, { ... } ], "testCount": 0, "totalTestCount": 3 } ], }
400 BAD_REQUEST : text/plain : Returns the error.
401 UNAUTHORIZED : text/plain : The Xray license is not valid.
500 INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the folders.
Tests
- To obtain a list of the Tests associated with the Test Repository of a given project, you need to specify the key of project
- To obtain a list of the Tests contained within a given Test Repository folder, you need to specify its folderId, besides the project key
- To change (add/remove) Tests to a given folder, you need to specify the key of the respective project
Returns a JSON object with a list of the Tests contained in a given folder of the Test Repository.
This endpoint supports pagination.
Request
PATH PARAMETERS
parameter | type | description |
---|---|---|
projectKey | String | project key |
folderId | Integer | internal folder Id; "-1" corresponds to the root folder of the Test Repository |
QUERY PARAMETERS
parameter | type | description |
---|---|---|
allDescendants | Boolean | include all descendants (i.e. all child Tests); "false", by default |
page | Integer | page of paginated data (first 1) |
limit | Integer | amount of Tests per paginated data |
Request examples
curl -H "Content-Type: application/json" -X GET -u admin:admin http://yourserver/rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>/tests
curl -H "Content-Type: application/json" -X GET -u admin:admin http://yourserver//rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>/tests?allDescendants=true
Responses
200 OK : text/plain : Successful. Returns a JSON object containing the Tests.
Each test will provide some information, including:
id
: internal Test Idkey
: Test's issue keysummary
: Test's summary- assignee: Test's issue assignee
rank
: rank of the Test in the parent folder ("1" corresponds to the first element)workflowStatus
: Test's workflow status- labels: array of all Test's assigned labels
components
: array of all Test's assigned componentstestType
: Test type (e.g. "Manual", "Cucumber, "Generic")
{ "tests": [ { "id": 24300, "key": "FP-10", "summary": "Issue test create inside folder", "assignee": "", "rank": 1, "workflowStatus": "Open", "labels": [], "components": [], "testType": "Manual", }, { "id": 24301, "key": "FP-11", "summary": "Issue test create inside folder", "assignee": "", "rank": 2, "workflowStatus": "Open", "labels": [], "components": [], "testType": "Manual", }, { ... } ], "total": 3, }
{ "tests": [ { "id": 24300, "key": "FP-10", "summary": "Issue test create inside folder", "assignee": "", "rank": 1, "workflowStatus": "Open", "labels": [], "components": [], "testType": "Manual", }, { "id": 24301, "key": "FP-11", "summary": "Issue test create inside folder", "assignee": "", "rank": 1, "workflowStatus": "Open", "labels": [], "components": [], "testType": "Manual", }, { ... } ], "total": 3, }
400 BAD_REQUEST : text/plain : Returns the error.
401 UNAUTHORIZED : text/plain : The Xray license is not valid.
500 INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the tests.
Add/remove tests to/from the given Test Repository folder. Returns error messages, if there are any.
Request
PATH PARAMETERS
parameter | type | description |
---|---|---|
projectKey | String | project key |
folderId | integer | internal folder Id |
Example
{ "add": [ "CALC-33", "CALC-75" ], "remove": [ "CALC-25", "CALC-45" ] }
Request example
Responses
200 OK : text/plain : Successful. Return error messages, if there are any.
["Issue with key CALC-33 not found or is not of type Test."]
400 BAD_REQUEST : text/plain : Returns the error.
401 UNAUTHORIZED : text/plain : The Xray for JIRA license is not valid.
500 INTERNAL SERVER ERROR : text/plain : An internal error occurred associating the tests.
Folders
- To obtain or update information about a given Test Repository folder, you need to specify both the project key and the internal folder Id
- To remove a folder from the Test Repository, you need to specify both the project key and the internal folder Id
Returns a JSON object with folder information.
Request
PATH PARAMETERS
parameter | type | description |
---|---|---|
projectKey | String | project key |
folderId | integer | internal folder Id |
Request example
curl -H "Content-Type: application/json" -X GET -u admin:admin http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6
Responses
200 OK : application/json : Successful. Returns a JSON object.
{ "id": 6, "rank": 1, "name": "Folder1", "testRepositoryPath": "/Folder1" "testCount": 0, "totalTestCount": 0 }
400 BAD_REQUEST : text/plain : Returns the error.
401 UNAUTHORIZED : text/plain : The Xray license is not valid.
500 INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the folder.
Creates a folder and returns a JSON object with folder information.
Request
PATH PARAMETERS
parameter | type | description |
---|---|---|
projectKey | String | project key |
folderId | integer | internal folder Id; "-1" corresponds to the root folder of the Test Repository |
JSON body attributes
parameter | type | description |
---|---|---|
name | String | name of folder |
Example
{ "name": "Folder1" }
Request example
curl -H "Content-Type: application/json" -X POST -u admin:admin --data @example.json http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/-1
Responses
201 CREATED : application/json : Successful. Returns a JSON object.
{ "id": 6, "rank": 1, "name": "Folder1", "testRepositoryPath": "/Folder1" "testCount": 0, "totalTestCount": 0 }
400 BAD_REQUEST : text/plain : Returns the error.
401 UNAUTHORIZED : text/plain : The Xray for JIRA license is not valid.
500 INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the folder.
Updates an existing folder.
Request
PATH PARAMETERS
parameter | type | description |
---|---|---|
projectKey | String | project key |
folderId | integer | internal folder Id |
JSON body attributes
parameter | type | description |
---|---|---|
name | String | name of folder |
rank | Integer | rank within the parent folder |
Example
{ "name": "Folder1", "rank": 4 }
Request example
curl -H "Content-Type: application/json" -X PUT -u admin:admin --data @example.json http://yourserver/rest/raven/1.0/api/testrepository/FP/folders/6
Responses
204 No content : text/plain : Successful. Does not return anything.
400 BAD_REQUEST : text/plain : Returns the error.
401 UNAUTHORIZED : text/plain : The Xray license is not valid.
500 INTERNAL SERVER ERROR : text/plain : An internal error occurred getting the folder.
Remove folder from the Test Repository.
Request
PATH PARAMETERS
parameter | type | description |
---|---|---|
projectKey | String | project key |
folderId | integer | internal folder Id |
Example Request
Responses
204 No content : text/plain : Successful.
400 BAD_REQUEST : text/plain : Returns the error.
401 UNAUTHORIZED : text/plain : The Xray license is not valid.
500 INTERNAL SERVER ERROR : text/plain : An internal error occurred removing the test.