API: Shared Steps - TestRail

API: Shared Steps

Use the following API methods to request details about shared steps.

On this page:

    get_shared_step

    Returns an existing set of shared steps.

    GET index.php?/api/v2/get_shared_step/:shared_step_id
    
    :shared_step_id The ID of the set of shared steps.

    Response content

    Please see below for a typical 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 int 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 int The ID of the set of shared steps.
    project_id int The ID of the project in which the steps reside.
    title string The title given to the set of steps.
    updated_by int 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

    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.

     

    Please Note: 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

    200 Success, the shared step is returned as part of the response
    400 Invalid or unknown shared step
    403 Insufficient permissions

     

    get_shared_steps

    Returns a list of shared steps for a project.

    GET index.php?/api/v2/get_shared_steps/:project_id
    
    :project_id The ID of the project.

     

    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 Request filters section below.

    Request filters

    The following filters can be applied:

    Name Type Description
    :created_after timestamp Only return shared steps created after this date (as UNIX timestamp).
    :created_before timestamp Only return shared steps created before this date (as UNIX timestamp).
    :created_by int (list) A comma-separated list of creators (user IDs) to filter by.
    :limit/:offset int Limit the result to :limit test runs. Use :offset to skip records.
    :updated_after timestamp Only return shared steps updated after this date (as UNIX timestamp).
    :updated_before timestamp Only return shared steps updated before this date (as UNIX timestamp).
    :refs string A single Reference ID (e.g. TR-a, 4291, etc.)
    # 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,2

    Response content

    The response includes an array of shared test steps. Each entry in the array follows the same format as get_shared_step.

    [
    	{"id": 1, "title": "Shared Step 1", ...},
    	{"id": 2, "title": "Shared Step 2", ...},
    	..
    ]
    

    info Please Note: As of February 26, 2021 the data structure returned by bulk GET API endpoints will change. These bulk endpoints will no longer return an array of all entities, but will instead return an object with additional pagination fields and an array of up to 250 entities.To see the new response structure and test any necessary code changes, include the following header and value in your API requests: x-api-ident: beta.

    New Response 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

    200 Success, the shared steps are returned as part of the response
    400 Invalid or unknown shared steps
    403 Insufficient permissions

     

    add_shared_step

    Creates a new set of shared steps. Requires permission to add test cases withing the project.

    POST index.php?/api/v2/add_shared_step/:project_id
    
    :project_id The ID of the project.

     

    Request fields

    The following POST fields are supported:

    Name Type Description
    custom_steps_separated array An array of objects. Each object contains the details for an individual step. See the table below for more details.
    title string The title for the set of steps. (Required)

    custom_steps_separated fields

    Each JSON object inside the array should contain at least one of the following fields.

    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.

    Please Note: 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.

    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 int 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 int The ID of the set of shared steps.
    project_id int The ID of the project in which the steps reside.
    title string The title given to the set of steps.
    updated_by int 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).

     

    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.

    Response codes

    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

     

    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
    
    :shared_update_id The ID of the set of shared steps.

    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.

    Response codes

    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

     

    delete_shared_step

    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
    {
    keep_in_cases:0
    }
    :shared_update_id The ID of the set of shared steps.
    :keep_in_cases 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.

     

    Response content

    If successful, this method returns a 200 status code and no other data.

    info Please Note: 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.

    Response codes

    200 Success, the shared step set was deleted
    400 Invalid or unknown shared step ID
    403 Insufficient permissions