The Script Engine is a powerful tool for constructing API tests and validating API responses. Custom JavaScript can be executed at various points in the test execution lifecycle:
- 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.
Standard JavaScript modules like Math and RegExp are available along with a set of included helper libraries. Scripts have access to the current variable context and complete request and response data.
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 Data
The response object is only available in post-response scripts.
response.body | The response body as a string. |
response.headers | 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. |
response.reason | The reason portion of the HTTP status line returned. This value cannot be modified. |
response.response_time_ms | The time taken to execute the request and receive the response in milliseconds. This value cannot be modified. |
response.size_bytes | The size of the response body in bytes. This value cannot be modified. |
response.status | The response's status code. This value cannot be modified. |
Request Data
The request object is available in both pre-request and post-response scripts.
request.body | The request body as a string. |
request.form | 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. |
request.headers | 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. |
request.host | The hostname of the URL executed. |
request.method | The request method (GET, POST, etc.) used to execute the request. |
request.params | 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. |
request.path | The path segment of the URL without URL parameters. |
request.scheme | http or https |
request.size_bytes | The size of the request body in bytes. This value cannot be modified. |
request.url | The fully-assembled URL that was accessed for the request. |
API Test Variables
The variables global is available in both pre-request and post-response scripts.
variables.get(name) | Return a value from the current variable context. See: Getting and Setting Variables. |
variables.set(name, value) | 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). |
Helper Functions
log(Object|string) | Write a string or pretty-printed version of an object to the output log viewable in test results. |
encode_base64(value) | Encode a string value as Base64. |
decode_base64(value) | Decode a Base64-encoded string. |
runscope_bucket | The key of the bucket the test belongs to and was executed in. |
get_secret(key) | Returns the value for the secret with key name. See: Secrets Management. |
JavaScript Functions
The script interpreter also supports common JavaScript objects and functions:
- Math
- Date
- RegExp
- parseInt
- parseFloat
- decodeURI
- decodeURIComponent
- encodeURI
- encodeURIComponent
- escape
- unescape
- btoa (URL-friendly Base64 encode)
- atob (URL-friendly Base64 decode)
Debugging Scripts
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. Usingconsole.logis not recommended. - Verify your JavaScript is valid with a tool like JSLint.
- 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
requestandresponseobjects entirely. Edit only specific attributes as needed.
Technical Details and Limitations
The Script Engine is a V8-compatible (version 3.28), sandboxed JavaScript interpreter. To ensure the performance and security of your scripts and API data, some limitations have been put in place:
- 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.
0 Comments