Help › Tutorials

Tutorial 5: Scripts

Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.

A step can run JavaScript before its request and after its response: to check what came back, to pass a value to the next step, and to change the request it sends. This tutorial runs a scripted Arazzo workflow from the command line, watches an assertion fail and the sandbox stop what it must, then takes a Postman collection with tests into the desktop as an operation.

Every command below was run against the fixtures as written. It takes about twenty minutes.

Before you start

  • The fixture APIs are running (cargo run -p reqlyn-fixtures).
  • You have done tutorial 1, or at least step 1 of it: the variable inventory set to http://127.0.0.1:8787.
  • Copy the repository's fixtures/arazzo/ folder somewhere to work in, and open a terminal there. It holds scripted.arazzo.yaml and inventory.openapi.yaml. Keep fixtures/postman/scripted.postman_collection.json at hand for step 5.

1. Read the scripts

Open scripted.arazzo.yaml. It has two steps, both posting to the fixture's echo, which answers with what it was sent:

  • issue sends {"token": $inputs.given}. Its x-reqlyn-script has an after script that reads the echoed body, asserts twice and sets token. sets: [token] declares that name.
  • use sends {"token": "{{token}}"}, the value the first step's script set. Its before script adds a trace field to the JSON body before it goes.

2. Run it

reqlyn arazzo run scripted.arazzo.yaml --input '{"given": "abc-123"}'
{
  "sent": "{\"token\":\"abc-123\",\"trace\":\"trace-abc-123\"}"
}

The second request carried the token the first step's script set, in a body its own script added to.

3. Watch an assertion fail

reqlyn arazzo run scripted.arazzo.yaml --input '{"given": "zzz"}'
Step "issue", after script: assertion failed on line 3: the token starts with abc

It ends with status 1. The assertion is the script's third line; the second request was never sent.

Store the document as an operation, and run it with a JUnit report:

reqlyn arazzo save scripted.arazzo.yaml
reqlyn run "A token checked by a script and sent on" --input '{"given": "zzz"}' --junit report.xml

report.xml holds a case for the step, then a case for each of its assertions, issue: the echo answered passing and issue: the token starts with abc failing with SCRIPT_ASSERTION, and the output contract skipped. A CI system shows the script's checks as tests.

4. Meet the sandbox

Make three copies of scripted.arazzo.yaml and change the use step's before script in each:

  • In looping.arazzo.yaml, put while (true) {} before its first line.
  • In reaching.arazzo.yaml, put const sent = fetch('https://example.com/'); before its first line.
  • In elsewhere.arazzo.yaml, add rq.request.url = 'https://example.com/echo'; after its last line.

Run each with --input '{"given": "abc-123"}':

Step "use", before script: it ran longer than 50 ms and was stopped.
Step "use", before script: it reached for fetch("https://example.com/"). A script cannot reach the network or files.
Step "use", before script: it changed where the request goes (its scheme, host or port), which a script cannot: the request's credential would go with it.

A script cannot run for ever, reach the network or a file, or send its request somewhere else.

5. Take a Postman collection as an operation

scripted.postman_collection.json has three requests to the echo:

  • The collection's pre-request script sets stamp.
  • "Place an order" sends it, and its tests check the echo and set order.
  • "Send it on" sends the order, and its test checks that it arrived.
  • "Tell a hook" has a test that calls pm.sendRequest.

In the desktop:

  1. In Operations, start a new operation with + and choose From a description or collection…. Open scripted.postman_collection.json.
  2. The panel lists its three requests. In the warning color it says what was not translated: "the test script of Tell a hook, line 1: pm.sendRequest is not translated".
  3. Choose Take every request as a step, in order. Three steps appear. Open place-an-order: its Scripts part shows the collection's pre-request script before its request, its tests after its response, and "Sets: stamp, order". tell-a-hook's test is there too, inside a comment that says why it is not run.
  4. Postman collections declare no output, so add one: under Output contract, Add field, name it sent, from send-it-on, path body, a string.
  5. Name the operation Scripted order and choose Test locally with {}.

The output is {"sent": "{\"order\": \"ord-7\"}"}. Under each step, its Postman tests are listed as they held: "Holds: the echo answered (after script, line 2)", "Holds: the stamp was sent (after script, line 4)" and "Holds: the order was sent on (after script, line 2)". The stamp set before the first request was sent with it, and the order its test set went on to the next. Save it. Published to a server, it runs the same on the server and on its private agents.

What next

  • Scripts: everything a script is given, the sandbox, secrets, and what of Postman, Insomnia and Bruno is translated.
  • Tutorial 3: publish an operation to a server.

Help for Reqlyn 0.5.1. All help topics