- Before the first step to set up environment data.
- Before each individual request step to dynamic modify request data.
- After a step completes to validate the response.
The Script Engine is ideal for cases that require more flexibility than simple Assertions and Variables. Scripts, assertions and variables work together seamlessly, each being evaluated at different points in the lifecycle of a test step.
Built-in Variables and Functions
Every script has access to the following values:
response object is only available in post-response scripts.
|The response body as a string.|
|A dictionary of response headers. The keys of the dictionary represent the header names. The dictionary values are arrays of values for the given key.|
|The reason portion of the HTTP status line returned. This value cannot be modified.|
|The time taken to execute the request and receive the response in milliseconds. This value cannot be modified.|
|The size of the response body in bytes. This value cannot be modified.|
|The response's status code. This value cannot be modified.|
request object is available in both pre-request and post-response scripts.
|The request body as a string.|
|A dictionary of form parameters sent with the request. The keys of the dictionary represent the parameter names. The dictionary values are arrays of values for the given key.|
|A dictionary of the request headers. The keys of the dictionary represent the header names. The dictionary values are arrays of values for the given key.|
|The hostname of the URL executed.|
|The request method (GET, POST, etc.) used to execute the request.|
|A dictionary of URL parameters (querystring) sent with the request. The keys of the dictionary represent the parameter names. The dictionary values are arrays of values for the given key.|
|The path segment of the URL without URL parameters.|
|The size of the request body in bytes. This value cannot be modified.|
|The fully-assembled URL that was accessed for the request.|
API Test Variables
variables global is available in both pre-request and post-response scripts.
|Return a value from the current variable context. See: Getting and Setting Variables.|
|Set a variable value. See: Getting and Setting Variables. Setting a variable in a pre-request script does not make the value available to the currently request step as scripts are evaluated after the template variables are inserted (see: Execution Order).|
|Write a string or pretty-printed version of an object to the output log viewable in test results.|
|Encode a string value as Base64.|
|Decode a Base64-encoded string.|
|The key of the bucket the test belongs to and was executed in.|
|Returns the value for the secret with key name. See: Secrets Management.|
- btoa (URL-friendly Base64 encode)
- atob (URL-friendly Base64 decode)
If you are receiving unexpected script errors, try the following to debug issues:
- Use the
log()function to write out values to be viewed with the test results.
log()will "pretty print" the values of objects so they are easily readable. Using
console.logis not recommended.
- Make sure the script is completing execution in under 3 seconds.
- Verify you are using functions supported in the documented version of included libraries.
- Do not overwrite the
responseobjects entirely. Edit only specific attributes as needed.
Technical Details and Limitations
- The Script Engine is a raw interpreter and does not include a framework like Node.js. Network (XHR or otherwise) and file system access is also prohibited. All HTTP calls must be made from request steps in your tests.
- Each script is evaluated as a single block with everything in the global scope. Module loaders like CommonJS, require(), AMD, etc. are not supported. While some npm modules may be able to be made to work, they do not by default.
- Built-in variables, functions and libraries are loaded first, followed by custom libraries. You may overwrite built-in functionality in your custom libraries and scripts, but doing so is unsupported and may cause unexpected results.
- All scripts must complete their execution within 20 seconds.