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 from the org.junit.platform:junit-platform-configuration-api artifact.

A small example

public class ConfigurationParametersDemo {

	/**
	 * 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 DEFAULT_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 minimal META-INF/junit-platform-configuration-metadata.json

{
    "properties": [
        {
            "name": "org.example.execution-mode",
            "type": "example.ExecutionMode",
            "description": "Property name used to set the default test execution mode.",
            "sourceType": "example.ConfigurationParametersDemo",
            "defaultValue": "fixed"
        }
    ]
}

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