Tutorial
Tutorial
In this tutorial you give a small Rust project a set of requirements, check them, and tie a test to one of them. It takes about fifteen minutes. You need rqm on your PATH, and you need git and cargo, though neither is run by rqm itself.
The project is a library called sessions that signs users in. It was made with cargo new sessions --lib, and it has a function sign_in and two tests, sessions::tests::sign_in_with_a_valid_password and sessions::tests::sign_in_with_a_wrong_password.
$ cargo new sessions --lib
$ cd sessions
$ git init
Every command below is run in the root directory of the project, and every output shown is what rqm prints.
Set the project up
rqm init creates the configuration. The one thing it asks is the kind of requirement that you will write most, called the default kind. We will write functional requirements:
$ rqm init --default-kind functional
created rqm.yaml (cargo project)
created .gitignore with .rqm/
next:
- cargo add --dev rqm-attr
- add to .config/nextest.toml, so that nextest writes the report rqm reads:
[profile.ci.junit]
path = "junit.xml"
- rqm create --title "..." to write the first requirement
- rqm check
rqm saw the Cargo.toml and wrote a configuration for a cargo project. It also added .rqm/ to your .gitignore, because that directory holds files that belong to your machine. Commit rqm.yaml, and do not commit .rqm/. The suggested next steps are about running tests, which you will not need until the requirements are bound, so you can ignore the first two for now. The configuration file explains everything in rqm.yaml.
Now check the project, to see what a project with no requirements looks like:
$ rqm check
checked 0 requirements (loaded 0 of 0 discovered requirement files)
warning[W-ROOT-MISSING]: The requirement root 'requirements' does not exist, so it holds no requirements
--> requirements:1:1
It is only a warning. rqm.yaml says that requirements are in the directory requirements/, and there is no such directory yet. The next step creates it.
Write the first requirement
$ rqm create --title "Users can sign in" --text "A user who gives a valid name and password gets a session." --acceptance "A valid name and password give a session." --acceptance "A wrong password gives an error and no session."
created RQM-1 in requirements/RQM-1.yaml
uuid: <uuid>
it is a draft: replace the TODO placeholders, then run rqm check
warning[W-ROOT-MISSING]: The requirement root 'requirements' does not exist, so it holds no requirements
--> requirements:1:1
The warning is the same one. create looked at the project before it wrote the file, and at that moment the directory was missing. Now it exists. The requirement has the id RQM-1, and a uuid that identifies it for good. This is the file:
$ cat requirements/RQM-1.yaml
schema: 1
uuid: <uuid>
id: RQM-1
kind: functional
title: Users can sign in
text: A user who gives a valid name and password gets a session.
acceptance:
- A valid name and password give a session.
- A wrong password gives an error and no session.
verification:
- test
status: draft
A requirement is a short piece of YAML. It has a title, the text that says what must be true, and acceptance criteria that say how you would know. verification: [test] says that tests verify it. The status is draft: it is a proposal until someone decides otherwise. The requirement file describes every key.
Open the file in your editor and make two changes: we agree with this requirement, so its status becomes approved, and it is important, so it gets the priority must.
$ rqm list
ID KIND STATUS PRIORITY TITLE
RQM-1 functional approved must Users can sign in
1 of 1 requirements shown
A second requirement, below the first
Sessions expire. That is a detail of signing in, so we write it as a requirement that refines the first:
$ rqm create --title "Sessions expire" --text "A session ends a fixed time after it was granted." --acceptance "A session that is 30 minutes old is refused."
created RQM-2 in requirements/RQM-2.yaml
uuid: <uuid>
it is a draft: replace the TODO placeholders, then run rqm check
Edit the new file in the same way, and give it a parent, which is the requirement it refines:
$ rqm show RQM-2
RQM-2 Sessions expire
uuid: <uuid>
kind: functional
status: approved
priority: must (inherited from RQM-1)
verification: test
file: requirements/RQM-2.yaml
bytes: <hash>
effective: <hash>
presentation: unverified
baseline: disabled
text:
A session ends a fixed time after it was granted.
acceptance:
- A session that is 30 minutes old is refused.
parent: RQM-1 Users can sign in
note: rqm shows that the evidence meets the declared policy. It does not show that the tests are adequate.
RQM-2 did not write a priority, and show tells you where it got must from: its parent. If you change the priority of RQM-1, every requirement below it follows. Parents and inheritance has the rules.
Let rqm find your mistakes
Mistakes are normal, and the point of rqm check is to find them. Make a typo in the status of RQM-2, aproved for approved:
$ rqm check
checked 1 requirements (loaded 1 of 2 discovered requirement files)
error[E-FIELD-VALUE]: The field 'status' must be one of draft, approved, required, deprecated, rejected, found 'aproved'
--> requirements/RQM-2.yaml:11:9
[exit 2]
rqm found the file, read it, and refused it, and the message tells you the file, the line and the column, and what the values can be. It loaded one requirement out of two, so for now rqm list and rqm show do not know about RQM-2. Fix the typo:
$ rqm check
checked 2 requirements (loaded 2 of 2 discovered requirement files)
Everything is fine again. The exit code of rqm check is 0 when it is, and 2 when it is not, which is all that a script needs to know.
Tie a test to a requirement
The requirement says that users can sign in, and the project has tests that show it. Tell rqm which ones, with the tests key in requirements/RQM-1.yaml. A test is named the way cargo test prints it:
$ rqm show RQM-1
RQM-1 Users can sign in
uuid: <uuid>
kind: functional
status: approved
priority: must
verification: test
file: requirements/RQM-1.yaml
bytes: <hash>
effective: <hash>
presentation: unverified
baseline: disabled
text:
A user who gives a valid name and password gets a session.
acceptance:
- A valid name and password give a session.
- A wrong password gives an error and no session.
tests:
- sessions::tests::sign_in_with_a_valid_password
- sessions::tests::sign_in_with_a_wrong_password
children:
- RQM-2 Sessions expire
note: rqm shows that the evidence meets the declared policy. It does not show that the tests are adequate.
rqm does not run the tests yet, and it does not look for them in your code yet. What it does today is hold a requirement to its status. Make RQM-2 required, which says that it must be verified, and it has no test:
$ rqm check
checked 2 requirements (loaded 2 of 2 discovered requirement files)
error[E-REQUIRED-UNBOUND]: The requirement RQM-2 is required and verified by test, but no test is bound to it
--> requirements/RQM-2.yaml:3:5
[exit 2]
A required requirement cannot go without a test. Write the test, add its name to RQM-2, and the check passes:
$ rqm check
checked 2 requirements (loaded 2 of 2 discovered requirement files)
Binding tests to requirements says what else there is to know, and what rqm cannot do yet.
Use it in a script
Every command prints JSON when you ask for it. The format is stable, so you can rely on it in a script or a continuous integration job:
$ rqm --format json check
{
"schema": 1,
"command": "check",
"ok": true,
"data": {
"files": {
"discovered": 2,
"loaded": 2,
"read": 2
},
"requirements": 2
},
"diagnostics": [],
"truncated": false
}
The usual way is to run rqm check --strict in your build and stop when it exits with something other than 0.
Where to go next
- The command line describes what every command does and prints.
- The file formats describe
rqm.yamland the requirement file in full. - Diagnostic codes lists every error and warning, with what to do about it.