Skip to content

Requirements sources

A requirements source turns a file named in reqCover.requirementsUris into a set of requirement IDs; ReqCover ships one for OpenAPI.

Module: dev.reqcover:reqcover-source-openapi (Maven: reqcover-source-openapi-jvm). Class: dev.reqcover.source.openapi.OpenApiRequirementsSource. It registers itself through ServiceLoader; adding it to the test classpath is enough.

build.gradle.kts
dependencies {
testImplementation("dev.reqcover:reqcover-source-openapi:0.0.12")
}
pom.xml
<dependency>
<groupId>dev.reqcover</groupId>
<artifactId>reqcover-source-openapi-jvm</artifactId>
<version>0.0.12</version>
<scope>test</scope>
</dependency>

The file is read with a YAML parser, so YAML and JSON OpenAPI documents both work.

For every operation under paths:

The operation has Requirement IDs
no responses (or an empty map) #<operationId>
responses, none with x-requirements #<operationId>/<responseCode> for each response
a response with an x-requirements map #<operationId>/<responseCode>/<key> for each key of the map, instead of #<operationId>/<responseCode>

Operations without operationId are skipped with Warning: Operation ID not found for path '<path>' and method '<method>'. printed to standard output. Path-level keys that are not operations, such as parameters, summary or servers, print the same warning.

src/test/resources/requirements.yaml
openapi: 3.0.0
info:
title: Users API
version: 1.0.0
paths:
/users:
get:
operationId: getUsers
responses:
'200':
description: List of users
post:
operationId: createUser
responses:
'201':
description: Created
'400':
description: Invalid user
/users/{id}:
delete:
operationId: deleteUser
/actuator/health:
get:
operationId: getHealth
responses:
'200':
description: OK
'500':
description: Service outage
x-requirements:
database: If the database is down, the service is unavailable.
downstream: If the downstream service is down, the service is unavailable.

Resulting requirement IDs:

ID Reason
#getUsers/200 response code
#createUser/201 response code
#createUser/400 response code
#deleteUser no responses
#getHealth/200 response code
#getHealth/500/database x-requirements key
#getHealth/500/downstream x-requirements key

The values of x-requirements are descriptions for humans; only the keys become IDs. Link tests to these IDs with @ForRequirement(id = "#getUsers/200") (Java), @ForRequirement("#getUsers/200") (Kotlin) or the Cucumber tag @req:#getUsers/200. See Core concepts.

Situation Message Result
File not on the classpath Requirements file not found at URI: <uri> Error, the build fails
Malformed YAML, empty file, or a document without paths Unsupported format for requirements file at URI: <uri> Error, the build fails
paths: {} or no operation with an operationId Requirements file at URI: <uri> contains no requirements. Warning; the file adds no requirements

Errors are reported before any test runs (with TestNG: before the tests of the suite that lists the file). The log line continues with a hint where to check the setting, for example Check the reqCover.requirementsUris configuration parameter. (JUnit). See Troubleshooting.

List several locations, separated by commas. The requirements of all files are combined into one set; IDs that appear in more than one file count once.

reqCover.requirementsUris=api/users.yaml, api/orders.yaml

Every file is loaded even if an earlier one fails, so the log shows all problems at once; the build then fails if any file failed.

Locations are classpath resource names, resolved with the class loader that loaded the requirements source:

  • src/test/resources/requirements.yaml is requirements.yaml.
  • src/test/resources/api/users.yaml is api/users.yaml.
  • Do not use a leading /, a classpath: prefix or a file system path.
  • If several classpath entries contain the same resource name (for example a shared JAR and your test resources), the requirements of all of them are combined.

Implement the SPI in dev.reqcover.engine.spi from the reqcover-engine module.

package dev.reqcover.engine.spi
interface RequirementsSource {
fun load(uri: String): Set<String>
}
interface JvmRequirementsSource : RequirementsSource {
override fun load(uri: String): Set<String> // finds all classpath resources named uri
fun load(inputStream: InputStream): Set<String>
}

On the JVM, implement JvmRequirementsSource: its default load(uri) finds every classpath resource with that name, throws NotFound if there is none, calls load(inputStream) for each and combines the results. You only parse the stream.

src/main/kotlin/com/example/PlainListRequirementsSource.kt
package com.example
import dev.reqcover.engine.UnsupportedFormat
import dev.reqcover.engine.spi.JvmRequirementsSource
import java.io.InputStream
class PlainListRequirementsSource : JvmRequirementsSource {
override fun load(uri: String): Set<String> {
if (!uri.endsWith(".txt")) throw UnsupportedFormat(uri)
return super.load(uri)
}
override fun load(inputStream: InputStream): Set<String> =
inputStream.bufferedReader().readLines()
.map { it.trim() }
.filter { it.isNotEmpty() && !it.startsWith("#") }
.toSet()
}

Register it for ServiceLoader:

src/main/resources/META-INF/services/dev.reqcover.engine.spi.RequirementsSource
com.example.PlainListRequirementsSource

For each URI, ReqCover asks every registered source in turn:

The source ReqCover
returns a set uses it and stops asking
throws dev.reqcover.engine.UnsupportedFormat tries the next source
throws dev.reqcover.engine.NotFound remembers it and tries the next source
throws any other exception reports Could not load requirements file at URI: <uri> (<exception>), the build fails

If no source returns a set, ReqCover reports NotFound if any source reported it, otherwise UnsupportedFormat. If no source is registered at all, every URI fails as UnsupportedFormat.