Test Steps Resources

Modify the steps for a given test.


Adding Test Steps

Add steps to a test by POSTing a type-specific payload to the Test Steps resource. There are several types of test steps available:

Request

POST/buckets/<bucket_key>/tests/<test_id>/steps

POST Body

The POST body must be a JSON object matching for a specific step type (see below).

Response

Returns a full list of the test's steps, with the newest test step at the end of the list.

Request Step

POST Body

The POST body must be a JSON object. The following parameters can be set on the request step, and these are formatted the same as the test detail response output.

Data Attributes
step_type Always set to request.
url The URL to make a request to for this step. This may contain both query string parameters and variables.
method The HTTP method for this request step.
note A description or note for this request step.
auth An object with either basic or oauth1 credentials for authenticating this request.
headers An object with keys as header names matched to their values. Values can either be a single string or an array of strings.
form An object with keys as form post parameter names matched to their values. Values can either be a single string or an array of strings.
body A string to use as the body of the request.
assertions A list of assertions to apply to the HTTP response from this request.
variables A list of variables to extract out of the HTTP response from this request.
Example Request Step
{ 
    "step_type": "request",
    "method": "POST",
    "url": "https://{{base_url}}/example/path",
    "body": "{ \"hello\": \"world\" }",
    "assertions": [
        {
            "source": "response_status", 
            "comparison": "equal_number", 
            "value": 200
        }
    ],
    "variables": [
        {
            "name": "source_ip",
            "property": "origin",
            "source": "response_json"
        }    
    ],
    "headers": {
      "Content-Type": [
        "application/json"
      ],
      "Accept": [
        "*/*"
      ]
    },
    "scripts": [
        {
            "value": "log(\"This is a sample script\");"
        }
    ],
    "note": "get example data"
}

Pause Step

POST Body

The POST body must be a JSON object. The following parameters can be set on the pause step, these are the same format as the test detail response output.

Data Attributes
id The unique ID for this test.
step_type Always set to pause.
duration This is the duration of the pause step in seconds. It must be an integer between 1 and 120.
Example Pause Step
{
    "step_type": "pause",
    "duration": 5
}

Condition Step

POST Body

The POST body must be a JSON object. The following parameters can be set on the condition step, these are the same format as the test detail response output.

Data Attributes
id The unique ID for this test.
step_type Always set to condition.
comparison An assertion comparison to determine whether or not to execute the embedded steps.
left_value The left hand value of the assertion.
right_value The right-hand side value of the assertion, if one is required.
steps An array of test steps to execute if the comparison evaluates successfully.
Example Condition Step

This example also includes a nested Request Step.

{
    "step_type": "condition",
    "left_value": "{{user_id}}",
    "comparison": "equal",
    "right_value": "12345",
    "steps": [
        {
            "assertions": [
                {
                    "comparison": "equal_number",
                    "source": "response_status",
                    "value": 200
                }
            ],
            "method": "GET",
            "step_type": "request",
            "url": "https://yourapihere.com/"
        }
    ]
}

Ghost Inspector Step

POST Body

The POST body must be a JSON object. The following parameters can be set on the Ghost Inspector step, these are the same format as the test detail response output.

Data Attributes
step_type Always set to ghost-inspector
integration_id The id of an account integration with Ghost Inspector as found in the team integrations list.
suite_id The Ghost Inspector suite id of the test to run. You can find this in the Ghost Inspector API.
test_id The Ghost Inspector test id of the test to run. You can find this in the Ghost Inspector API.
start_url A custom Start URL for the Ghost Inspector test to execute with.
assertions A list of assertions to apply to the incoming webhook result from Ghost Inspector.
variables A list of variables to extract out of the incoming webhook result from Ghost Inspector.
Example Ghost Inspector Step
{
    "step_type": "ghost-inspector",
    "integration_id": "c6f2aa66-ed7e-4faf-a05d-5da7416da3ee",
    "suite_id": "55c3b3b3fdac93101d808ca5",
    "test_id": "55c3b3dbfdac93101d808ca6",
    "is_custom_start_url": false,
    "start_url": "http://example.com",
    "assertions": [
        {
            "comparison": "equal",
            "property": "data.passing",
            "source": "response_json",
            "value": "true"
        }
    ],
    "variables": [
        {
            "name": "screenshot_url",
            "property": "data.screenshot.small.defaultUrl",
            "source": "response_json"
        }
    ]
}

Subtest Step

POST Body

The POST body must be a JSON object. The following parameters can be set on the subtest step, these are the same format as the test detail response output.

Data Attributes
test_uuid The embedded test's unique id.
step_type Always set to subtest.
environment_uuid The environment uuid to run with the subtest.
bucket_key The bucket key to which the subtest belongs.
assertions A list of assertions to apply to the incoming subtest result.
variables A list of variables to extract out of the incoming subtest result.
params A list of key value pairs to pass to the subtest at runtime. This is a way to pass variables extracted in the parent test to the subtest.
Example Subtest Step
{
    "step_type": "subtest",
    "test_uuid": "c6f2aa66-ed7e-4faf-a05d-5da7416da3ee",
    "environment_uuid": "d6f2aa66-ed7e-4faf-a05d-5da7416da3ef",
    "bucket_key": "fd1qy7w2l7ka",
    "assertions": [{
        "source": "response_status",
        "comparison": "equal_number",
        "value": 200,
        }],
    "variables": [{
        "name": "regionRunFrom",
        "property": "region",
        "source": "response_json",
        }    
    ],
    "params": [{
        "name": "foo",
        "value": "{{bar}}",
    }]
}

Defining Assertions

Assertions allow you to specify success criteria for a given request, Ghost Inspector, subtest, or condition step. Each assertion is defined by a source, property, comparison, and value.

Assertion Sources

response_status Assert on the value of the HTTP status code from the Response.
response_headers Assert on the value of a Response Header. You must include a Property with the header name to assert on.
response_json Parse the response body as JSON. You must include a Property with the JSON path to assert on.
response_xml Parse the response body as XML. You must include a Property with the XPath to assert on.
response_text Parse the response body as plain text. This source does not specify a Property.
response_time Assert on the execution time of the response in milliseconds.
response_size Assert on the size of the Response body in bytes.

Assertion Comparisons

equal A string equality check on the given property and value.
empty The given value is an empty string.
not_empty The given value is not an empty string.
not_equal The given string property is not equal to the given string value.
contains The given string value is found in the given property.
does_not_contain The given string value is not found in the given property.
is_a_number The source property can be converted to a numeric value. This comparison does not take a value.
equal_number The source property is numerically equal to the given value. This comparison ensures the values are able to be converted to numbers.
is_less_than The given property is numerically less than the given value.
is_less_than_or_equal The given property is numerically less than or equal to the given value.
is_greater_than The given property is numerically greater than the given value.
is_greater_than_or_equal The given property is numerically greater than or equal to the given value.
has_key The JSON property evaluates to an object and contains the given value as a key. Source must be response_json.
has_value The JSON property evaluates to an array and contains the given value as an element. Source must be response_json
is_null The JSON property has a NULL value. Source must be response_json.
Example Assertions

Status Code == 200

"assertions": [
    {
        "source": "response_status", 
        "comparison": "equal_number", 
        "value": 200
    }
]

JSON element 'address' contains the text "avenue"

"assertions": [
    {
        "source": "response_json", 
        "property": "address", 
        "comparison": "contains", 
        "value": "avenue"
    }
]

Response Time is faster than 1 second.

"assertions": [
    {
        "source": "response_time", 
        "comparison": "is_less_than", 
        "value": 1000
    }
]

Defining Variables

Variables allow you to extract data from request, subtest, and Ghost Inspector steps for use in subsequent steps in the test. Similar to Assertions, each variable is defined by a name, source, and property.

Variable Sources

response_status Create a variable from the value of the HTTP status code from the Response.
response_header Create a variable from the value of a Response Header. You must include a property with the name of the header to extract the value from.
response_json Parse the response body as JSON. You must include a property with the JSON path to extract.
response_xml Parse the response body as XML. You must include a property with the XPath to extract.
response_text Parse the response body as plain text. This source does not specify a property.
response_time Create a variable from the execution time of the response in milliseconds.
response_size Create a variable from the size of the Response body in bytes.
Example Variable

Set {{myUserId}} to the value of JSON element 'user_id'

"variables": [
    {
        "source": "response_json", 
        "property": "user_id", 
        "name": "myUserId"
    }
]

Changing Step Order

Update the execution order of the steps for a given test.

Request

PUT/buckets/<bucket_key>/tests/<test_id>/steps

PUT Body

The body of the PUT request should contain an ordered list of id's of the test step for the test. If any id's are omitted the request will fail. If the test contains a Condition, you must provide the step and its embedded steps in the form of an object like: { "id": "your_condition_id", "steps": ["your_embeded_step_id_1",...]}

Example PUT Request

The id's of each step can be retrieved from the test detail resource.

[
    "f6b09ca8-0803-478f-9919-d4ddc66db006",
    "839a5dff-dad3-4693-90a3-dcaba462514a"
]

Reorder steps with a condition.

[
    "f6b09ca8-0803-478f-9919-d4ddc66db006",
    {
        "id": "c6f2aa66-ed7e-4faf-a05d-5da7416da3ee",
        "steps": [
            "53f8e1fd-0989-491a-9f15-cc055f27d097",
            "626a024c-f75e-4f57-82d4-104fe443c0f3"
        ]
    },
    "839a5dff-dad3-4693-90a3-dcaba462514a"
]

Response

Returns the reordered list of test steps.


Test Step Detail

Get the details of a single test step for a given API test.

Request

GET/buckets/<bucket_key>/tests/<test_id>/steps/<step_id>

Response

Returns the details of the test step.

{
    "data": {
        "assertions": [
            {
                "comparison": "is_null",
                "source": "response_json"
            }
        ],
        "auth": {},
        "body": "",
        "form": {},
        "headers": {},
        "method": "GET",
        "note": "this is step 1",
        "step_type": "request",
        "url": "https://yourapihere.com/",
        "id": "f6b09ca8-0803-478f-9919-d4ddc66db006",
        "variables": []
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Modifying Test Steps

Update the details of a single test step for a given API test.

Request

PUT/buckets/<bucket_key>/tests/<test_id>/steps/<step_id>

PUT Body

The same JSON Body for adding a Test Step can be used to modify an existing step.

Example Request Step
{ 
    "method": "GET",
    "url": "https://yourapihere.com/example/path",
    "assertions": [
        {
            "source": "response_status", 
            "comparison": "equal_number", 
            "value": 200
        }
    ],
    "variables": [{
        "name": "source_ip",
        "property": "origin",
        "source": "response_json"
        }    
    ],
    "note": "get example data"
}

Response

Returns the updated details of the test step.


Delete Test Step

Delete a step from a test.

Request

DELETE/buckets/<bucket_key>/tests/<test_id>/steps/<step_id>

Response

Returns a 204 if the step is successfully deleted.