Requirements Sources

A requirements source turns a URI into a Set<String> of requirement IDs - the set ReqCover expects your tests to cover. ReqCover ships one source; you can add your own.

The SPI

interface RequirementsSource {
    fun load(uri: String): Set<String>
}

On the JVM, most sources will want to load from the classpath rather than parse a raw URI themselves - JvmRequirementsSource handles that:

interface JvmRequirementsSource : RequirementsSource {
    override fun load(uri: String): Set<String> {
        // resolves `uri` as a classpath resource (or resources, if duplicated across jars)
        // and delegates to load(inputStream) for each one
    }

    fun load(inputStream: InputStream): Set<String>
}

Register an implementation via META-INF/services/dev.reqcover.engine.spi.RequirementsSource, and ReqCover’s loadRequirements(uri) will try every registered source until one accepts the URI (a source that doesn’t recognize the format throws UnsupportedFormat and is skipped; a source that recognizes the format but can’t find the resource throws NotFound).

Built-in: reqcover-source-openapi

Reads an OpenAPI 3.x document and derives one requirement ID per meaningful unit in the spec:

• If an operation has no responses: #operationId
• If a response has no x-requirements: #operationId/responseCode
• If a response declares x-requirements: #operationId/responseCode/requirementKey - one ID per key

For example, this OpenAPI fragment:

paths:
  /api/health:
    get:
      operationId: getHealth
      responses:
        '200':
          description: Health is PASS
        '500':
          description: Health is FAIL
          x-requirements:
            downstream: When the downstream service is unavailable, health MUST return FAIL with a 500 status.
            database: When the database is unavailable, health MUST return FAIL with a 500 status.

produces three requirement IDs:

#getHealth/200
#getHealth/500/downstream
#getHealth/500/database

…which you’d then reference from your tests:

@Test
@ForRequirement("#getHealth/500/downstream")
void returnsFailWhenDownstreamIsUnavailable() { /* ... */ }

x-requirements is a plain OpenAPI extension field - any editor or validator that tolerates unknown x-* keys will happily keep working with your spec.

Writing your own source

A source doesn’t have to parse a spec format at all - a flat list of requirement IDs in a text file, or an export from a requirements-management tool, is a valid RequirementsSource. Implement the interface, add the META-INF/services entry, and put the module on your test classpath alongside reqcover-junit-jupiter.