Setup & teardown scripts
You can tailor each HTTP request made by an API check to your exact situation by using setup and/or teardown scripts.
- Setup scripts give you access to properties like the URL, headers and query parameters of the HTTP request as well as all environment variables. Popular use cases are signing HMAC requests, requesting tokens and setting up test data.
- Teardown scripts give you access to all the same data as the setup scripts plus the response object, allowing you to read and modify the response. Use cases are cleaning up test data and scrubbing sensitive response data for regulatory reasons.
Setup scripts allow you to process test data and configure API Check requests.
A setup script executes before any requests are made. You have access to a set of built-in variables to tweak the HTTP request and a set of 3rd party libraries available in each runtime.
Add custom request configuration
If your API Check’s request configuration relies on setup script data, adjust the
Common examples are:
- Setting a custom header
- Updating the request URL
- Defining of a cookie
Use environment variables to access values in your API Check request body
If your API Check’s request body relies on data evaluated in a setup script, use environment variables to make it accessible.
// define a variable that should be accessible in the API Check response body process.env.MY_VALUE = 'my value'
Access your defined environment variables in the API Check request body with
To learn more about setup scripts, check our setup script examples.
Teardown scripts are run after the HTTP request has finished, but before any assertions are validated. Next to the request and environment objects, teardown scripts also have access to the response object. Use teardown scripts to clean up any created test data or clean up response data that might contain sensitive information you do not want to store on the Checkly backend.
To learn more about teardown scripts, check our teardown script examples.
Reusable code snippets
To DRY (Don’t Repeat Yourself) up your code, we strongly advice you create all setup and teardown scripts as code snippets. You can create, update and delete code snippets in the ‘Code Snippets’ section. Snippets are available to all checks.
Once created, just select any snippets from the drop down menu in setup and teardown scripts section of your API check.
It’s also possible to import snippets from your setup or teardown scripts. This can be valuable if setup and teardown scripts are similar across checks, but still require some customization. Find more information in the snippet documentation.
Inside each script, you have access to certain data structures of the API check lifecycle.
You have access to all environment variables configured in the variables section on the account page. They are available under
You can create, read, update and delete any of the attributes in this object.
The current data center location the script is running in is exposed as the AWS region code in the
// read values and use them for further processing const myValue = process.env.MY_KEY // write values process.env.MY_KEY = myValue + 10 // add a new key/value pair process.env.NEW_KEY = 'new value' // remove a key delete process.env.SOME_OTHER_KEY // read the current region const region = process.env.REGION
In setup scripts, the modified environment object is used for the subsequent HTTP request. In teardown script, the modified environment object is just there for informational purposes.
More about using environment variables
||The HTTP request method, i.e. ‘GET’, ‘POST’ etc.||String|
||The request URL. Any separately defined query parameters are added at the end.||String|
||The request body in string format.||String|
||The request headers.||Object|
||The request query parameters.||Object|
||The response status code, i.e. 200 or 404.||Number|
||The response status text, i.e. ‘Ok’ or ‘Not found’.||String|
||The response body in string format. You will need to use
||Various timestamps for the request stage relative to the starting time.||Object|
||Time durations for each request phase.||Object|
General runtime variables
The setup and teardown runtime also exposes a set of environment variables (e.g. process.env.CHECK_NAME) to figure out what check, check type etc. you are running.
||The name of the check being executed.||String|
||The UUID of the check being executed.||String|
||The type of the check being executed, (
||The UUID of the result where the run result will be saved.||String|
||The request URL of the
All setup and teardown scripts run in a sandboxed environment on our cloud backend. You do not have full access to the Node.js standard library or to arbitrary NPM modules.
Check out our runtimes documentation for a full specification of which modules are included.
- Setup and teardown scripts are implicitly wrapped in async function. This means you can always use
- You cannot use nested callbacks as there is no way to determine the callback function. Always use
- You need to include modules and libraries explicitly, e.g.
const moment = require('moment')before you can use them.
- You can pass a maximum of 256KB of data to and from the check’s main request (e.g. using
request.body = data).
You can contribute to this documentation by editing this page on Github