API: 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
| :suite_id | 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 | int | The unique ID of the test suite |
| is_baseline | bool | True if the test suite is a baseline test suite and false otherwise (added with TestRail 4.0) |
| is_completed | bool | True if the test suite is marked as completed/archived and false otherwise (added with TestRail 4.0) |
| is_master | bool | 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 | int | 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
| 200 | Success, the test suite is returned as part of the response |
| 400 | Invalid or unknown test suite |
| 403 | No access to the project |
get_suites
Returns a list of test suites for a project.
GET index.php?/api/v2/get_suites/:project_id
| :project_id | The ID of the project |
Response content
The response includes an array of test suite. 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
| 200 | Success, the test suites are returned as part of the response |
| 400 | Invalid or unknown project |
| 403 | No access to the project |
add_suite
Creates a new test suite.
POST index.php?/api/v2/add_suite/:project_id
| :project_id | The ID of the project the test suite should be added to |
Request fields
The following POST fields are supported:
| Name | Type | Description |
|---|---|---|
| name | string | The name of the test suite (required) |
| description | string | 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
| 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 |
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
| :suite_id | The ID of the test suite |
This methods 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
| 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 |
delete_suite
Deletes an existing test suite.
POST index.php?/api/v2/delete_suite/:suite_id
| :suite_id | The ID of the test suite |
Soft Parameter
If soft=1, this will return data on the number of affected tests, cases, etc.
Including soft=1 will not actually delete the entity.
Note: Omitting the soft parameter, or submitting soft=0 will delete the test suite and its test cases
info Please Note: 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.
Response codes
| 200 | Success, the test suite and all active test runs & results were deleted |
| 400 | Invalid or unknown test suite |
| 403 | No permissions to delete test suites or no access to the project |