API tests are comprised of a series of steps, most often HTTP requests. In addition to requests, you can also add additional types of steps to your tests like pauses and conditions.
The Editor is where you'll define the steps (HTTP requests, pauses, etc.) and execution order that make up a test. For each request in a test, you can specify the HTTP request data, assertions, variables and scripts by clicking on a request.
- HTTP Request Step
- Subtest Step
- Pause Step
- Condition Step
- Incoming Request Step
- Ghost Inspector Step
- Changing Execution Order
- Duplicating Requests
HTTP Request Step
Click Add Request to add an empty request template to the end of your test. Replace the placeholder data with the method, URL, headers and parameters for the API your test needs to call.
Request steps can be imported from other tools like Swagger, AWS API Gateway and Postman.
When a request step is executed each of the associated assertions, variables and scripts will be processed. The execution order is as follows:
- Pre-request Scripts are executed. The variable context from initial/variables and scripts and previous steps are available via
- The HTTP request is executed and a response is returned.
- Variables defined in the editor are processed on the response.
- Post-response Scripts are processed. Initial and request-specific variable values extracted from previous steps are available for use.
- Assertions defined in the test editor are processed on the response. If the
responseobject was modified by a Post-response Script, the data is not available to be evaluated by an Assertion.
Subtests steps can run other Runscope tests as part of a test run. This is useful for reusing tests that perform common functionality like generating a new access token, setup/teardown or creating suites or groups of tests.
A subtest step can use environment settings from the parent test, the subtest, or any shared environment in the parent test's bucket.
Subtest steps always use the location of the parent test's chosen environment and ignore location settings in the selected environment.
Assertions, Variables & Scripts
When a subtest completes, a JSON object representing the result is made available to run Assertions, Variables and Scripts against. You can validate the resulting subtest run was correct and extract data from the
variables object (the end result of the subtests's variable state) just like any other JSON payload. The JSON object you get back is the same as a webhook notification payload.
Passing Parameters to Subtests
By default, all of the selected environment's initial variables are passed to the subtest. To pass additional data, add 'Parameters' in the subtest step editor. These values will be passed to the subtest's initial variables, overriding any initial variable values with the same name.
Getting Variables from Subtests
You can use the "Variables" tab in a subtest step to extract variables that were create inside that subtest. Under "Property", you can access them by using
variables.variable_name_in_subtest. For example:
Pauses are a type of test step that allow you to introduce short delays between steps in the test plan. You can add as many pauses as you need, but tests require at least one request to execute. If your test is set to use a schedule, take care that the total amount of execution time is less than your test's schedule interval.
Click Add Pause to add a step to your test to pause test run execution for a brief period of time. Pause duration can be from 1-180 seconds long. Pauses are not guaranteed to be exact, but durations are guaranteed to be at least the amount of time specified.
Incoming Request Step
Incoming Requests allow you to pause execution of a test run until a request is received at a unique URL. This is useful for testing webhooks or other asynchronous HTTP callback methods. See examples.
Important Considerations for Incoming Steps
- The response to the incoming request will be a 200 OK with an empty response body.
- The max wait time for an incoming request is 10 minutes.
- If you make an incoming request before this step is reached in a test run, we'll store it for up to 30 seconds.
- Tests with incoming steps should only be executed from a single location, on a schedule that is longer than the expected response time window. Simultaneous test runs may cause unexpected results.
Condition steps are a way to conditionally run select test steps based on criteria you define. If the condition assertion evaluates to True, test steps embedded within a condition are executed. Otherwise, embedded test steps are skipped.
To create a new condition, click Add Condition, and drag any test steps you want conditionally executed into it. A condition assertion is an expression made up of a left operand, a comparison operator, and a right operand. When you define your condition assertion, you can hardcode the values or use any variables you've previously defined in your test or shared environment settings. To include the value of a variable in a condition assertion, enter the name of the variable surrounded by double braces e.g.
Assertion comparisons in conditions behave the same way they do in request steps, and you have access to all the same comparison operators you would in request steps. See the assertions comparison chart for more details about each type of comparison operator.
Ghost Inspector Steps
When your team is connected with a Ghost Inspector account, a new step type is available to add to your tests: UI test. This is useful if your API requires a sign in step before requests can be issued. Learn more in the Ghost Inspector integration guide.
Changing Execution Order
To change the execution order of requests within a test, drag the Reorder icon for a given request and drop it where you want it to be executed. The new order will be used on subsequent test runs. If you are using variables in your request data, take care to make sure that the request that defines a given variable comes before the request(s) that use it.
To create a copy of an existing request in a test, click the Duplicate icon for any existing request in the test. The new request will be added to the end of the test.