Getting Started
In this tutorial you add ReqCover to a JUnit project built with Gradle, watch the coverage gate fail, and then make it pass.
You need a Gradle project with JUnit 5 or 6 tests and a GitHub account. Using TestNG, Cucumber or Maven instead? Read the TestNG, Cucumber or Maven guide after this one; the steps are the same, only the wiring differs.
1. Give Gradle access to GitHub Packages
Section titled “1. Give Gradle access to GitHub Packages”ReqCover is published to GitHub Packages, which requires a login even for public packages.
Create a GitHub personal access token (classic) with the read:packages scope, then add it to ~/.gradle/gradle.properties:
gpr.user=your-github-usernamegpr.key=ghp_your_tokenSee Installation for other ways to provide the credentials, for example in CI.
2. Add the dependencies
Section titled “2. Add the dependencies”In build.gradle.kts:
repositories { mavenCentral() maven("https://maven.pkg.github.com/reqcover/reqcover") { credentials { username = providers.gradleProperty("gpr.user").orNull ?: System.getenv("GITHUB_ACTOR") password = providers.gradleProperty("gpr.key").orNull ?: System.getenv("GITHUB_TOKEN") } }}
dependencies { testImplementation("dev.reqcover:reqcover-engine-junit-jupiter:0.0.12") testImplementation("dev.reqcover:reqcover-source-openapi:0.0.12") testImplementation("dev.reqcover:reqcover-reporter-html:0.0.12") testImplementation("dev.reqcover:reqcover-reporter-xml:0.0.12")}
tasks.test { useJUnitPlatform()}The engine registers itself with the JUnit Platform; you do not need to add a listener anywhere.
3. Write the requirements
Section titled “3. Write the requirements”Create src/test/resources/requirements.yaml with a small OpenAPI document:
openapi: 3.0.3info: title: Users version: 1.0.0paths: /users: get: operationId: getUsers responses: '200': description: The list of users '404': description: No users foundReqCover turns every response of every operation into a requirement.
This file contains two: #getUsers/200 and #getUsers/404.
The ID scheme is explained in Core Concepts.
4. Configure the coverage gate
Section titled “4. Configure the coverage gate”Create src/test/resources/junit-platform.properties:
reqCover.requirementsUris=requirements.yamlreqCover.minimumRequiredCoveragePercent=100reqCover.requirementsUris is a classpath location, so the file must be on the test classpath.
5. Link a test to a requirement
Section titled “5. Link a test to a requirement”Annotate a test with @ForRequirement.
Java:
import dev.reqcover.api.ForRequirement;import org.junit.jupiter.api.Test;
class UsersTest { @Test @ForRequirement(id = "#getUsers/200") void listsUsers() { // call your code and assert on the result }}Kotlin:
import dev.reqcover.api.ForRequirementimport org.junit.jupiter.api.Test
class UsersTest { @Test @ForRequirement("#getUsers/200") fun `lists users`() { // call your code and assert on the result }}6. Run the tests and watch the gate fail
Section titled “6. Run the tests and watch the gate fail”./gradlew testAll tests pass, but the build fails. The log shows why:
WARNING: The following requirements were not covered by any test: [#getUsers/404]INFO: Requirements coverage: 1 out of 2 = 50.0%SEVERE: Requirements coverage is below the minimum required coverage of 100.0%. Actual coverage: 50.0%SEVERE: Exiting with error code 1 due to insufficient requirements coverage.The exact prefixes depend on your logging setup.
The reports are written before the build fails, so open build/reports/tests/reqcover/requirements-coverage.html to see which requirement is missing.
An XML version is in requirements-coverage.xml next to it.
7. Cover the missing requirement
Section titled “7. Cover the missing requirement”Add a test for the second requirement:
@Test@ForRequirement(id = "#getUsers/404")void reportsMissingUsers() { // ...}Run ./gradlew test again. The log now says:
INFO: All requirements are covered by tests.INFO: Requirements coverage: 2 out of 2 = 100.0%INFO: Requirements coverage meets the minimum required coverage of 100.0%. Actual coverage: 100.0%Only passing tests count. If reportsMissingUsers fails, #getUsers/404 is not covered and the gate fails again.
8. Choose a minimum that fits your project
Section titled “8. Choose a minimum that fits your project”In an existing project, start with a minimum you already meet and raise it as you add tests:
reqCover.minimumRequiredCoveragePercent=80To see the coverage without failing the build, set reqCover.failIfBelowMinimum=false.
All settings are listed in Configuration.
Next steps
Section titled “Next steps”- Core Concepts: requirements, coverage and the gate in detail
- JUnit guide: parameterized tests, class-level annotations, system properties
- TestNG guide, Cucumber guide, Maven guide
- Requirement sources and Reporters