Reqstool Gradle Plugin

Gradle build plugin for reqstool that assembles requirements traceability artifacts.

Overview

Collects @Requirements and @SVCs annotations from compiled Java code, combines them with test results, and packages everything into a ZIP artifact for analysis by the reqstool CLI. Supports Java 21+.

The plugin automatically wires task dependencies: assembleRequirements depends on all compileJava tasks, and build is finalized by assembleRequirements. No manual task wiring is needed in most projects.

Installation

Add the plugin to your build.gradle:

plugins {
    id 'io.github.reqstool.gradle-plugin' version '0.1.1'
}

requirementsTool {
    datasetPath = file('docs/reqstool')
}

The assembleRequirements task runs automatically as part of build. No additional wiring is required.

Configuration

All properties are optional. Defaults match the standard Gradle project layout.

Property	Type	Default	Description
requirementsAnnotationsFile	RegularFileProperty	build/generated/sources/annotationProcessor/java/main/resources/annotations.yml	Requirements annotations YAML file generated by the annotation processor for the main source set
svcsAnnotationsFiles	ConfigurableFileCollection	Auto-discovered from all non-main source sets	SVCs annotations YAML files, one per test source set (e.g. test, integrationTest)
svcsAnnotationsFile (deprecated)	Object	—	Deprecated since 0.1.1. Use svcsAnnotationsFiles.from(...) instead. Delegates to svcsAnnotationsFiles and emits a WARN log.
outputDirectory	RegularFileProperty	build/reqstool	Output directory for the ZIP artifact and combined annotations file
datasetPath	RegularFileProperty	reqstool/ (project directory)	Directory containing requirements.yml and optional supporting files
testResults	ListProperty<String>	["build/test-results/**/*.xml"]	Ant-style glob patterns for test result XML files to include in the ZIP
skip	Property<Boolean>	false	Skip all plugin execution
skipAssembleZipArtifact	Property<Boolean>	false	Skip ZIP assembly; annotations are still combined into annotations.yml
skipAttachZipArtifact	Property<Boolean>	false	Skip attaching the ZIP artifact to Maven publications

Dataset directory

The datasetPath directory must contain at minimum a requirements.yml file. Optional files in the same directory are included if present:

File	Required
requirements.yml	Yes
software_verification_cases.yml	No
manual_verification_results.yml	No

Overriding auto-discovered annotation files

To replace the auto-discovered SVCs annotation files with explicit paths (also disables auto-wired compile dependencies for test source sets):

requirementsTool {
    setSvcsAnnotationsFiles(
        file('custom/path/test-annotations.yml'),
        file('custom/path/it-annotations.yml')
    )
}

JUnit 5 parameterized tests

Gradle's JUnit XML reporter writes test case names using the parameterized test's display name. By default this is [N] arguments — a format that omits the method name. Reqstool cannot link these entries to @SVCs-annotated methods without the method name.

Add this to your build to include the method name in every test case name, covering all test tasks (unit, integration, e2e):

tasks.withType(Test).configureEach {
    systemProperty 'junit.jupiter.params.displayname.default', '{displayName}[{index}]'
}

Kotlin DSL:

tasks.withType<Test>().configureEach {
    systemProperty("junit.jupiter.params.displayname.default", "{displayName}[{index}]")
}

This produces names like checkStatus(StatusType)[1] instead of [1] ACTIVE, which reqstool can correctly attribute to the annotated method.

Note: Tests with an explicit @ParameterizedTest(name = "{index} ...") still omit the method name because the explicit value overrides the default. Either remove the custom name or change it to start with {displayName}: @ParameterizedTest(name = "{displayName}[{index}] ...").

Maven Surefire always embeds the method name regardless of display-name settings — no change needed for Maven projects.

Task reference

assembleRequirements

Group: build

Combines requirements and SVCs annotations from all source sets, writes a merged annotations.yml to outputDirectory, and (unless skipAssembleZipArtifact is set) assembles a ZIP artifact at <outputDirectory>/<name>-<version>-reqstool.zip.

Auto-wired dependencies (when the java plugin is applied):

• Depends on compileJava (main source set)
• Depends on compileXxxJava for each non-main source set (unless svcsAnnotationsFiles was set explicitly)
• build is finalized by assembleRequirements

Usage

gradle clean build

The plugin generates a ZIP artifact in build/reqstool/ containing requirements, annotations, and test results.

Documentation

Full documentation can be found here.

Contributing

See the organization-wide CONTRIBUTING.md.

License

MIT License.