Documenting Configuration Parameters

Authors of test engines and JUnit Jupiter extensions may generate a machine-readable overview of configuration parameters by annotating their configuration parameters with ConfigurationParameter and ConfigurationParameterGroup from the org.junit.platform:junit-platform-configuration-api artifact.

A small example

/**
 * Collection of configuration parameters for the example project.
 */
@ConfigurationParameterGroup("org.example")
public class ConfigurationParametersDemo {

	enum ExecutionMode {

		/**
		 * Executes with a fixed number of threads.
		 */
		FIXED,

		/**
		 * Executes with a dynamic number of threads.
		 */
		DYNAMIC
	}

	/**
	 * Property name used to set the default test execution mode: {@value}.
	 * <p>
	 * Test can be executed with either a fixed number of threads, a number
	 * based on the available cores or a custom strategy.
	 */
	@ConfigurationParameter(type = ExecutionMode.class, defaultValue = @Value(stringValue = "fixed"))
	public static final String EXECUTION_MODE_PROPERTY_NAME = "org.example.execution-mode";
}

Processing the annotations with org.junit.platform:junit-platform-configuration-processor will produce a META-INF/junit-platform-configuration-metadata.json file in the format of Spring Boots Configuration Metadata. This file can then be used to generate documentation or provide code completion by IDEs. An example is shown below.

A small META-INF/junit-platform-configuration-metadata.json

{
    "groups": [
        {
            "name": "org.example",
            "sourceType": "example.ConfigurationParametersDemo",
            "description": "Collection of configuration parameters for the example project."
        }
    ],
    "properties": [
        {
            "name": "org.example.execution-mode",
            "type": "example.ConfigurationParametersDemo.ExecutionMode",
            "description": "Property name used to set the default test execution mode.",
            "sourceType": "example.ConfigurationParametersDemo",
            "defaultValue": "fixed"
        }
    ],
    "hints": [
        {
            "name": "org.example.execution-mode",
            "values": [
                {
                    "value": "fixed",
                    "description": "Executes with a fixed number of threads."
                },
                {
                    "value": "dynamic",
                    "description": "Executes with a dynamic number of threads."
                }
            ]
        }
    ]
}

The first paragraph from the Javadoc will be used to describe the property or group. If the first paragraph contains tags these will be sensibly replaced.

When the type is an enum or interface, hints will be automatically generated. The first paragraph of the enum constant is used to describe the enum value. If the allowed values are not enumerable, ConfigurationParameter.hints() can be used to provide examples instead.

Gradle

To use the annotation processor with Gradle, add the junit-platform-configuration-api as a compileOnly dependency and enable the junit-platform-configuration-processor as an annotationProcessor.

dependencies {
	annotationProcessor("org.junit.platform:junit-platform-configuration-processor:6.2.0-SNAPSHOT")
	compileOnly("org.junit.platform:junit-platform-configuration-api:6.2.0-SNAPSHOT")
}

Maven

To use the annotation processor with Maven, add the junit-platform-configuration-api as an optional runtime dependency and add the junit-platform-configuration-processor to the annotationProcessorPaths of the maven-compiler-plugin.

<project>
	<!-- ... -->
	<dependencyManagement>
		<dependencies>
			<dependency>
				<groupId>org.junit</groupId>
				<artifactId>junit-bom</artifactId>
				<version>6.2.0-SNAPSHOT</version>
				<type>pom</type>
				<scope>import</scope>
			</dependency>
		</dependencies>
	</dependencyManagement>

	<dependencies>
		<dependency>
			<groupId>org.junit.platform</groupId>
			<artifactId>junit-platform-configuration-api</artifactId>
			<optional>true</optional>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>3.16.0</version>
				<configuration>
					<annotationProcessorPathsUseDepMgmt>true</annotationProcessorPathsUseDepMgmt>
					<annotationProcessorPaths>
						<path>
							<groupId>org.junit.platform</groupId>
							<artifactId>junit-platform-configuration-processor</artifactId>
						</path>
					</annotationProcessorPaths>
				</configuration>
			</plugin>
		</plugins>
	</build>
	<!-- ... -->
</project>