API: Results
Use the following API methods to request details about test results and to add new test results.
get_results
Returns a list of test results for a test.
GET index.php?/api/v2/get_results/:test_id
| :test_id | The ID of the test |
This method will return up to 250 entries in the response array. To retrieve additional entries, you can make additional requests using the offset filter described in the Request filters section below.
Request filters
The following filters can be applied:
| Name | Type | Description |
|---|---|---|
| :limit/:offset | int | Limit the result to :limit test results. Use :offset to skip records. |
| :status_id | int (list) | A comma-separated list of status IDs to filter by. |
# The latest 10 results for test with ID 1 and statuses 4 or 5 (Retest, Failed)
GET index.php?/api/v2/get_results/1&status_id=4,5&limit=10
Response content
Please see below for a typical response:
[
{
"assignedto_id": 1,
"comment": "This test failed: ..",
"created_by": 1,
"created_on": 1393851801,
"custom_step_results: [
{
..
},
..
]
"defects": "TR-1",
"elapsed": "5m",
"id": 1,
"status_id": 5,
"test_id": 1,
"version": "1.0RC1"
},
..
]
The following system fields are always included in the response:
| Name | Type | Description |
|---|---|---|
| assignedto_id | int | The ID of the assignee (user) of the test result |
| comment | string | The comment or error message of the test result |
| created_by | int | The ID of the user who created the test result |
| created_on | timestamp | The date/time when the test result was created (as UNIX timestamp) |
| defects | string | A comma-separated list of defects linked to the test result |
| elapsed | timespan | The amount of time it took to execute the test (e.g. “1m” or “2m 30s”) |
| id | int | The unique ID of the test result |
| status_id | int | The status of the test result, e.g. passed or failed, also see get_statuses |
| test_id | int | The ID of the test this test result belongs to |
| version | string | The (build) version the test was executed against |
Custom fields are also included in the response and use their system name prefixed with ‘custom_’ as their field identifier. Please see add_result for a full list of available custom field types.
Response codes
| 200 | Success, the test results are returned as part of the response |
| 400 | Invalid or unknown test |
| 403 | No access to the project |
get_results_for_case
Returns a list of test results for a test run and case combination.
The difference to get_results is that this method expects a test run + test case instead of a test. In TestRail, tests are part of a test run and the test cases are part of the related test suite. So, when you create a new test run, TestRail creates a test for each test case found in the test suite of the run. You can therefore think of a test as an “instance” of a test case which can have test results, comments and a test status. Please also see TestRail’s getting started guide for more details about the differences between test cases and tests.
GET index.php?/api/v2/get_results_for_case/:run_id/:case_id
| :run_id | The ID of the test run |
| :case_id | The ID of the test case |
This method uses the same response format as get_results.
This method will return up to 250 entries in the response array. To retrieve additional entries, you can make additional requests using the offset filter described in the Request filters section below.
Request filters
The following filters can be applied:
| Name | Type | Description |
|---|---|---|
| :limit/:offset | int | Limit the result to :limit test results. Use :offset to skip records. |
| :status_id | int (list) | A comma-separated list of status IDs to filter by. |
# All results for test run with ID 1 and test case with ID 2
GET index.php?/api/v2/get_results_for_case/1/2
Response codes
| 200 | Success, the test results are returned as part of the response |
| 400 | Invalid or unknown test run or case |
| 403 | No access to the project |
get_results_for_run
Returns a list of test results for a test run.
GET index.php?/api/v2/get_results_for_run/:run_id
| :run_id | The ID of the test run |
This method uses the same response format as get_results.
This method will return up to 250 entries in the response array. To retrieve additional entries, you can make additional requests using the offset filter described in the Request filters section below.
Request filters
The following filters can be applied:
| Name | Type | Description |
|---|---|---|
| :created_after | timestamp | Only return test results created after this date (as UNIX timestamp). |
| :created_before | timestamp | Only return test results created before this date (as UNIX timestamp). |
| :created_by | int (list) | A comma-separated list of creators (user IDs) to filter by. |
| :limit/:offset | int | Limit the result to :limit test results. Use :offset to skip records. |
| :status_id | int (list) | A comma-separated list of status IDs to filter by. |
# The latest 10 results for test run with ID 1 created by user 5
GET index.php?/api/v2/get_results_for_run/1&created_by=5&limit=10
Response codes
| 200 | Success, the test results are returned as part of the response |
| 400 | Invalid or unknown test run |
| 403 | No access to the project |
add_result
Adds a new test result, comment or assigns a test. It’s recommended to use add_results instead if you plan to add results for multiple tests.
POST index.php?/api/v2/add_result/:test_id
| :test_id | The ID of the test the result should be added to |
Request fields
The following POST fields are supported (system fields):
| Name | Type | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| status_id | int |
The ID of the test status. The built-in system statuses have the following IDs:
You can get a full list of system and custom statuses via get_statuses. |
||||||||||
| comment | string | The comment / description for the test result | ||||||||||
| version | string | The version or build you tested against | ||||||||||
| elapsed | timespan | The time it took to execute the test, e.g. “30s” or “1m 45s” | ||||||||||
| defects | string | A comma-separated list of defects to link to the test result | ||||||||||
| assignedto_id | int | The ID of a user the test should be assigned to |
Custom fields are supported as well and must be submitted with their system name, prefixed with ‘custom_’, e.g.:
{
..
"custom_comment": "This is a custom comment"
..
}
The following custom field types are supported:
| Name | Type | Description |
|---|---|---|
| Checkbox | bool | True for checked and false otherwise |
| Date | string | A date in the same format as configured for TestRail and API user (e.g. “07/08/2013”) |
| Dropdown | int | The ID of a dropdown value as configured in the field configuration |
| Integer | int | A valid integer |
| Milestone | int | The ID of a milestone for the custom field |
| Multi-select | array | An array of IDs as configured in the field configuration |
| Step Results | array | An array of objects specifying the step results. Also see the example below. |
| String | string | A valid string with a maximum length of 250 characters |
| Text | string | A string without a maximum length |
| URL | string | A string with matches the syntax of a URL |
| User | int | The ID of a user for the custom field |
Request example
Also see the following example which shows how to submit step results with the structured steps custom field:
{
"status_id": 5,
"comment": "This test failed",
"elapsed": "15s",
"defects": "TR-7",
"version": "1.0 RC1 build 3724",
..
"custom_step_results": [
{
"content": "Step 1",
"expected": "Expected Result 1",
"actual": "Actual Result 1",
"status_id": 1
},
{
"content": "Step 2",
"expected": "Expected Result 2",
"actual": "Actual Result 2",
"status_id": 2
},
..
]
..
}
Response content
If successful, this method returns the new test result using the same response format as get_results, but with a single result instead of a list of results.
Response codes
| 200 | Success, the test result was created and is returned as part of the response |
| 400 | Invalid or unknown test |
| 403 | No permissions to add test results or no access to the project |
add_result_for_case
Adds a new test result, comment or assigns a test (for a test run and case combination). It’s recommended to use add_results_for_cases instead if you plan to add results for multiple test cases.
The difference to add_result is that this method expects a test run + test case instead of a test. In TestRail, tests are part of a test run and the test cases are part of the related test suite. So, when you create a new test run, TestRail creates a test for each test case found in the test suite of the run. You can therefore think of a test as an “instance” of a test case which can have test results, comments and a test status. Please also see TestRail’s getting started guide for more details about the differences between test cases and tests.
POST index.php?/api/v2/add_result_for_case/:run_id/:case_id
| :run_id | The ID of the test run |
| :case_id | The ID of the test case |
This method supports the same POST fields as add_result.
Response content
If successful, this method returns the new test result using the same response format as get_results, but with a single result instead of a list of results.
Response codes
| 200 | Success, the test result was created and is returned as part of the response |
| 400 | Invalid or unknown test run or case |
| 403 | No permissions to add test results or no access to the project |
add_results
Adds one or more new test results, comments or assigns one or more tests. Ideal for test automation to bulk-add multiple test results in one step.
POST index.php?/api/v2/add_results/:run_id
| :run_id | The ID of the test run the results should be added to |
This method expects an array of test results (via the ‘results’ field, please see below). Each test result must specify the test ID and can pass in the same fields as add_result, namely all test related system and custom fields.
Please note that all referenced tests must belong to the same test run.
Request example
The following listing shows a typical example request. In addition to the test, you need to specify at least one of the status, comment or assignee fields for each result.
{
"results": [
{
"test_id": 101,
"status_id": 5,
"comment": "This test failed",
"defects": "TR-7"
},
{
"test_id": 102,
"status_id": 1,
"comment": "This test passed",
"elapsed": "5m",
"version": "1.0 RC1"
},
..
{
"test_id": 101,
"assignedto_id": 5,
"comment": "Assigned this test to Joe"
}
..
]
}
Response content
If successful, this method returns the new test results using the same response format as get_results and in the same order as the list of the request.
Response codes
| 200 | Success, the test results were created and are returned as part of the response |
| 400 | Invalid or unknown test run/tests |
| 403 | No permissions to add test results or no access to the project |
add_results_for_cases
Adds one or more new test results, comments or assigns one or more tests (using the case IDs). Ideal for test automation to bulk-add multiple test results in one step.
POST index.php?/api/v2/add_results_for_cases/:run_id
| :run_id | The ID of the test run the results should be added to |
This method expects an array of test results (via the ‘results’ field, please see below). Each test result must specify the test case ID and can pass in the same fields as add_result, namely all test related system and custom fields.
The difference to add_results is that this method expects test case IDs instead of test IDs. Please see add_result_for_case for details.
Please note that all referenced tests must belong to the same test run.
Request example
The following listing shows a typical example request. In addition to the test case, you need to specify at least one of the status, comment or assignee fields for each result.
{
"results": [
{
"case_id": 1,
"status_id": 5,
"comment": "This test failed",
"defects": "TR-7"
},
{
"case_id": 2,
"status_id": 1,
"comment": "This test passed",
"elapsed": "5m",
"version": "1.0 RC1"
},
..
{
"case_id": 1,
"assignedto_id": 5,
"comment": "Assigned this test to Joe"
}
..
]
}
Response content
If successful, this method returns the new test results using the same response format as get_results and in the same order as the list of the request.
Response codes
| 200 | Success, the test results were created and are returned as part of the response |
| 400 | Invalid or unknown test run/cases |
| 403 | No permissions to add test results or no access to the project |