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}

Parameters

Name Type Required Description
test_id integer true The ID of the test
limit integer false The number that sets the limit of test results to be shown on the response (The response size limit is 250 by default) – requires TestRail 6.7 or later
offset integer false The number that sets the position where the response should start from – requires TestRail 6.7 or later

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
defects_filter string A single Defect ID (e.g. TR-1, 4291, etc.)
limit/offset integer Limit the result to :limit test results. Use :offset to skip records
status_id integer (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:

{
    "offset": 0,
    "limit": 250,
    "size": 250,
    "_links": {
       "next": "/api/v2/get_results/131071&limit=250&offset=250",
       "prev": null
    },
    "results": [
        {
            "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 integer The ID of the assignee (user) of the test result
comment string The comment or error message of the test result
created_by integer 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 integer The unique ID of the test result
status_id integer The status of the test result, e.g. passed or failed, also see get_statuses
test_id integer The ID of the test this test result belongs to
version string The (build) version of the test was executed against

The depthdisplay_order and parent fields determine the hierarchy of the sections in a test suite. The depth field is 0 for all sections on the root level and greater than 0 for all child sections. The depth field, therefore, resembles the level in the section hierarchy. Also, see get_sections for an example.

Response codes

Status Code Description
200 Success (the test results are returned as part of the response)
400 Invalid or unknown test
403 No access to the project
429 TestRail Cloud only—Too many requests (see API rate limit)

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 that 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}

Parameters

Name Type Required Description
run_id integer true The ID of the test run
case_id integer true The ID of the test case

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
defects_filter string A single Defect ID (e.g. TR-1, 4291, etc.)
limit integer The number of test results the response should return (The response size is 250 by default) – requires TestRail 6.7 or later
offset integer Where to start counting the results of the test from (the offset) – requires TestRail 6.7 or later
status_id integer (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 Content 

This method uses the same response format as get_results.

{
    "offset": 0,
    "limit": 250,
    "size": 250,
    "_links": {
       "next": "/api/v2/get_results/131071&limit=250&offset=250",
       "prev": null
    },
    "results": [
        {
            "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"
        }
    ]
}

Response codes

Status Code Description
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
429 TestRail Cloud only—Too many requests (see API rate limit)

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}

Parameters

Name Type Required Description
run_id integer true The ID of the test run

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 integer (list) A comma-separated list of creators (user IDs) to filter by
defects_filter string A single Defect ID (e.g. TR-1, 4291, etc.)
limit integer Number that sets the limit of results to be shown on the response (Optional parameter. The response size limit is 250 by default) – requires TestRail 6.7 or later
offset integer Number that sets the position where the response should start from (Optional parameter) – requires TestRail 6.7 or later
status_id integer (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 Content 

This method uses the same response format as get_results.

Response codes

Status Code Description
200 Success (the test results are returned as part of the response)
400 Invalid or unknown test run
403 No access to the project
429 TestRail Cloud only—Too many requests (see API rate limit)

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}

Parameters

Name Type Required Description
test_id integer true 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 integer

The ID of the test status. The default system statuses have the following IDs:

  • 1: Passed
  • 2: Blocked
  • 3: Untested (not allowed when adding a new result)
  • 4: Retest
  • 5: Failed

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 integer 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 boolean True for checked and false otherwise
Date string A date in the same format as configured for TestRail and API users (e.g. “07/08/2013”)
Dropdown integer The ID of a dropdown value as configured in the field configuration
Integer integer A valid integer
Milestone integer 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 integer 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

Status Code Description
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
429 TestRail Cloud only—Too many requests (see API rate limit)

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}

Parameters

Name Type Required Description
run_id integer true The ID of the test run
case_id integer true 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

Status Code Description
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
429 TestRail Cloud only—Too many requests (see API rate limit)

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}

Parameters

Name Type Required Description
run_id integer true 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

Status Code Description
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
429 TestRail Cloud only—Too many requests (see API rate limit)

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}

Parameters

Name Type Required Description
run_id integer true 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

Status Code Description
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
429 TestRail Cloud only—Too many requests (see API rate limit)
Was this article helpful?
0 out of 0 found this helpful