rqm show
rqm show
rqm show prints one requirement: what its file says, what that resolves to, how it relates to the others, where it is and what its hashes are.
rqm show <id-or-uuid>
The argument is the id, such as RQM-2, or the uuid of the requirement.
When a run record exists, show also says what the latest run proved about the requirement, on a line that starts with run:. It names the result (satisfied, incomplete, unknown or unsatisfied), the run, and whether the run saw the requirement as it is now (current) or before it was changed (superseded). --run <id> uses another run instead of the latest one. Run ids sort by start time, so the latest run is the one with the greatest id. See rqm test.
$ 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.
fields:
area: sessions
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.
What the output says
The first line is the id and the title. The block of key: value lines that follows is the requirement as rqm understands it:
priorityis the resolved priority, followed in brackets by where it came from: nothing when the requirement wrote it,inherited from RQM-1when an ancestor did, anddefaultwhen it is the default of the project. See Parents and inheritance.verificationlists the methods that verify the requirement.fileis the file of the requirement, relative to the project root.bytesandeffectiveare the two hashes. See Identity and hashes.
After that come the text, the acceptance criteria, the evidence if there is any, the tests (see Binding tests to requirements), the fields of the kind with their resolved values, the parent, the children, the requirements it links to, and the requirements that link to it. A part that a requirement does not have is left out.
Below the hashes show prints the verification state. presentation is the one label for the requirement, baseline is what the baseline says about it, and manual appears when the requirement lists a method other than test. The label is computed from the latest run and the baseline by the rules in Labels and manual evidence, and it can never be written into a requirement. When the label is one that a bare word would mislead about, such as verification_conflict, a sentence under it says what is behind it, for example when the baseline recorded the requirement as verified and what the latest run says now. Manual evidence is always marked as an assertion by the author, because rqm cannot check it.
A project with no baseline key has no baseline, and the line says disabled. A configured baseline that does not exist, and one that cannot be read, are errors of show (exit 2), and then every requirement presents unknown.
An unknown requirement
An id or a uuid that no requirement has, among the ones that could be read, is an error:
$ rqm show RQM-99
error[E-REQ-NOT-FOUND]: No requirement has the id or uuid RQM-99
[exit 2]
If you expected it to exist, run rqm check: a file with an error is not loaded, and so it cannot be shown.
Options
$ rqm show --help
Show one requirement with its resolved values, links and hashes
Usage: rqm show [OPTIONS] <REQUIREMENT>
Arguments:
<REQUIREMENT> The id (`RQM-12`) or the uuid of the requirement
Options:
--format <FORMAT> Output format. JSON is the stable contract [default: human] [possible values: human, json]
--run <ID> Take the run evaluation from this run instead of the latest one
--strict Treat warnings as errors for the exit code. The output itself does not change
-h, --help Print help
The data of --format json is described in The JSON output.