Skip to content

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.

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-username
gpr.key=ghp_your_token

See Installation for other ways to provide the credentials, for example in CI.

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.

Create src/test/resources/requirements.yaml with a small OpenAPI document:

openapi: 3.0.3
info:
title: Users
version: 1.0.0
paths:
/users:
get:
operationId: getUsers
responses:
'200':
description: The list of users
'404':
description: No users found

ReqCover 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.

Create src/test/resources/junit-platform.properties:

reqCover.requirementsUris=requirements.yaml
reqCover.minimumRequiredCoveragePercent=100

reqCover.requirementsUris is a classpath location, so the file must be on the test classpath.

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.ForRequirement
import org.junit.jupiter.api.Test
class UsersTest {
@Test
@ForRequirement("#getUsers/200")
fun `lists users`() {
// call your code and assert on the result
}
}
Terminal window
./gradlew test

All 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.

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=80

To see the coverage without failing the build, set reqCover.failIfBelowMinimum=false. All settings are listed in Configuration.