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-script on a step, with before, after and sets (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, with not and deep), pm.test, and pm.environment, pm.variables, pm.collectionVariables and pm.globals as one scope of the run's inputs and what scripts set. Before a request, pm.request.headers and pm.request.body.raw as well.
  • Insomnia: insomnia, the same as pm.
  • Bruno: bru (getVar, setVar, getEnvVar, setEnvVar, hasVar), req (getUrl, getMethod, getHeader, getHeaders, getBody; before a request also setUrl, setHeader, setBody), res (status, headers, body and their getters), test and expect. 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