Help › Guide
Scripts
Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.
A step of an operation may run JavaScript before its request is sent and after its response comes back. A script changes the request, checks the response, and passes values to later steps. It runs in a sandbox wherever the run does: on this computer, on a server and on a private agent.
Where scripts are written
- In the step's editor, in Operations: the "Scripts" part at its end. "Add scripts" opens two code fields, "Before its request is sent" and "After its response", highlighted as JavaScript, a "Sets" field, and what a script is given beside them.
- In an Arazzo document, as
x-reqlyn-scripton a step, withbefore,afterandsets(Arazzo). Exporting an operation writes them back the same way. - From a Postman, Insomnia or Bruno collection: their scripts are translated when the collection is taken as an operation (below).
- stepId: issue
operationId: echo
x-reqlyn-script:
after: |
const sent = JSON.parse(rq.response.body.body);
rq.assert(rq.response.status === 200, 'the echo answered');
rq.set('token', sent.token);
sets: [token]
What a script is given
Every script is given rq:
| Name | Stage | What it is |
|---|---|---|
rq.request.url |
before | The address. Its path and query may change; where it goes may not. |
rq.request.headers |
before | The headers that are sent, by name. Add, change or delete them. |
rq.request.body |
before | A text or JSON body, as text. Set an object and it is written as JSON. A form's body cannot be changed. |
rq.request.method |
both | The method. It cannot change: whether a request writes decides how it is sent. |
rq.response.status |
after | Its status. |
rq.response.headers |
after | Its headers, by name in lower case. |
rq.response.body |
after | Its body read as JSON; an XML step's as text; null when it is neither. |
rq.get(name) |
both | An input of the operation, or a value a script set. |
rq.set(name, value) |
both | Sets a value: text, a number or a boolean, as an input is. |
rq.assert(condition, message) |
both | A criterion of the step. One that does not hold fails it. |
An after script runs once the step's own checks pass: its status and its "Succeeds when" criteria.
Values passed on
A value a script sets fills {{name}} in later steps' requests, before the operation's inputs of that name do. A before script's value fills its own request too. A step names what its scripts set ("Sets", or sets in Arazzo), and a script may set no other name: a placeholder nobody declared could be filled with a secret. A request that still holds a declared name when it is about to go, because no script has set it yet, is not sent (SCRIPT_UNSET). It is never filled from a variable of that name.
Assertions
Each rq.assert is a criterion of the step. The test result lists them under their step, "Holds: the echo answered (after script, line 2)" or, in red, "Does not hold". A server's run lists them too, in Runs, and a JUnit report (reqlyn run --junit) makes each a test case after its step's. One that does not hold fails the step (SCRIPT_ASSERTION) with its line, as a criterion does: the step's actions and "If it fails" apply. A script that throws fails the step with its line too (SCRIPT_ERROR).
The sandbox
A script has the JavaScript language and nothing else. There is no network, no file and no module: fetch, XMLHttpRequest, WebSocket, EventSource, require and importScripts are refused by name (SCRIPT_REFUSED). A script runs for at most 50 ms and uses at most 16 MiB; past either it is stopped (SCRIPT_LIMIT), even in a loop that never ends. On a server, the deployment manifest sets other limits for a version where it is hosted, up to a second and 64 MiB (scripts, DEPLOYMENT.md).
A before script cannot send its request elsewhere: its scheme, host and port stay as they were. It cannot add a {{placeholder}} the request did not hold, or move one to another place in it (SCRIPT_CHANGE). Either could take a credential or a secret somewhere it was not meant to go.
Secrets
A script never sees a secret. The request it is given still holds the environment's variables as their {{name}}, and its credential is added after the script runs. A secret value that comes back anyway, such as an API that echoes the credential it was sent, reads as [masked]. On this computer that is the environment's secret variables and what the step's credential sends; on a server, every secret value the run used; on an agent, its credentials, the tokens they bought and what its vault gave. An assertion's message is masked in a run's record as its reasons are.
Scripts from Postman, Insomnia and Bruno
"From a description or collection…" in Operations opens a Postman collection, an Insomnia export (v4 JSON or a v5 YAML collection) or a Bruno collection, exported as JSON or as its folder of .bru files (choose any one of them). Choosing a request takes it as a step. "Take every request as a step, in order" takes them all, as the tool's runner sends them. Each step comes with its scripts translated: the collection's, its folders' and its own, in the order the tool runs them. What they set is declared. Add an output field, and the operation tests and saves.
A script keeps its own text and runs with the tool's API as Reqlyn gives it:
- Postman:
pm.response(code,json(),text(),headers.get,to.have.status,to.have.header,to.be.ok),pm.expect(equal,eql,a,include,property,length,above,below,least,most,within,oneOf,match,ok,true,false,null,undefined,exist,empty, withnotanddeep),pm.test, andpm.environment,pm.variables,pm.collectionVariablesandpm.globalsas one scope of the run's inputs and what scripts set. Before a request,pm.request.headersandpm.request.body.rawas well. - Insomnia:
insomnia, the same aspm. - Bruno:
bru(getVar,setVar,getEnvVar,setEnvVar,hasVar),req(getUrl,getMethod,getHeader,getHeaders,getBody; before a request alsosetUrl,setHeader,setBody),res(status,headers,bodyand their getters),testandexpect. After a request come its post-response scripts, its assertions written as tests (res.status: eq 200), then its tests.
A test that fails is recorded and the script goes on, as in those tools; the step fails once the script ends, naming the test and its line.
A script that uses more than this is kept on its step inside a comment and not run. Examples are pm.sendRequest, cookies, postman.setNextRequest, require, the older tests[…], bru.sendRequest and an assertion's between. The collection's review lists each such line in the warning color, with why. A value a script sets under a name that looks secret is masked as it is imported. An environment's own variables are not read by a script, so pm.environment.get of one gives nothing.
Errors
| Code | Means |
|---|---|
| SCRIPT_ASSERTION | An assertion or a translated test did not hold. |
| SCRIPT_ERROR | The script threw. |
| SCRIPT_LIMIT | It ran past its time or its memory. |
| SCRIPT_REFUSED | It reached for the network or a file. |
| SCRIPT_CHANGE | A before script changed what it may not. |
| SCRIPT_VALUE | It set a value its step does not declare, or one an input could not be. |
| SCRIPT_UNSET | A request held a declared name no script had set. |
| STEP_NO_SCRIPTS | It ran on something that runs no scripts, such as an agent older than scripts. |
The full list is in Errors.
Help for Reqlyn 0.5.1. All help topics