Suites

Use the following API methods to request details about test suites and to create or modify test suites.

get_suite

Returns an existing test suite.

GET index.php?/api/v2/get_suite/{suite_id}

Parameters

Name Type Required Description
suite_id integer true The ID of the test suite

Response content

Please see below for a typical example response:

{
    "description": "..",
    "id": 1,
    "name": "Setup & Installation",
    "project_id": 1,
    "url": "http:///testrail/index.php?/suites/view/1"
}

The following fields are included in the response:

Name Type Description
completed_on timestamp The date/time when the test suite was closed (as UNIX timestamp) (added with TestRail 4.0)
description string The description of the test suite
id integer The unique ID of the test suite
is_baseline boolean True if the test suite is a baseline test suite and false otherwise (added with TestRail 4.0)
is_completed boolean True if the test suite is marked as completed/archived and false otherwise (added with TestRail 4.0)
is_master boolean True if the test suite is a master test suite and false otherwise (added with TestRail 4.0)
name string The name of the test suite
project_id integer The ID of the project this test suite belongs to
url string The address/URL of the test suite in the user interface

Response codes

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

get_suites

Returns a list of test suites for a project.

GET index.php?/api/v2/get_suites/{project_id}

Parameters

Name Type Required Description
project_id integer true The ID of the project

Response content

The response includes an array of test suites. Each test suite in this list follows the same format as get_suite.

[
    {
        "id": 1,
        "name": "Setup & Installation", 
    },
    {
        "id": 2,
        "name": "Document Editing", 
    },
]

Response codes

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

add_suite

Creates a new test suite.

POST index.php?/api/v2/add_suite/{project_id}

Parameters

Name Type Required Description
project_id integer true The ID of the project the test suite should be added to

Request body

The following fields are supported in the POST request body:

Name Type Required Description
name string true The name of the test suite
description string false The description of the test suite

Request example

Also see the following example which shows how to create a new, empty test suite:

{
    "name": "This is a new test suite",
    "description": "Use the description to add additional context details"
}

Once you’ve added a test suite, you can start adding sections and test cases.

Response content

If successful, this method returns the new test suite using the same response format as get_suite.

Response codes

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

update_suite

Updates an existing test suite (partial updates are supported, i.e. you can submit and update specific fields only).

POST index.php?/api/v2/update_suite/{suite_id}

Parameters

Name Type Required Description
suite_id integer true The ID of the test suite

This method supports the same POST fields as add_suite.

Response content

If successful, this method returns the updated test suite using the same response format as get_suite.

Response codes

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

delete_suite

 

Deleting a test suite cannot be undone and also deletes all active test runs & results, i.e. test runs & results that weren’t closed (archived) yet.

Deletes an existing test suite.

POST index.php?/api/v2/delete_suite/{suite_id}

Parameters

Name Type Required Description
suite_id integer true The ID of the test suite

Soft Parameter

 

Omitting the soft parameter, or submitting soft=0 will delete the test suite and its test cases

If soft=1, this will return data on the number of affected tests, cases, etc.

Including soft=1 will not actually delete the entity.

Response codes

Status Code Description
200 Success (the test suite and all active test runs and results were deleted)
400 Invalid or unknown test suite
403 No permissions to delete test suites or no access to the project
429 TestRail Cloud only—Too many requests (see API rate limit)
Was this article helpful?
3 out of 13 found this helpful