Use the following API methods to request details about shared steps.
Shared Test Steps and related endpoints are only available in TestRail 7.0 or later.
get_shared_step
Returns an existing set of shared steps.
GET index.php?/api/v2/get_shared_step/{shared_step_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| shared_step_id | integer | true | The ID of the set of shared steps |
Response content
Example response:
{
"id": 1,
"title": "Default Login",
"project_id": 2,
"created_by": 1,
"created_on": 1612555977,
"updated_by": 1,
"updated_on": 1612555977,
"custom_steps_separated": [
{
"content": "Navigate to https:\\/\\/localhost\\/some_app",
"additional_info": null,
"expected": "Login screen loads",
"refs": "TR-123"
},
{
"content": "Enter Valid Credentials",
"additional_info": null,
"expected": "Logged in and redirected to dashboard",
"refs": null
}
],
"case_ids": [
25
]
}The following fields are included in the response:
| Name | Type | Description |
|---|---|---|
| case_ids | array | An array of integers. The array contains all test cases which use the set of shared steps |
| created_by | integer | The ID of the user who created the set of steps |
| created_on | timestamp | The date/time when the steps were created (as UNIX timestamp) |
| custom_steps_separated | array | An array of objects. Each object contains the details for an individual step |
| id | integer | The ID of the set of shared steps |
| project_id | integer | The ID of the project in which the steps reside |
| title | string | The title given to the set of steps |
| updated_by | integer | The ID of the user who last updated the set of steps |
| updated_on | timestamp | The date/time when the set of steps was last updates (as UNIX timestamp) |
custom_steps_separated fields
| Name | Type | Description |
|---|---|---|
| additional_info | text | The text contents of the “Additional Info” field |
| content | text | The text contents of the “Step” field |
| expected | text | The text contents of the “Expected Result” field |
| refs | string | Reference information for the “References” field |
The custom_steps_separated field name is the default system name for the separated steps field. This name may be different if the field has ever been removed from the instance and recreated with a different system name.
Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the shared step is returned as part of the response) |
| 400 | Invalid or unknown shared step |
| 403 | Insufficient permissions |
| 429 | TestRail Cloud only—Too many requests (see API rate limit) |
get_shared_step_history
This endpoint requires TestRail 7.3 or later.
Returns an existing set of shared steps.
GET index.php?/api/v2/get_shared_step_history/{shared_step_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| shared_step_id | integer | true | The ID of the set of shared steps |
Response content
The returned response includes the change history of the steps in the following format:
{
"offset": 0,
"limit": 250,
"size": 2,
"_links": {
"next": null,
"prev": null
},
"step_history": [
{
"id": "1",
"timestamp": 1389968184,
"user_id": "4",
"custom_steps_separated": [
{
"content": "Step 1",
"additional_info": "Step 1 Additional Information",
"expected": "Expected Result 1",
"refs": "ABC-1, ABC-2"
}
],
"title": "Shared Steps 1"
}
]
}The following fields are included in the response:
| Name | Type | Description |
|---|---|---|
| offset | integer | Where to start counting the step history from |
| limit | integer | The maximum number of records to return |
| size | integer | The number of records returned |
| links | object | An object containing URIs to the next and previous sets of values, if available |
| step_history | object | An array of changes to the shared steps |
| title | string | The tittle of the shared step |
step_history fields
| Name | Type | Description |
|---|---|---|
| id | integer | ID of the change record |
| user_id | integer | ID of the user who made the change |
| timestamp | integer | Unix timestamp indicating when the change ocurred |
| custom_steps_separated | object | An object containing each of the available fields and values for test step record, consistent with get_shared_step |
The custom_steps_separated field name is the default system name for the separated steps field. This name may be different if the field has ever been removed from the instance and recreated with a different system name.
Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the shared step history is returned as part of the response) |
| 400 | Invalid or unknown shared step |
| 403 | Insufficient permissions |
| 429 | TestRail Cloud only—Too many requests (see API rate limit) |
get_shared_steps
Returns a list of shared steps for a project.
GET index.php?/api/v2/get_shared_steps/{project_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| project_id | integer | true | The ID of the project |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
| created_after | timestamp | false | Only return shared steps created after this date (as UNIX timestamp) |
| created_before | timestamp | false | Only return shared steps created before this date (as UNIX timestamp) |
| created_by | integer(list) | false | A comma-separated list of creators (user IDs) to filter by |
| limit/offset | integer | false | Limit the result to :limit test runs. Use :offset to skip records |
| updated_after | timestamp | false | Only return shared steps updated after this date (as UNIX timestamp) |
| updated_before | timestamp | false | Only return shared steps updated before this date (as UNIX timestamp) |
| refs | string | false | A single Reference ID (e.g. TR-a, 4291, etc.) |
This method will return up to 250 entries in the response array. To retrieve additional entries, you can make additional requests using the offset filter described in the above table.
# All shared steps for project with ID 1 created by user with ID 1 or 2
GET index.php?/api/v2/get_shared_steps/1&created_by=1,2Response content
The response includes an array of shared test steps. Each entry in the array follows the same format as get_shared_step.
{
"offset": 0,
"limit": 250,
"size": 250,
"_links": {
"next": "/api/v2/get_shared_steps/1&limit=250&offset=250",
"prev": null
},
"shared_steps": [
{
"id": 1,
"title": "Shared Step 1",
},
{
"id": 2,
"title": "Shared Step 2",
}
]
}Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the shared steps are returned as part of the response) |
| 400 | Invalid or unknown set of shared steps |
| 403 | Insufficient permissions |
| 429 | TestRail Cloud only—Too many requests (see API rate limit) |
add_shared_step
Creates a new set of shared steps. Requires permission to add test cases within the project.
POST index.php?/api/v2/add_shared_step/{project_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| project_id | integer | true | The ID of the project |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
| custom_steps_separated | array | false | An array of objects. Each object contains the details for an individual step. See the table below for more details |
| title | string | true | The title for the set of steps |
| created_by | integer(list) | false | A comma-separated list of creators (user IDs) to filter by |
| limit/offset | integer | false | Limit the result to :limit test runs. Use :offset to skip records |
| updated_after | timestamp | false | Only return shared steps updated after this date (as UNIX timestamp) |
| updated_before | timestamp | false | Only return shared steps updated before this date (as UNIX timestamp) |
| refs | string | false | A single Reference ID (e.g. TR-a, 4291, etc.) |
custom_steps_separated fields
Each JSON object inside the array should contain at least one of the following fields.
| Name | Type | Description |
|---|---|---|
| additional_info | text | The text contents of the “Additional Info” field |
| content | text | The text contents of the “Step” field |
| expected | text | The text contents of the “Expected Result” field |
| refs | string | Reference information for the “References” field |
The custom_steps_separated field name is the default system name for the separated steps field. This name may be different if the field has ever been removed from the instance and recreated with a different system name.
Request example
Also, see the following example which shows how to create a new set of shared steps.
{
"title": "First Step",
"custom_steps_separated": [
{
"content": "Open home page",
"additional_info": "Must be a new browser session",
"expected": "Login page loads",
"refs": "RF-1"
},
{
"content": "Log In",
}
]
}Response content
If successful, this method returns the new shared steps using the same response format as get_shared_step.
The following system fields are included in the response:
| Name | Type | Description |
|---|---|---|
| case_ids | array | An array of integers. The array contains all test cases which use the set of shared steps |
| created_by | integer | The ID of the user who created the set of steps |
| created_on | timestamp | The date/time when the steps were created (as UNIX timestamp) |
| custom_steps_separated | array | An array of objects. Each object contains the details for an individual step |
| id | integer | The ID of the set of shared steps |
| project_id | integer | The ID of the project in which the steps reside |
| title | string | The title given to the set of steps |
| updated_by | integer | The ID of the user who last updated the set of steps |
| updated_on | timestamp | The date/time when the set of steps was last updated (as UNIX timestamp) |
Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the set of shared steps was created and is returned as part of the response) |
| 400 | Invalid or unknown set of shared steps |
| 403 | Insufficient permissions |
| 429 | TestRail Cloud only—Too many requests (see API rate limit) |
update_shared_step
Updates an existing set of shared steps (partial updates are supported, i.e. you can submit and update specific fields only). Requires permission to edit test cases within the project.
POST index.php?/api/v2/update_shared_step/{shared_update_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| shared_update_id | integer | true | The ID of the set of shared steps |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
| custom_steps_separated | array | false | An array of objects. Each object contains the details for an individual step. See the table below for more details |
| title | string | true | The title for the set of steps |
| created_by | integer(list) | false | A comma-separated list of creators (user IDs) to filter by |
| limit/offset | integer | false | Limit the result to :limit test runs. Use :offset to skip records |
| updated_after | timestamp | false | Only return shared steps updated after this date (as UNIX timestamp) |
| updated_before | timestamp | false | Only return shared steps updated before this date (as UNIX timestamp) |
| refs | string | false | A single Reference ID (e.g. TR-a, 4291, etc.) |
This method supports the same fields as add_shared_step. When submitting the custom_steps_separated field, ALL existing steps will be replaced.
Response content
If successful, this method returns the updated shared steps using the same response format as get_shared_step.
{
"id": 1,
"title": "Default Login",
"project_id": 2,
"created_by": 1,
"created_on": 1612555977,
"updated_by": 1,
"updated_on": 1612555977,
"custom_steps_separated": [
{
"content": "Navigate to https:\\/\\/localhost\\/some_app",
"additional_info": null,
"expected": "Login screen loads",
"refs": "TR-123"
},
{
"content": "Enter Valid Credentials",
"additional_info": null,
"expected": "Logged in and redirected to dashboard",
"refs": null
}
],
"case_ids": [
25
]
}Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the set of shared steps was updated and is returned as part of the response) |
| 400 | Invalid or unknown test |
| 403 | Insufficient permissions |
| 429 | TestRail Cloud only—Too many requests (see API rate limit) |
delete_shared_step
Deleting shared test steps cannot be undone. By default, deleting a shared step set will keep the steps in all test cases which used the set. Use the keep_in_cases parameter to also remove the steps from test cases.
Deletes an existing shared step entity. Requires permission to delete test cases within the project.
POST index.php?/api/v2/delete_shared_step/{shared_update_id}
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| shared_update_id | integer | true | The ID of the set of shared steps |
| keep_in_cases | boolean | true | Default is 1 (true). Submit keep_in_cases=0 to delete the shared steps from all test cases as well as the shared step repository |
Request body
{
"keep_in_cases":0
}Response content
If successful, this method returns a 200 status code and no other data.
Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the shared step set was deleted) |
| 400 | Invalid or unknown shared step ID |
| 403 | Insufficient permissions |
| 429 | TestRail Cloud only—Too many requests (see API rate limit) |