Tests

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

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 (list) 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)
Was this article helpful?
2 out of 4 found this helpful