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