You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+14-13Lines changed: 14 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -37,12 +37,12 @@ because at best, only leaf requirements (those without children) must be traced
37
37
8. Repeat from step 2 until the project is complete
38
38
39
39
For a quick overview of those steps, see the [getting-started section](#getting-started) below.
40
-
More details about using and configuring *mantra* may be found in the [/docs/usage](docs/usage/README.md) folder.
40
+
More details about using and configuring *mantra* may be found in the `/docs/usage` folder.
41
41
The goals, requirements, and decisions behind *mantra* are documented under `/docs/wiki`, which is also published on *mantra*'s [GitHub wiki](https://github.com/mhatzl/mantra/wiki).
42
42
43
43
**Note:** Currently, focus is on support for Rust code, but built-in support for other languages is planned.
44
44
If your language is not supported directly, you may create your own tooling that extracts relevant information
45
-
and converts it into a format *mantra* understands following *mantra*'s [JSON schemas](schema-gen/README.md).
45
+
and converts it into a format *mantra* understands following *mantra*'s JSON schemas available at `schema-gen/generated`.
46
46
47
47
## Installation
48
48
@@ -63,7 +63,7 @@ cargo install --locked mantra
63
63
## Usage
64
64
65
65
This section provides a high-level overview to get you started using *mantra*.
66
-
For more details, take a look at the [/docs/usage](docs/usage/README.md) folder.
66
+
For more details, take a look at the `/docs/usage` folder.
67
67
68
68
In order to use *mantra* for Rust projects, you typically want the following prerequisites installed:
69
69
@@ -113,17 +113,17 @@ products: [{
113
113
```
114
114
115
115
Based on this configuration, files defining requirements are expected to be located under the `reqs/` folder
116
-
following the [RequirementSchema](schema-gen/generated/collect/RequirementSchema.json).
116
+
following the `RequirementSchema`.
117
117
Annotations such as requirement traces are extracted from Rust code files located in the repository.
118
118
Test and code coverage results are expected under `target/nextest/default`, with test results following the [JUnit XML](https://llg.cubic.org/docs/junit/) format and code coverage being represented in the [Cobertura Loose XML](https://github.com/cobertura/cobertura/blob/master/cobertura/src/site/htdocs/xml/coverage-loose.dtd) format.
119
119
Files containing manual reviews are expected to be located under the `reviews/` folder
120
-
following the [ReviewSchema](schema-gen/generated/collect/ReviewSchema.json).
120
+
following the `ReviewSchema`.
121
121
122
-
More details related to *mantra*'s configuration file can be found under [/docs/usage/configuration](docs/usage/configuration.md).
122
+
More details related to *mantra*'s configuration file can be found under `/docs/usage/configuration.md`.
123
123
124
124
### Defining Requirements
125
125
126
-
Currently, only the [RequirementSchema](schema-gen/generated/collect/RequirementSchema.json) is supported as input for requirement definitions.
126
+
Currently, only the `RequirementSchema` is supported as input for requirement definitions.
127
127
128
128
The following configuration defines three requirements `gs-req-1`, `gs-req-2`, and `gs-req-1.sub-1`:
129
129
@@ -170,12 +170,12 @@ even if `gs-req-1.sub-1` is `unverified` or `skipped`.
170
170
171
171
### Tracing Requirements in Code
172
172
173
-
Currently, *mantra* is only able to detect traces in Rust code that match the macros defined in the [mantra-macros](langs/rust/mantra-macros) crate.
173
+
Currently, *mantra* is only able to detect traces in Rust code that match the macros defined in the [mantra-macros](https://crates.io/crates/mantra-macros) crate.
174
174
Note that it is not required to use this crate, because trace detection is only based on macro names.
175
175
For other languages and file formats, external tools may convert extracted data into the
If you want to use the macros from [mantra-macros](langs/rust/mantra-macros/README.md),
178
+
If you want to use the macros from [mantra-macros](https://crates.io/crates/mantra-macros),
179
179
add it to your Cargo.toml via
180
180
181
181
```sh
@@ -217,8 +217,9 @@ The benefit is that combining traces with line coverage allows users to choose b
217
217
For example, if a `verifies` trace is set on a test and there is a code part with a `satisfies` trace to the same requirement, *mantra* checks if the test actually passed this code part.
218
218
219
219
For Rust projects, a convenient way to get test and coverage results that are readable by *mantra*
220
-
is to use [cargo-nextest](https://nexte.st/) with the JUnit feature and [grcov](https://github.com/mozilla/grcov/) with the Cobertura output format. See the `testcov` task in the [justfile](justfile) of the repository to see how this is set up for *mantra*.
221
-
This convenience layer is internally converted to the [TestRunSchema](schema-gen/generated/collect/TestRunSchema.json), which external tools may target directly.
220
+
is to use [cargo-nextest](https://nexte.st/) with the JUnit feature and [grcov](https://github.com/mozilla/grcov/) with the Cobertura output format.
221
+
See the `testcov` task in the `justfile` of the repository to see how this is set up for *mantra*.
222
+
This convenience layer is internally converted to the `TestRunSchema`, which external tools may target directly.
222
223
223
224
**Note:** Code coverage for Rust projects collected via `-Cinstrument-coverage` is only collected per binary.
224
225
Consequently, it is not possible to get code coverage results per test case, which worsens the safety guarantees
@@ -232,7 +233,7 @@ to explicitly state that this requirement must be verified manually in a review.
232
233
Besides verifying requirements, reviews may also be used to overwrite test results,
233
234
which is for example useful in case of flaky tests.
234
235
235
-
Currently, can only be added following the [ReviewSchema](schema-gen/generated/collect/ReviewSchema.json).
236
+
Currently, reviews can only be added following the `ReviewSchema`.
236
237
External tools may be used to extract data from other formats and convert to the schema.
237
238
238
239
The review below verifies the manual requirement `gs-req-2`:
0 commit comments