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.
GET /rest/raven/1.0/api/testrepository/<projectKey>/folders
Returns a JSON object with a list of the folders of the Test Repository.
Request
PATH PARAMETERS
parameter | type | description |
---|
projectKey | String | project key |
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
GET /rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>/tests
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 |
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.
PUT /rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>/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"
]
}
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
GET /rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>
Returns a JSON object with folder information.
Request
PATH PARAMETERS
parameter | type | description |
---|
projectKey | String | project key |
folderId | integer | internal folder Id |
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.
POST /rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>
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
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.
PUT /rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>
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
}
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.
DELETE /rest/raven/1.0/api/testrepository/<projectKey>/folders/<folderId>
Remove folder from the Test Repository.
Request
PATH PARAMETERS
parameter | type | description |
---|
projectKey | String | project key |
folderId | integer | internal folder Id |
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.