The configuration file
The configuration file
A project is a directory with a file called rqm.yaml in it. rqm init writes it, and this page explains every part of what it writes. The file is YAML, and rqm reads it strictly: a key that rqm does not know is an error that names the key, so a typo cannot silently turn a setting off.
This is what rqm init --default-kind functional writes in a cargo project:
$ rqm init --default-kind functional --no-gitignore
created rqm.yaml (cargo project)
.gitignore left alone (--no-gitignore)
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
$ cat rqm.yaml
# rqm configuration. See docs/ for what every key means.
schema: 1
default_kind: "functional"
# Directories that hold one requirement per file.
requirement_roots: ["requirements/"]
# The prefixes of requirement ids, such as CORE-1 or COMP-2. RQM when absent.
# id_prefixes: ["RQM"]
defaults:
priority: "should"
# Where the baseline is kept, once you have promoted one.
# baseline: ".rqm/baseline.yaml"
verification:
min_cases: 1
require_suites: ["unit"]
# The suite runs nextest. The report is written by the "ci" profile of
# .config/nextest.toml, which needs these two lines:
# [profile.ci.junit]
# path = "junit.xml"
suites:
- id: "unit"
cmd: ["cargo", "nextest", "run", "--profile", "ci", "--no-fail-fast"]
report: "target/nextest/ci/junit.xml"
format: "junit"
adapter: "nextest"
execution: "mandatory"
kinds:
functional: {}
The keys
schema is the version of the file format. It is 1, and a file with another number is refused with E-SCHEMA-VERSION, so that a newer file is never half understood by an older rqm.
default_kind is the kind that rqm create uses when you do not pass --kind. It must be one of the kinds declared in kinds.
requirement_roots lists the directories that hold requirement files. They are relative to the project root. rqm looks in each of them and in the directories below it, and reads every file whose name ends in .yaml. The name of the file does not matter, but rqm create names its files RQM-<n>.yaml, and it writes into the first root. A root that does not exist is a warning (W-ROOT-MISSING), because a project that has just been initialized has no requirements yet.
id_prefixes lists the uppercase prefixes that requirement ids may have, such as CORE or COMP in CORE-1 or COMP-2. Each requirement’s id is a prefix, a hyphen and a number without leading zeros. The id_prefixes key is optional and defaults to ["RQM"] when absent. A requirement whose id has a prefix that is not declared is an error (E-ID-PREFIX) and is left out of the snapshot. id_prefixes is not part of the policy fingerprint, because ids are not normative.
defaults holds values that a requirement gets when neither it nor any of its ancestors writes one. Today it holds priority. See Parents and inheritance.
baseline is where rqm keeps the accepted state of the verification of each requirement. It is commented out in a new project, which then has no baseline. See The baseline file and Running rqm in CI.
verification says how much evidence a requirement needs. min_cases is the number of test cases that must count for a requirement, and require_suites names the suites that every requirement depends on. A suite named here must be declared in suites, or the configuration is refused with E-SUITE-UNKNOWN.
suites declares the commands that run tests and the reports they write. A suite has an id, the command cmd (a program and its arguments, never run through a shell), the report it writes, the report format (junit), the adapter that understands the report (nextest, pytest or generic), and execution, which is mandatory or optional and decides whether a suite that did not run well fails a run. rqm test runs them. See Running suites.
kinds declares the kinds of requirement and the fields each kind has. It is the subject of Kinds and fields.
There are two more sections, join and limits. They tune how test reports are matched to requirements and how large untrusted input can be. Their defaults are meant to be right, and they matter when suites run. Running suites and Reading test reports say what they do.
A project that is not a cargo project
Without a Cargo.toml, init cannot know how you run your tests, and it does not guess. It declares a suite that cannot work until you replace its command, and it says so in a comment in the file. The suite is optional and require_suites is empty, so rqm check has nothing to complain about right after init:
$ rqm init --default-kind constraint
created rqm.yaml (generic project)
created .gitignore with .rqm/
next:
- replace the placeholder command of the suite in rqm.yaml with your own test command
- rqm create --title "..." to write the first requirement
- rqm check
$ 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
Finding the file
Every command looks for rqm.yaml in the working directory and then in each directory above it, up to the root of the git repository. The directory that holds the file is the project root, and the paths in every output are relative to it.