Help › Tutorials
Tutorial 1: a first operation in the desktop
Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.
You will send a request, save two requests, and compose them into an operation that takes a device id and returns its host name and whether it is compliant: one call to an inventory API, one to a compliance API, the second filled from the first. Then you will test it, keep a regression case, see what happens when an API has no answer, and run the same operation from the command line.
It takes about fifteen minutes and needs nothing but Reqlyn and its fixture APIs. Every step below was followed against the fixtures as written.
Before you start
Start the fixture APIs in a terminal and leave them running:
cargo run -p reqlyn-fixtures
They answer on http://127.0.0.1:8787. Then start the desktop (reqlyn-desktop, or cargo run -p reqlyn-desktop).
If you want to keep this apart from your own work, set REQLYN_DATA_DIR to an empty folder, and REQLYN_SECRET_SERVICE to a name of your own such as dev.reqlyn.tutorial, before starting it.
1. A variable for the API's address
An operation should not have an address written into it: the same operation will later run against another inventory. So the address goes in a variable.
- On Requests (the first icon of the rail), choose the Variables tab under the address.
- Press + Add variable. Name it
inventory, give it the valuehttp://127.0.0.1:8787, and press Save variables. The tab now reads "Variables 1".
2. Send a request
- In the address field, type
{{inventory}}/devices/4831. - Press Send (or Enter, or Ctrl Enter).
Under Response you see 200 OK, the time and the size, and the body:
{
"address": "10.24.10.11",
"hostname": "pe01.pitb02-pa",
"id": 4831,
"role": "PE",
"status": "active"
}
HISTORY in the sidebar lists the send, with the address as it went: 127.0.0.1:8787/devices/4831.
3. Save two requests
The device id should come from whoever runs the operation, so it becomes a placeholder too.
- Change the address to
{{inventory}}/devices/{{deviceId}}. Reqlyn says, in red, "No value is defined for {{deviceId}}": there is no such variable. That is fine; the operation will fill it. - Click "Name this request", type
Device, and press Save. It is listed under COLLECTIONS, and the state reads "Saved on this computer". - Press the + beside COLLECTIONS for a new request. Give it the address
{{inventory}}/compliance/devices/{{id}}/status, name itCompliance status, and save it.
4. Compose the operation
- Open Device from COLLECTIONS and press Use in an operation. Reqlyn opens Operations with a new operation: its first step sends Device, and it has one input,
deviceId, for the placeholder that is not a variable. - Choose the step. Under NAME, call it
device. Later steps refer to its response by this name. - Click the operation's name at the top and call it
Device overview. - Choose Inputs, and make
deviceIdan integer. Inputs are never converted: a run given"4831"is refused. - Press + Add step. Name the new step
compliance, and under SAVED REQUEST choose Compliance status. - Under FILLED FROM EARLIER STEPS, press + Add mapping: the placeholder
id, from the stepdevice, at the pathid. The compliance request will be sent with the device's own id. - Choose Output contract and press + Add field twice:
hostname, fromdevice, athostname, a string;compliant, fromcompliance, atcompliant, a boolean.
- Press Save. The state reads "Draft · revision 1 · saved on this computer".
The operation returns those two fields and nothing else, whatever the APIs send.
5. Test it
- Choose Test run. Replace the input with
{"deviceId": 4831}. - Press Test locally.
The output:
{
"hostname": "pe01.pitb02-pa",
"compliant": false
}
Under STEPS, each step "returned its result" with one request and its time. Try {"deviceId": 4832}: pe02.pitb02-pa, compliant true.
6. Keep a regression case
A case remembers a live run, the answers each step got and the output, so you can check later changes against it without calling any API.
- Test with
{"deviceId": 4831}again, then press Keep as case. - Name it
pe01and press Keep. "Kept as the case pe01." - Press Run cases. Under "CASES · NOTHING WAS SENT",
pe01holds, and the Test run part says "Its cases hold".
7. When an API has no answer
The compliance API knows only two of the four devices. Test with {"deviceId": 4840}: the run fails, "Step "compliance": the server answered 404, which is not success, so there is no output."
Say the host name is still worth having without the compliance status:
- Choose the
compliancestep. Under IF IT FAILS, choose The run goes on. - Choose Output contract, and tick May be null on
compliant. - Save.
Test 4840 again: the output is {"hostname": "cr01.pitb02-pa", "compliant": null}, and the run says it returned part of its output. The case still holds: pe01 did not change.
8. The same operation from the command line
The command line runs what the desktop saved, through the same engine. In a terminal (with the same REQLYN_DATA_DIR, if you set one):
reqlyn list
reqlyn run "Device overview" --input '{"deviceId": 4831}'
prints the output as JSON and ends with 0. Then:
reqlyn run "Device overview" --input '{"deviceId": 4840}'
prints the partial output, says which step it went on without, and ends with 3. A failure ends with 1, and an input it will not run with 2:
reqlyn run "Device overview" --input '{"deviceId": "4831"}'
Input: "deviceId" has to be an integer and was given a string. Nothing is converted for you.
Replay the case, sending nothing:
reqlyn test "Device overview"
passed pe01
1 of 1 cases hold.
And write a JUnit report of a run, a test case for each step and one for the output contract:
reqlyn run "Device overview" --input '{"deviceId": 4831}' --junit report.xml
What you did
- A variable kept the API's address out of the requests.
- An operation gave two saved requests a typed input and a declared output, and carried a value from one response into the next request.
- A test showed each step; a case kept the run to check against later; an optional step turned a failure into a partial result.
- The command line ran the same thing, with exit statuses a script can act on.
Choose Arazzo source to see what you built as an Arazzo document: that is the subject of the next tutorial.
Help for Reqlyn 0.5.1. All help topics