API: Shared Steps - TestRail

API: Shared Steps

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

Please Note: Shared Test Steps and related endpoints are only available in TestRail 7.0 or later.

On this page:

    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.

     

    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

    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_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
    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,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.

    {"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 withing 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
    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 false The title for the set of steps. (Required)
    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.

    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:

    Key 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

    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

    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

    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

    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
       }

    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

    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

    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)