Runscope API tests support variables, allowing you to pass one or more values between requests within a test. Variables are extremely helpful when you need to extract data from one request in your test and then apply or compare that value at another stage of your test. We sometimes refer to this as chaining requests. Variables can be declared before an API test run using Initial Variables (located in Environment settings), or you can create them dynamically after each request within your test. Runscope variables are limited to an individual test run, which means that they are reinitialized with each test run.
There are many use cases for needing to persist variables, such as storing credentials like an access token in an initial variable. This makes it convenient for making authenticated API requests in your tests and only having to manage those credentials in one place (in the environment settings).
But that convenience wanes when those credentials change often and you need to modify those settings by hand. Fortunately, the Runscope API allows you to update initial variable values programmatically. Leveraging this functionality is easy to do.
Updating Initial Variables Using the Runscope API
The Runscope API provides access to data in your Runscope account, including API tests, test steps, results, environment settings and much more. Initial variables belong to Environments settings, and are therefore accessible through the Environments resource in the API. The API includes methods for listing, fetching, creating, deleting and modifying environments.
1. Create a Runscope personal access token—The API uses OAuth 2.0, so you'll need to create an application from the the profile page. This will provide you with a Personal Access Token which can be used as an OAuth bearer token to access data in your account.
2. Fetch the test ID—All Runscope tests have a unique ID. You can obtain this ID from the dashboard URL while viewing/editing your test. Another way to obtain the ID is with the API using the List Tests method which lists all the tests in a bucket.
Tip: Use the Request Editor to explore the Runscope API. A handy button at the bottom of the application page will load the Request Editor with your bearer token pre-populated in the headers.
3. Fetch the environment JSON object—Pasting the test ID from above, make a GET call to the environments endpoint. This fetches an array of test environments. Select and copy the environment JSON object into your clipboard in preparation for the next step.
4. Edit environment JSON and submit changes—Paste the JSON representation of the environment settings into your favorite text editor and modify the value of the initial variable. Below, we're using the Request Editor to execute a PUT call to modify the environment record, placing the updated JSON in the request body. Notice how the environment ID is appended to the request URL (obtained from the JSON object).
Note of caution: A PUT call to the environments endpoint must be a complete JSON representation, meaning that if you submit a partial object, all of the settings will be overwritten for that test environment. This is why we copied the entire JSON object for the environment, and not just the variables. If you do end up making a mistake editing your tests or environments, you can always roll back to a previously saved state using Runscope Revision History.
Dynamically Updating Environments from within a Test Run
Now that you know how easy it is to make updates to initial variables and other environment settings, you might be wondering if you can embed a PUT call inside one of your tests. And indeed, it will work. But as stated above, proceed with caution—you are, after all, updating a live environment.
There's a Lot More API to Explore
Modifying initial variables is just one example of how the Runscope API can provide test management and configuration flexibility. Every aspect of your Runscope tests can be accessed via the API, including the ability to create and delete tests, environments and schedules programmatically. You can start playing around with the Runscope API by signing up for Runscope for free. Check out the API documentation for information on how to get started, and contact our support team if you need a hand.