Test cases can be designed using a variety of tools and even auto-generated. If you have a tool that generates test cases, you may want to automatically create those test cases in TestRail so that testers can start making use of them and submitting results.
With the ability to create test cases programmatically, you should be able to create tools and integrations for use cases such:
- Create test cases based on automated tests
- Combinatorial test case generation tools
- Other model-based test case generation tools
| Real examples | Use case |
|---|---|
| TestRail CLI - JUnit Parser | Automatically creates tests when uploading test automation results |
| TestRail CLI - OpenAPI Parser | Generates test cases from OpenAPI specifications |
Notes about custom fields
To enrich your test cases, TestRail gives your the ability to customize your test case fields and templates. If you configured custom result fields, you can also submit values using the pattern custom_field_name, such as custom_automation_status in the example above.
You can also discover details about all case fields by executing one of the following requests:
| Case fields | GET index.php?/api/v2/get_case_fields |
| Case templates | GET index.php?/api/v2/get_templates/{project_id} |
| Case priorities | GET index.php?/api/v2/get_priorities |
| Case types | GET index.php?/api/v2/get_case_types |
| Case statuses | GET index.php?/api/v2/get_case_statuses |
Creating test cases with "Test Case (Text)" template
The text template is the TestRail default and it's the most basic, yet versatile, template. It contains a Preconditions field, a Steps field, and an Expected Result field. You can create tests using this field using a content body similar to the one in the example below.
POST index.php?/api/v2/add_case/{section_id}
curl -X POST \
-u "user@example.com:password" \
-d "@path/to/data.json" \
"https://example.testrail.io/index.php?/api/v2/add_case/432"{
"title": "My test case (text)",
"template_id": 1,
"type_id": 1,
"priority_id": 1,
"estimate": "3m",
"refs": "TR-1, TR-2",
"custom_preconds": "My preconditions",
"custom_steps": "My test steps",
"custom_expected": "My expected final results"
}{
"id": 4076,
"title": "My test case (text)",
"section_id": 498,
"template_id": 1,
"type_id": 1,
"priority_id": 1,
"milestone_id": null,
"refs": "TR-1, TR-2",
"created_by": 18,
"created_on": 1684927460,
"updated_by": 18,
"updated_on": 1684927460,
"estimate": "3m",
"estimate_forecast": null,
"suite_id": 53,
"display_order": 1,
"is_deleted": 0,
"case_assignedto_id": null,
"custom_automation_type": null,
"custom_preconds": "My preconditions",
"custom_steps": "My test steps",
"custom_testrail_bdd_scenario": null,
"custom_expected": "My expected final results",
"custom_steps_separated": null,
"custom_mission": null,
"custom_goals": null,
"comments": []
}Creating test cases with "Test Case (Steps)" template
If you want to have a more granular control over the results of your test cases, you may want to design them using individual test steps, so you can identify which exact step failed during the execution. You can create a test case with separated test steps using a format similar to what you see in the content body below.
POST index.php?/api/v2/add_case/{section_id}
curl -X POST \
-u "user@example.com:password" \
-d "@path/to/data.json" \
"https://example.testrail.io/index.php?/api/v2/add_case/432"{
"title": "My test case (steps)",
"template_id": 2,
"type_id": 1,
"priority_id": 1,
"estimate": "3m",
"refs": "TR-1, TR-2",
"custom_preconds": "My preconditions",
"custom_steps_separated": [
{
"content": "Step 1",
"expected": "Expected Result 1"
},
{
"content": "Step 2",
"expected": "Expected Result 2"
},
{
"shared_step_id": 3
},
]
}{
"id": 4078,
"title": "My test case (steps)",
"section_id": 498,
"template_id": 2,
"type_id": 1,
"priority_id": 1,
"milestone_id": null,
"refs": "TR-1, TR-2",
"created_by": 18,
"created_on": 1684931159,
"updated_by": 18,
"updated_on": 1684931159,
"estimate": "3m",
"estimate_forecast": null,
"suite_id": 53,
"display_order": 2,
"is_deleted": 0,
"case_assignedto_id": null,
"custom_automation_type": null,
"custom_preconds": "My preconditions",
"custom_steps": null,
"custom_testrail_bdd_scenario": null,
"custom_expected": null,
"custom_steps_separated": [
{
"content": "Step 1",
"expected": "Expected Result 1",
"additional_info": "",
"refs": ""
},
{
"content": "Step 2",
"expected": "Expected Result 2",
"additional_info": "",
"refs": ""
},
{
"shared_step_id": 3,
"content": "Shared step action",
"expected": "Shared step expected result"
}
],
"custom_mission": null,
"custom_goals": null,
"comments": []
}Creating test cases with "Exploratory Session" template
Exploratory testing is a very relevant testing technique if you want to make sure your system is in tip-top shape by interacting with it in a less constrained manner, and it also helps you learn about the system. If you are doing this kind of testing and want to save your exploratory test charters to TestRail for future reference, you can do so using a content body similar to the one below.
POST index.php?/api/v2/add_case/{section_id}
curl -X POST \
-u "user@example.com:password" \
-d "@path/to/data.json" \
"https://example.testrail.io/index.php?/api/v2/add_case/432"{
"title": "My test case (exploratory)",
"template_id": 3,
"type_id": 1,
"priority_id": 1,
"estimate": "3m",
"refs": "TR-1, TR-2",
"custom_preconds": "My preconditions",
"custom_mission": "My exploratory test session mission",
"custom_goals": "Goals for my exploratory test session"
}{
"id": 4079,
"title": "My test case (exploratory)",
"section_id": 498,
"template_id": 3,
"type_id": 1,
"priority_id": 1,
"milestone_id": null,
"refs": "TR-1, TR-2",
"created_by": 18,
"created_on": 1684931263,
"updated_by": 18,
"updated_on": 1684931263,
"estimate": "3m",
"estimate_forecast": null,
"suite_id": 53,
"display_order": 3,
"is_deleted": 0,
"case_assignedto_id": null,
"custom_automation_type": null,
"custom_preconds": null,
"custom_steps": null,
"custom_testrail_bdd_scenario": null,
"custom_expected": null,
"custom_steps_separated": null,
"custom_mission": "My exploratory test session mission",
"custom_goals": "Goals for my exploratory test session",
"comments": []
}Importing attachments
Attachments can enrich your test case design, either by making the steps more visual using screenshots of application areas or even by uploading test diagrams and mindmaps so you won't miss anything during execution. You can attach files to your test cases using a request as per below.
Note that the maximum allowed upload size is set to 256MB.
POST index.php?/api/v2/add_attachment_to_case/{case_id}Content-Type: multipart/form-data
curl -X POST \
-u "user@example.com:password" \
-H "Content-Type: multipart/form-data" \
-F "attachment=@path/to/image.jpg" \
"https://example.testrail.io/index.php?/api/v2/add_attachment_to_case/42"
{ "attachment_id": "758c9b26-6038-4147-9a4d-74cd7af1499a" }In case you want to append your attachment to any text field in your test case, you need to update the text and add a link, as per the example below.
POST index.php?/api/v2/update_case/{case_id}
curl -X POST \
-u "user@example.com:password" \
-d "@path/to/data.json" \
"https://example.testrail.io/index.php?/api/v2/update_case/4079"{
"custom_goals": "Goals for my exploratory test session\r\n "
}{
"id": 4079,
"title": "My test case (exploratory)",
"section_id": 498,
"template_id": 3,
"type_id": 1,
"priority_id": 1,
"milestone_id": null,
"refs": "TR-1, TR-2",
"created_by": 18,
"created_on": 1684931263,
"updated_by": 18,
"updated_on": 1684931263,
"estimate": "3m",
"estimate_forecast": null,
"suite_id": 53,
"display_order": 3,
"is_deleted": 0,
"case_assignedto_id": null,
"custom_automation_type": null,
"custom_preconds": null,
"custom_steps": null,
"custom_testrail_bdd_scenario": null,
"custom_expected": null,
"custom_steps_separated": null,
"custom_mission": "My exploratory test session mission",
"custom_goals": "Goals for my exploratory test session \r\n ",
"comments": []
}