Requirements sources
A requirements source turns a file named in reqCover.requirementsUris into a set of requirement IDs; ReqCover ships one for OpenAPI.
OpenAPI source
Section titled “OpenAPI source”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.
dependencies { testImplementation("dev.reqcover:reqcover-source-openapi:0.0.12")}<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.
How IDs are derived
Section titled “How IDs are derived”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.
Example
Section titled “Example”openapi: 3.0.0info: title: Users API version: 1.0.0paths: /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.
Errors and warnings
Section titled “Errors and warnings”| 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.
Multiple files
Section titled “Multiple files”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.yamlEvery 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.
Classpath locations
Section titled “Classpath locations”Locations are classpath resource names, resolved with the class loader that loaded the requirements source:
src/test/resources/requirements.yamlisrequirements.yaml.src/test/resources/api/users.yamlisapi/users.yaml.- Do not use a leading
/, aclasspath: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.
Writing your own source
Section titled “Writing your own source”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.
package com.example
import dev.reqcover.engine.UnsupportedFormatimport dev.reqcover.engine.spi.JvmRequirementsSourceimport 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:
com.example.PlainListRequirementsSourceHow ReqCover picks a source
Section titled “How ReqCover picks a source”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.
Next steps
Section titled “Next steps”- Configuration: the
reqCover.requirementsUrissetting. - Reporters: what happens with the IDs after the run.
- Troubleshooting: requirements file errors.