API Monitoring Script Engine Overview

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:

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. Using console.log is 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 request and response objects 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.