Reporters
Reporters write the result of a coverage run to files; ReqCover ships an HTML and an XML reporter, and you can add your own.
Overview
Section titled “Overview”| Module | Maven artifact | Class | File |
|---|---|---|---|
reqcover-reporter-html |
reqcover-reporter-html-jvm |
dev.reqcover.reporter.html.HtmlRequirementsCoverageReporter |
requirements-coverage.html |
reqcover-reporter-xml |
reqcover-reporter-xml-jvm |
dev.reqcover.reporter.xml.XmlRequirementsCoverageReporter |
requirements-coverage.xml |
Both register themselves through ServiceLoader. Every reporter on the test classpath runs; add one, both or none.
dependencies { testImplementation("dev.reqcover:reqcover-reporter-html:0.0.12") testImplementation("dev.reqcover:reqcover-reporter-xml:0.0.12")}<dependency> <groupId>dev.reqcover</groupId> <artifactId>reqcover-reporter-html-jvm</artifactId> <version>0.0.12</version> <scope>test</scope></dependency><dependency> <groupId>dev.reqcover</groupId> <artifactId>reqcover-reporter-xml-jvm</artifactId> <version>0.0.12</version> <scope>test</scope></dependency>If no reporter is on the classpath, ReqCover prints this to standard error and continues:
No reporter configured. Please add a RequirementsCoverageReporter implementation to the classpath.Location
Section titled “Location”Reports are written to reqCover.reportsDir, default build/reports/tests/reqcover, relative to the working directory of the test JVM. The directory is created if needed; existing report files are overwritten.
When reports are written
Section titled “When reports are written”At the end of the test run, after the coverage summary is logged and before the build is failed for insufficient coverage. A run that fails because coverage is below the minimum still leaves complete reports behind.
If a requirements file cannot be loaded, the build fails at the start of the run and no report is written.
HTML report
Section titled “HTML report”requirements-coverage.html is an XHTML page titled “Requirements Coverage Report” with one table:
| Requirement ID | Test |
|---|---|
| each expected requirement | Covered or - (Not Covered) |
| each unexpected requirement | Unexpected |
An unexpected requirement is an ID used by a passing test (or Cucumber tag) that is not in any requirements file, usually a typo.
XML report
Section titled “XML report”requirements-coverage.xml is meant for CI tools and scripts. Structure (shown pretty-printed; the file itself starts with an <?xml ...?> declaration and has no indentation):
<requirements-coverage total="2" covered="1" coverage="50.0"> <expected> <requirement id="REQ-1" covered="true"/> <requirement id="REQ-2" covered="false"/> </expected> <unexpected> <requirement id="REQ-3"/> </unexpected></requirements-coverage>| Element / attribute | Meaning |
|---|---|
requirements-coverage/@total |
Number of expected requirements |
requirements-coverage/@covered |
Number of expected requirements covered by a passing test |
requirements-coverage/@coverage |
Coverage in percent, one decimal, always with a dot (50.0; before 0.0.12 it followed the JVM’s default locale, for example 50,0 on a German locale); 100.0 when there are no expected requirements |
expected/requirement |
One per expected requirement, with id and covered (true or false) |
unexpected/requirement |
One per ID covered by a passing test but not defined in a requirements file |
Empty lists are written as <expected/> and <unexpected/>. The order of requirement elements is not specified.
Writing your own reporter
Section titled “Writing your own reporter”Implement dev.reqcover.engine.spi.RequirementsCoverageReporter from reqcover-engine:
package dev.reqcover.engine.spi
interface RequirementsCoverageReporter { fun report(tracker: RequirementsCoverageTracker)
fun report(tracker: RequirementsCoverageTracker, reportsDirectory: String) = report(tracker)}ReqCover calls report(tracker, reportsDirectory) with the configured reqCover.reportsDir. The default implementation calls report(tracker), so reporters written before 0.0.11 keep working. Override the two-argument method to honour reqCover.reportsDir.
RequirementsCoverageTracker (dev.reqcover.engine) provides sets of IDs: expectedRequirements(), verifiedRequirements(), coveredRequirements(), unverifiedRequirements() and unexpectedRequirements(), plus isVerified(id) and isExpected(id).
package com.example
import dev.reqcover.engine.RequirementsCoverageTrackerimport dev.reqcover.engine.spi.RequirementsCoverageReporterimport java.nio.file.Filesimport java.nio.file.Path
class CsvRequirementsCoverageReporter : RequirementsCoverageReporter { override fun report(tracker: RequirementsCoverageTracker) = report(tracker, "build/reports/tests/reqcover")
override fun report(tracker: RequirementsCoverageTracker, reportsDirectory: String) { val directory = Files.createDirectories(Path.of(reportsDirectory)) val lines = listOf("id,covered") + tracker.expectedRequirements().sorted().map { "$it,${tracker.isVerified(it)}" } Files.write(directory.resolve("requirements-coverage.csv"), lines) }}Register it:
com.example.CsvRequirementsCoverageReporterNext steps
Section titled “Next steps”- Configuration:
reqCover.reportsDir. - Requirements sources: where expected requirements come from.
- Troubleshooting: missing reports and reports in the wrong directory.