API: Tests - TestRail

API: Tests

Use the following API methods to request details about tests (individual instances of test cases added to specific test runs or test plans).

On this page:

    get_test

     Returns an existing test.

    GET index.php?/api/v2/get_test/{test_id}

    Parameters

    Name Type Required Description
    test_id
    integer true The ID of the test

    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 using query parameters in the request URL:

    Name Type Description
    with_data
    string The parameter to get data

     

    Response content

    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
    integer The ID of the user the test is assigned to
    case_id
    integer 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 estimated forecast of the related test case, e.g. “30s” or “1m 45s”
    id
    integer The unique ID of the test
    milestone_id
    integer The ID of the milestone that is linked to the test case
    priority_id
    integer 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
    integer The ID of the test run the test belongs to
    status_id
    integer The ID of the current status of the test, also see get_statuses
    title
    string The title of the related test case
    type_id
    integer 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

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

     

    get_tests

    Returns a list of tests for a test run

    GET index.php?/api/v2/get_tests/{run_id}

    Parameters

    Name Type Required Description
    run_id
    integer true 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 using query parameters in the request URL:

    Name Type Description
    status_id
    integer (list) A comma-separated list of status IDs to filter by
    limit
    integer The 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
    integer The 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&offset=1&limit=30&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.

    {
      "offset": 0,
      "limit": 250,
      "size": 236,
      "_links": {
        "next": null,
        "prev": null,
    },
    "tests": [
    	{
    		"id": 1, 
    		"title": "Test conditional formatting with basic value range", 
    		.. 
    	},
    	{ 
    		"id": 2,
    		"title": "Verify line spacing on multi-page document",
    		..
    	},
    	..
    ]
    }
    

    Response codes

    Status Code Description
    200 Success (the tests 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)