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 - A standard HTTP request step.
pause - Pause the execution of the test for the given duration.
condition - Evaluate a condition and optionally other steps within the condition.
ghost-inspector - Execute a Ghost Inspector UI test and wait for the results.
subtest - Execute a different Runscope Test and wait for the results.

Request Step

The POST body must be a JSON object.

Adding Request Step

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps' \
				-X POST \
				-H 'Content-Type: application/json' \
				-H 'Authorization: Bearer <access_token>' \
				-d '{"step_type":"request","method":"POST","url":"https://yourapihere.com/example/path","body":"{ \"hello\": \"world\" }",assertions": [{"source":"response_status","comparison":"equal_number","value": 200}],"variables":[{"name":"source_ip","property":"origin","source":"response_json"}],"auth": {"username":"authBasicUsername","auth_type":"basic","password":"authBasicPassword"},"headers": {"Content-Type": ["application/json"],"Accept": [*/*"]},"scripts": ["log(\"This is a sample post-response script\");","log(\"This is a second sample post-response script\");"],"before_scripts": ["log(\"This is a sample pre-request script\");","log(\"This is a second sample pre-request script\");"],"note":"get example data"}'

Adding Request Steps Request Attributes

The following parameters can be set on the request step, and these are formatted the same as the test detail response output.

Attributes

step_typestring

Always set to request
methodstring

The HTTP method for this request step
urlstring

The URL to make a request to for this step. This may contain both query string parameters and variables
bodystring

A string to use as the body of the request
assertionsarray

A list of assertions to apply to the HTTP response from this request
Show/Hide Child Attributes
- source string
  
  The source where the assertion is being run against
- comparison string
  
  The comparison value that was used
- value integer
  
  The value that was used in the comparison
variablesarray

A list of variables to extract out of the HTTP response from this request
Show/Hide Child Attributes
- name string
  
  The name of the variable
- property string
  
  The property where the value for this variable is being pulled from
- sourcestring
  
  The data source for the variable. Possible values are json, xml, response_headers, response_size_bytes, response_time_ms or status_code
authobject

An authentication object with either basic, OAuth 1.0, OAuth 2.0 or client certificate credentials for authenticating this request
Show/Hide Basic authentication
- passwordstring
  
  Password for this authentication
- usernamestring
  
  User name for this authentication
- auth_typestring
  
  The authorization type for this authentication. Value is basic
Show/Hide OAuth 1.0
- consumer_keystring
  
  The Consumer Key used for asking the service for authorization
- consumer_secretstring
  
  The Consumer Secret used for asking the service for authorization
- access_tokenstring
  
  The token used for accessing the resource
- token_secretstring
  
  The secret that accompanies the access token
- signature_typestring
  
  Signature type. Value can be auth_header, query, or body
- auth_typestring
  
  The authorization type for this authentication. Value is oauth_1
Show/Hide OAuth 2.0 (short)
- access_tokenstring
  
  Value of the access token
- token_locationstring
  
  Location of the token. Value can be query or auth_header
- auth_typestring
  
  The authorization type for this authentication. Value is oauth_2
Show/Hide OAuth 2.0 (extended)
- Note: Not all parameters are mandatory. Only the parameters included in the payload are saved in the test Environment or Template. Parameters not included in the payload will show as "null" in the response.
- grant_typestring
  
  OAuth 2.0 grant type. Value can be authorization_code, authorization_code_pkce, implicit, password_credentials, or client_credentials
  
  Important! For Authorization Code, Authorization Code with PKCE, and Implicit grant types, you must add or register the API Monitoring Redirect URI, https://www.runscope.com/oauth2/callback, to the third-party authorization site. See Redirect URI Registration for details.
- access_tokenstring
  
  Value of the access token
- token_locationstring
  
  Location of the token. Value can be query or auth_header
- auth_urlstring
  
  Third-party authorization URL
- access_token_urlstring
  
  URL for the access token
- client_idstring
  
  The ID of the client
- client_secretstring
  
  The client secret
- code_challenge_methodstring
  
  Method for challenging code, either plain or S256. For PKCE grant type only. Default is SHA-256
- code_verifierstring
  
  The code verifier string generated by the app, if available. For PKCE grant type only
- passwordstring
  
  Password for third-party authorization
- usernamestring
  
  User name for third-party authorization
- scopestring
  
  The OAuth 2.0 scope string, if used
- statestring
  
  The OAuth 2.0 state string, if used
- client_authenticationstring
  
  Method of client authentication, either either sent in basic_auth_header or body. Default is basic_auth_header
- auth_typestring
  
  The authorization type for this authentication. Value is oauth_2
- refresh_tokenstring
  
  Value of the refresh token
- is_auto_refresh_tokenboolean
  
  Determines whether the refresh token is auto-generated
headers object

An object with keys as header names matched to their values. Values can either be a single string or an array of strings
Show/Hide Child Attributes
- headerNamearray
  
  The header name of this header (i.e. Accept) and it's list of values for this header name (i.e. */*)
formobject

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
scriptsarray

A list of post-response scripts to run after this request
before_scriptsarray

A list of pre-request scripts to run before this request
notestring

A description or note for this request step
skippedboolean

If this is set to true, this step will be skipped when the test is executed

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Adding Request Step
Sample POST Body (JSON) for Request Step

{ 
    "step_type": "request",
    "method": "POST",
    "url": "https://yourapihere.com/example/path",
    "body": "{ \"hello\": \"world\" }",
    "assertions": [
        {
            "source": "response_status", 
            "comparison": "equal_number", 
            "value": 200
        }
    ],
    "variables": [
        {
            "name": "source_ip",
            "property": "origin",
            "source": "response_json"
        }    
    ],
    "auth": {
        "username": "authBasicUsername",
        "auth_type": "basic",
        "password": "authBasicPassword"
    },
    "headers": {
        "Content-Type": [
            "application/json"
        ],
        "Accept": [
            "*/*"
        ]
    },
    "scripts": [
        "log(\"This is a sample post-response script\");",
        "log(\"This is a second sample post-response script\");"
    ],
    "before_scripts": [
        "log(\"This is a sample pre-request script\");",
        "log(\"This is a second sample pre-request script\");"
    ],
    "skipped": false,
    "note": "get example data"
}

Response201 CREATED

{
    "data": {
        "created_at": 1438832081,
        "created_by": {
            "email": "grace@example.com",
            "name": "Grace Hopper",
            "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
        },
        "default_environment_id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
        "description": null,
        "environments": [
            {
                "emails": {
                    "notify_all": false,
                    "notify_on": "all",
                    "notify_threshold": 1,
                    "recipients": []
                },
                "initial_variables": {
                    "base_url": "https://api.example.com"
                },
                "integrations": [
                    {
                        "description": "Pagerduty Account",
                        "integration_type": "pagerduty",
                        "id": "53776d9a-4f34-4f1f-9gff-c155dfb6692e"
                    }
                ],
                "name": "Test Settings",
                "parent_environment_id": null,
                "preserve_cookies": false,
                "regions": [
                    "us1"
                ],
                "remote_agents": [],
                "script": "",
                "test_id": "626a024c-f75e-4f57-82d4-104fe443c0f3",
                "id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
                "verify_ssl": true,
                "webhooks": null
            }
        ],
        "last_run": null,
        "name": "Sample Name",
        "schedules": [],
        "steps": [
            {
                "assertions": [
                    {
                        "comparison": "is_equal",
                        "source": "response_status",
                        "value": 200
                    }
                ],
                "auth": {},
                "body": "",
                "form": {},
                "headers": {},
                "method": "GET",
                "note": "",
                "step_type": "request",
                "url": "https://yourapihere.com/",
                "id": "53f8e1fd-0989-491a-9f15-cc055f27d097",
                "variables": []
            }
        ],
        "trigger_url": "http://api.runscope.com/radar/b96ecee2-cce6-4d80-8f07-33ac22a22ebd/trigger",
        "id": "626a024c-f75e-4f57-82d4-104fe443c0f3"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Pause Step

The POST body must be a JSON object.

Adding Pause Step

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps' \
				-X POST \
				-H 'Content-Type: application/json' \
				-H 'Authorization: Bearer <access_token>' \
				-d '{"step_type": "pause","duration": 5}'

Adding Pause Steps Request Attributes

The following parameters can be set on the pause step, and these are formatted the same as the test detail response output.

Attributes

step_typestring

Always set to pause
durationinteger

This is the duration of the pause step in seconds. It must be an integer between 1 and 120

Condition Step

The POST body must be a JSON object.

Adding Condition Step

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps' \
				-X POST \
				-H 'Content-Type: application/json' \
				-H 'Authorization: Bearer <access_token>' \
				-d '{"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/"}]}'

Adding Condition Steps Request Attributes

The following parameters can be set on the condition step, and these are formatted the same as the test detail response output.

Attributes

step_typestring

Always set to condition
left_valuestring

The left hand value of the assertion
comparisonstring

An assertion comparison to determine whether or not to execute the embedded steps
right_valuestring

The right-hand side value of the assertion, if one is required
stepsarray

An array of test steps to execute if the comparison evaluates successfully

Adding Condition Step
Sample POST Body (JSON) for Condition 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/"
        }
    ]
}

Response201 CREATED

{
    "data": {
        "created_at": 1438832081,
        "created_by": {
            "email": "grace@example.com",
            "name": "Grace Hopper",
            "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
        },
        "default_environment_id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
        "description": null,
        "environments": [
            {
                "emails": {
                    "notify_all": false,
                    "notify_on": "all",
                    "notify_threshold": 1,
                    "recipients": []
                },
                "initial_variables": {
                    "base_url": "https://api.example.com"
                },
                "integrations": [
                    {
                        "description": "Pagerduty Account",
                        "integration_type": "pagerduty",
                        "id": "53776d9a-4f34-4f1f-9gff-c155dfb6692e"
                    }
                ],
                "name": "Test Settings",
                "parent_environment_id": null,
                "preserve_cookies": false,
                "regions": [
                    "us1"
                ],
                "remote_agents": [],
                "script": "",
                "test_id": "626a024c-f75e-4f57-82d4-104fe443c0f3",
                "id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
                "verify_ssl": true,
                "webhooks": null
            }
        ],
        "last_run": null,
        "name": "Sample Name",
        "schedules": [],
        "steps": [
            {
                "assertions": [
                    {
                        "comparison": "equal_number",
                        "source": "response_status",
                        "value": 200
                    }
                ],
                "method": "GET",
                "step_type": "request",
                "url": "https://yourapihere.com/"
            }
        ],
        "trigger_url": "http://api.runscope.com/radar/b96ecee2-cce6-4d80-8f07-33ac22a22ebd/trigger",
        "id": "626a024c-f75e-4f57-82d4-104fe443c0f3"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Ghost Inspector Step

The POST body must be a JSON object.

Adding Ghost Inspector Step

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps' \
				-X POST \
				-H 'Content-Type: application/json' \
				-d '{"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"}]}'

Adding Ghost Inspector Steps Data Attributes

The following parameters can be set on the ghost inspector step, and these are formatted the same as the test detail response output.

Attributes

step_typestring

Always set to ghost-inspector
integration_idstring

The id of an account integration with Ghost Inspector as found in the team integrations list
suite_idstring

The Ghost Inspector suite id of the test to run. You can find this in the Ghost Inspector API
test_idstring

The Ghost Inspector test id of the test to run. You can find this in the Ghost Inspector API
is_custom_start_urlboolean
start_urlstring

A custom Start URL for the Ghost Inspector test to execute with
assertionsarray

A list of assertions to apply to the incoming webhook result from Ghost Inspector
variablesarray

A list of variables to extract out of the incoming webhook result from Ghost Inspector

Adding Ghost Inspector Step
Sample POST Body (JSON) for 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"
        }
    ]
}

Response201 CREATED

{
    "data": {
        "created_at": 1438832081,
        "created_by": {
            "email": "grace@example.com",
            "name": "Grace Hopper",
            "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
        },
        "default_environment_id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
        "description": null,
        "environments": [
            {
                "emails": {
                    "notify_all": false,
                    "notify_on": "all",
                    "notify_threshold": 1,
                    "recipients": []
                },
                "initial_variables": {
                    "base_url": "https://api.example.com"
                },
                "integrations": [
                    {
                        "description": "Pagerduty Account",
                        "integration_type": "pagerduty",
                        "id": "53776d9a-4f34-4f1f-9gff-c155dfb6692e"
                    }
                ],
                "name": "Test Settings",
                "parent_environment_id": null,
                "preserve_cookies": false,
                "regions": [
                    "us1"
                ],
                "remote_agents": [],
                "script": "",
                "test_id": "626a024c-f75e-4f57-82d4-104fe443c0f3",
                "id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
                "verify_ssl": true,
                "webhooks": null
            }
        ],
        "last_run": null,
        "name": "Sample Name",
        "schedules": [],
        "steps": [
            {
                "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"
                    }
                ]
            }
        ],
        "trigger_url": "http://api.runscope.com/radar/b96ecee2-cce6-4d80-8f07-33ac22a22ebd/trigger",
        "id": "626a024c-f75e-4f57-82d4-104fe443c0f3"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Subtest Step

The POST body must be a JSON object.

Adding Subtest Step

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps' \
				-X POST \
				-H 'Content-Type: application/json' \
				-H 'Authorization: Bearer <access_token>' \
				-d '{"step_type":"request","method":"POST","url":"https://yourapihere.com/example/path","body":"{ \"hello\": \"world\" }",assertions": [{"source":"response_status","comparison":"equal_number","value": 200}],"variables":[{"name":"source_ip","property":"origin","source":"response_json"}],"auth": {"username":"authBasicUsername","auth_type":"basic","password":"authBasicPassword"},"headers": {"Content-Type": ["application/json"],"Accept": [*/*"]},"scripts": ["log(\"This is a sample post-response script\");","log(\"This is a second sample post-response script\");"],"before_scripts": ["log(\"This is a sample pre-request script\");","log(\"This is a second sample pre-request script\");"],"note":"get example data"}'

Adding Subtest Steps Data Attributes

The following parameters can be set on the subtest step, and these are formatted the same as the test detail response output.

Attributes

step_typestring

Always set to subtest
test_uuidstring

The embedded test's unique id
environment_uuidstring

The environment uuid to run with the subtest
bucket_keystring

The bucket key to which the subtest belongs
assertionsarray

A list of assertions to apply to the incoming subtest result
variablesarray

A list of variables to extract out of the incoming subtest result
paramsarray

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

Adding Subtest Step
Sample POST Body (JSON) for 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}}"
        }
    ]
}

Response201 CREATED

{
    "data": {
        "created_at": 1438832081,
        "created_by": {
            "email": "grace@example.com",
            "name": "Grace Hopper",
            "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
        },
        "default_environment_id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
        "description": null,
        "environments": [
            {
                "emails": {
                    "notify_all": false,
                    "notify_on": "all",
                    "notify_threshold": 1,
                    "recipients": []
                },
                "initial_variables": {
                    "base_url": "https://api.example.com"
                },
                "integrations": [
                    {
                        "description": "Pagerduty Account",
                        "integration_type": "pagerduty",
                        "id": "53776d9a-4f34-4f1f-9gff-c155dfb6692e"
                    }
                ],
                "name": "Test Settings",
                "parent_environment_id": null,
                "preserve_cookies": false,
                "regions": [
                    "us1"
                ],
                "remote_agents": [],
                "script": "",
                "test_id": "626a024c-f75e-4f57-82d4-104fe443c0f3",
                "id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
                "verify_ssl": true,
                "webhooks": null
            }
        ],
        "last_run": null,
        "name": "Sample Name",
        "schedules": [],
        "steps": [
            {
                "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}}",
                    }
                ]
            }
        ],
        "trigger_url": "http://api.runscope.com/radar/b96ecee2-cce6-4d80-8f07-33ac22a22ebd/trigger",
        "id": "626a024c-f75e-4f57-82d4-104fe443c0f3"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}