Generate configuration parameters overview

[mpkorstanje]

Generate META-INF/junit-platform-configuration-metadata.json in the format of Spring Boots Configuration Metadata.

Minimal example

The minimal usage:

/**
 * A brief multi-line description of
 * this property: {@value}.
 *
 * <p>Followed by an additional paragraph.
 */
@ConfigurationProperty
public static final String EXAMPLE_PROPERTY_NAME = "org.example.property";

Produces:

{
  "properties": [
	{
	  "name": "org.example.property",
      "description": "A brief multi-line description of this property.",
	  "sourceType": "com.example.app.Constants"
	}
  ]
}

This takes all the information from the obvious places. Of note is that the first paragraph from the doc string is used and the : {@value}. that we conventionally use is replaced with a ..

Deprecation

@Deprecated
@ConfigurationParameter
public static final String EXAMPLE_PROPERTY_NAME = "org.example.property";

Produces:

{
  "properties": [
	{
	  "name": "org.example.property",
      "description": "A brief multi-line description of this property.",
	  "sourceType": "com.example.app.Constants",
      "deprecated": { }
	}
  ]
}

The empty deprecated object is sufficient to mark a field as deprecated. To fill out the fields in the deprecated object the @Deprecation annotation can be used:

@Deprecated
@ConfigurationParameter(deprecation = @Deprecation(reason = "A an example reason", replacement = "com.example.app.Constants#EXAMPLE_PROPERTY_NAME_V2", since = "2.0.0"))
public static final String EXAMPLE_PROPERTY_NAME_V1 = "org.example.property";

Type and default

The type of the parameter can be provided using the type property of the annotation.

@ConfigurationParameter(type = String.class)
public static final String EXAMPLE_PROPERTY_NAME = "org.example.property";

Though in practice this will be rarely needed. If the type is not provided, we can take the type of the default value.

@ConfigurationParameter(defaultValue = @Value(stringValue = "default"))
public static final String EXAMPLE_PROPERTY_NAME = "org.example.property";

When using Enums it is useful to use both type and default value, because arbitrary enums can't be used in an annotation.

@ConfigurationParameter(defaultValue = @Value(intValue = 42))
public static final String INTS_PROPERTY_NAME = "org.example.ints";

Limitations

• Metadata.groups, Metadata.hints, Metadata.ignored are not yet implemented. They might be useful later on, but we don't need them yet.
• While Property.default supports lists of values, the implementation is intentionally limited to a single value.

Closes: #4330

---

I hereby agree to the terms of the JUnit Contributor License Agreement.

---

Definition of Done

• There are no TODOs left in the code
• Method preconditions are checked and documented in the method's Javadoc
• Coding conventions (e.g. for logging) have been followed
• Change is covered by automated tests including corner cases, errors, and exception handling
• Public API has Javadoc and @API annotations
• Change is documented in the User Guide and Release Notes

[mpkorstanje]

TODO: Document circular dependency between tests and annotation processor.

[mpkorstanje]

@marcphilipp I can't infer what the intended location for constants is.

I would expect them to all sit in Constants, but we have DEFAULT_CLEANUP_MODE_PROPERTY_NAME duplicated here. This pattern is also present in Execution, TestInstance and Timeout.

Should new constants go here, or into Constants?

[testlens-app]

✅ All tests passed ✅

🏷️ Commit: bb2e42d
▶️ Tests: 9760 executed
⚪️ Checks: 15/15 completed

---

Learn more about TestLens at testlens.app.