API: Results - TestRail

API: Results

Use the following API methods to request details about test results and to add new test results.

On this page:

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

    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

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

    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)