For more information about API Checks in general, see our API Check article.
JavaScript Step
A JavaScript step runs arbitrary JavaScript code and saves the result into a custom variable. This can be used to add custom functionality to API Checks.
JavaScript steps run in a JavaScript engine outside of a browser. This means that you will not be able to interact with the DOM, make XHR, or log to the console, as these are all implemented by the browser.
Note: Each step runs in isolation. If you create a variable in one step, you will not have access to it in the following step. You can pass data between steps by saving to a custom variable, which will automatically be included as a variable in the next step. If you need to pass multiple values to a later step, you can save a variable in JSON format containing all of the values and parse that JSON in the subsequent step.
Example
A common use case is to generate a specific date or time format. Rigor’s Built-In Variables have some default variables that you can use to generate various formats, but suppose you need a format where the day of the month doesn’t have a leading 0. You can do this with the following sample step:
Results
The result is saved to a custom variable as a string. For example, if the result is saved to a custom variable named result, then the result can be accessed in other steps as {{custom.result}} (or in a following JavaScript Step as custom.result). A result is the last thing that is evaluated in a step. JavaScript objects (including arrays) are converted to JSON strings. For example, if you enter the following JavaScript code:
var someObject = {key1: 'A string', key2: 42}
someObject;
The result will be the following string:
{"key1":"A string","key2":42}
Note: Make sure you don’t try to return the value, as that will cause the step to fail.
Variables
JavaScript Steps have access to all of the variables that any other steps have access to, but they are accessible as JavaScript objects. This means that instead of accessing the response body with {{response.body}}, you can access via response.body in the supplied JavaScript.
JavaScript Files
You can upload JavaScript files to reuse across checks. Included files will be run before the code for each JavaScript in the order that the files are included in the check, and will have access to all of the variables.
In the example where we added a function to generate a custom formatted date string, we added a function that generated the date string. If we needed to use that across checks, we could copy that string into a file, upload that to your account, and attach it to an API Check. Then you could access the formatDatefunction from any checks that include the file. If you are going to have many custom functions, we encourage you to use JavaScript Files to organize and consolidate the logic.
For more information, please see our JavaScript Files article.
Failures
Syntax Errors
Any syntax errors will fail the step.
Runtime Errors
Any runtime errors will fail the step. For example, calling a function that has not been defined is a runtime error.
Technical Note: Rigor uses the V8 engine (version 3.16.14.0) to run the JavaScript. If you are having trouble getting a step to pass, make sure that the code can run on this version.
Timeout
JavaScript Steps have a timeout of 1 second per step. Any step that exceeds this timeout will fail.