Core Concepts

Glossary

• Requirement - a piece of functionality that should be implemented in the system, identified by a string ID.
• Test case - a piece of code that tests a requirement.
• Coverage - the set of test cases that cover a requirement.
• Expected requirements - the full set of requirements loaded from your requirements source(s); what should be verified.
• Verified requirements - the set of requirement IDs actually asserted by passing tests via @ForRequirement.

@ForRequirement

@Repeatable
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.FUNCTION)
annotation class ForRequirement(val id: String)

Put it on a test method. It’s @Repeatable, so one test can verify several requirements. ReqCover only counts a requirement as verified if the annotated test passed - a failing or skipped test does not count toward coverage.

RequirementsCoverageTracker

The engine underneath everything is a small, dependency-free tracker (dev.reqcover.engine.RequirementsCoverageTracker):

tracker.expectAll(requirementIds)   // from your requirements source
tracker.verified(requirementId)     // from a passing @ForRequirement test

tracker.expectedRequirements()      // what should be covered
tracker.verifiedRequirements()      // what was actually verified
tracker.coveredRequirements()       // expected ∩ verified
tracker.unverifiedRequirements()    // expected − verified: gaps in coverage
tracker.unexpectedRequirements()    // verified − expected: tests referencing IDs your source doesn't define

unexpectedRequirements matters in practice - it catches typos in a requirement ID, or a test still referencing a requirement that was since removed from the spec.

How a test run actually gets tracked

RequirementsCoverageListener (in reqcover-junit-jupiter) implements JUnit Platform’s TestExecutionListener and is registered automatically via ServiceLoader - see Getting Started. Over the course of a run it:

1. testPlanExecutionStarted - reads reqCover.requirementsUris from JUnit Platform configuration parameters and loads every listed source into the tracker via expectAll.
2. executionFinished - for each test that finishes successfully, reads its @ForRequirement annotations (via reflection on the resolved MethodSource) and marks each ID as verified.
3. testPlanExecutionFinished - computes coverage, logs a summary, compares it against reqCover.minimumRequiredCoveragePercent, optionally fails the build, then hands the tracker to every registered reporter.

See Configuration Reference for every property RequirementsCoverageListener reads, and Requirements Sources / Reporters for how to plug in your own.