API: Tests
Use the following API methods to request details about tests.
On this page:
get_test
Returns an existing test.
GET index.php?/api/v2/get_test/:test_id
:test_id | The ID of the test |
:with_data | The parameter to get data (This is optional) |
If you are interested in the test results rather than the tests, please see get_results instead.
Response content
Please see below for a typical example response:
{
"assignedto_id": 1,
"case_id": 1,
"custom_expected": "..",
"custom_preconds": "..",
"custom_steps_separated": [
{
"content": "Step 1",
"expected": "Expected Result 1"
},
{
"content": "Step 2",
"expected": "Expected Result 2"
}
],
"estimate": "1m 5s",
"estimate_forecast": null,
"id": 100,
"priority_id": 2,
"run_id": 1,
"status_id": 5,
"title": "Verify line spacing on multi-page document",
"type_id": 4
}
The following system fields are always included in the response:
Name | Type | Description |
---|---|---|
assignedto_id | int | The ID of the user the test is assigned to |
case_id | int | The ID of the related test case |
estimate | timespan | The estimate of the related test case, e.g. “30s” or “1m 45s” |
estimate_forecast | timespan | The estimate forecast of the related test case, e.g. “30s” or “1m 45s” |
id | int | The unique ID of the test |
milestone_id | int | The ID of the milestone that is linked to the test case |
priority_id | int | The ID of the priority that is linked to the test case |
refs | string | A comma-separated list of references/requirements that are linked to the test case |
run_id | int | The ID of the test run the test belongs to |
status_id | int | The ID of the current status of the test, also see get_statuses |
title | string | The title of the related test case |
type_id | int | The ID of the test case type that is linked to the test case |
Custom fields of test cases are also included in the response and use their system name prefixed with ‘custom_’ as their field identifier. Please see add_case for a full list of available custom field types.
Response codes
200 | Success, the test is returned as part of the response |
400 | Invalid or unknown test |
403 | No access to the project |
get_tests
Returns a list of tests for a test run
GET index.php?/api/v2/get_tests/:run_id
limit=:limit
&offset=:offset
:run_id | The ID of the test run |
If you are interested in the test results rather than the tests, please see get_results instead.
Request filters
The following filters can be applied:
Name | Type | Description |
---|---|---|
:status_id | int (list) | A comma-separated list of status IDs to filter by. |
:limit | int | Number that sets the limit of tests to be shown on the response (Optional parameter. The response size limit is 250 by default) (requires TestRail 6.7 or later) |
:offset | int | Number that sets the position where the response should start from (Optional parameter) (requires TestRail 6.7 or later) |
# All test cases for test run with ID 1 and status 4, 5 (Retest and Failed)
GET index.php?/api/v2/get_tests/1&status_id=4,5
Response content
The response includes an array of tests. Each test in this list follows the same format as get_test.
[
{
"id": 1,
"title": "Test conditional formatting with basic value range",
..
},
{
"id": 2,
"title": "Verify line spacing on multi-page document",
..
},
..
]
info Please Note: As of February 26, 2021 the data structure returned by bulk GET API endpoints will change. These bulk endpoints will no longer return an array of all entities, but will instead return an object with additional pagination fields and an array of up to 250 entities.To see the new response structure and test any necessary code changes, include the following header and value in your API requests: x-api-ident: beta.
New Response Content
The response includes an array of tests. Each test in this list follows the same format as get_test.
{
"offset": 0,
"limit": 250,
"size": 236,
"_links": {
"next": null,
"prev": null,
},
"test": [
{
"id": 1,
"title": "Test conditional formatting with basic value range",
..
},
{
"id": 2,
"title": "Verify line spacing on multi-page document",
..
},
..
]
}
Response codes
200 | Success, the tests are returned as part of the response |
400 | Invalid or unknown test run |
403 | No access to the project |