Getting Started

ReqCover links test cases to requirements and reports coverage - which requirements are verified, which aren’t, and which tests verify something that was never a defined requirement in the first place. It runs as a JUnit Platform TestExecutionListener, so it works with any JVM language that runs its tests through JUnit 5 Jupiter: Java, Kotlin, Scala, or Groovy.

The idea

• A requirement is a piece of functionality that should be implemented in the system.
• A test case verifies one or more requirements by annotating itself with @ForRequirement.
• A requirements source supplies the full set of requirements you expect to be covered - today that’s an OpenAPI document, but the source is pluggable.
• ReqCover compares what’s expected against what’s verified and reports the difference.

1. Add the dependency

build.gradle.kts

dependencies {
    testRuntimeOnly("dev.reqcover:reqcover-junit-jupiter:0.0.9")
    testRuntimeOnly("dev.reqcover:reqcover-reporter-html:0.0.9")
}

That’s it - no listener registration. reqcover-junit-jupiter ships a META-INF/services entry for org.junit.platform.launcher.TestExecutionListener, so the JUnit Platform Launcher (which Gradle’s test task and Maven Surefire both use) picks it up automatically.

2. Annotate a test

import dev.reqcover.api.ForRequirement;
import org.junit.jupiter.api.Test;

class HealthCheckTest {
    @Test
    @ForRequirement("#getHealth/500/downstream")
    void returnsFailWhenDownstreamIsUnavailable() {
        // ...
    }
}

@ForRequirement is @Repeatable - annotate a test multiple times if it verifies several requirements.

3. Point ReqCover at your requirements

Add a junit-platform.properties file to your test resources:

reqCover.requirementsUris=openapi/api.yaml

The value is a comma-separated list of classpath resource paths, resolved through the same RequirementsSource SPI that generates the requirement IDs your @ForRequirement annotations reference - see Requirements Sources for the ID format each source produces.

4. Run your tests

./gradlew test

ReqCover logs a summary at the end of the run and writes a report (see Reporters):

All requirements are covered by tests.
Requirements coverage: 2 out of 2 = 100.0%

If coverage is below the threshold you configure - see reqCover.minimumRequiredCoveragePercent - the build fails.

Next: Installation for the full module list, or Core Concepts for how the tracker, sources, and reporters fit together.