Add configuration parameter hints

junit-jupiter-api/src/main/java/org/junit/jupiter/api/Constants.java

@@ -29,6 +29,8 @@
 import org.junit.jupiter.api.parallel.Execution;
 import org.junit.jupiter.api.parallel.ExecutionMode;
 import org.junit.platform.configuration.api.ConfigurationParameter;
+import org.junit.platform.configuration.api.ConfigurationParameter.Hint;
+import org.junit.platform.configuration.api.ConfigurationParameter.Hints;
 import org.junit.platform.engine.support.hierarchical.DefaultParallelExecutionConfigurationStrategy;
 import org.junit.platform.engine.support.hierarchical.ParallelExecutionConfigurationStrategy;
 import org.junit.platform.engine.support.hierarchical.ParallelHierarchicalTestExecutorServiceFactory;
@@ -330,15 +332,33 @@ public final class Constants {
 	 *
 	 * @see Timeout#DEFAULT_TIMEOUT_PROPERTY_NAME
 	 */
-	@ConfigurationParameter(type = String.class)
+	@ConfigurationParameter(type = String.class, hints = @Hints(permitsAdditionalValues = true, value = { //
+			@Hint(value = "42   ", description = "A duration in seconds"), //
+			@Hint(value = "42 ns", description = "A duration in nanoseconds"), //
+			@Hint(value = "42 μs", description = "A duration in microseconds"), //
+			@Hint(value = "42 ms", description = "A duration in milliseconds"), //
+			@Hint(value = "42 s ", description = "A duration in seconds"), //
+			@Hint(value = "42 m ", description = "A duration in minutes"), //
+			@Hint(value = "42 h ", description = "A duration in hours"), //
+			@Hint(value = "42 d ", description = "A duration in days") //
+	}))
 	public static final String DEFAULT_TIMEOUT_PROPERTY_NAME = Timeout.DEFAULT_TIMEOUT_PROPERTY_NAME;
 
 	/**
 	 * Property name used to set the default timeout for all testable methods: {@value}
 	 *
 	 * @see Timeout#DEFAULT_TESTABLE_METHOD_TIMEOUT_PROPERTY_NAME
 	 */
-	@ConfigurationParameter(type = String.class)
+	@ConfigurationParameter(type = String.class, hints = @Hints(permitsAdditionalValues = true, value = { //
+			@Hint(value = "42   ", description = "A duration in seconds"), //
+			@Hint(value = "42 ns", description = "A duration in nanoseconds"), //
+			@Hint(value = "42 μs", description = "A duration in microseconds"), //
+			@Hint(value = "42 ms", description = "A duration in milliseconds"), //
+			@Hint(value = "42 s ", description = "A duration in seconds"), //
+			@Hint(value = "42 m ", description = "A duration in minutes"), //
+			@Hint(value = "42 h ", description = "A duration in hours"), //
+			@Hint(value = "42 d ", description = "A duration in days") //
+	}))
 	public static final String DEFAULT_TESTABLE_METHOD_TIMEOUT_PROPERTY_NAME = Timeout.DEFAULT_TESTABLE_METHOD_TIMEOUT_PROPERTY_NAME;
 
 	/**
@@ -347,7 +367,16 @@ public final class Constants {
 	 *
 	 * @see Timeout#DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME
 	 */
-	@ConfigurationParameter(type = String.class)
+	@ConfigurationParameter(type = String.class, hints = @Hints(permitsAdditionalValues = true, value = { //
+			@Hint(value = "42   ", description = "A duration in seconds"), //
+			@Hint(value = "42 ns", description = "A duration in nanoseconds"), //
+			@Hint(value = "42 μs", description = "A duration in microseconds"), //
+			@Hint(value = "42 ms", description = "A duration in milliseconds"), //
+			@Hint(value = "42 s ", description = "A duration in seconds"), //
+			@Hint(value = "42 m ", description = "A duration in minutes"), //
+			@Hint(value = "42 h ", description = "A duration in hours"), //
+			@Hint(value = "42 d ", description = "A duration in days") //
+	}))
 	public static final String DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME = Timeout.DEFAULT_TEST_METHOD_TIMEOUT_PROPERTY_NAME;
 
 	/**
@@ -356,7 +385,16 @@ public final class Constants {
 	 *
 	 * @see Timeout#DEFAULT_TEST_TEMPLATE_METHOD_TIMEOUT_PROPERTY_NAME
 	 */
-	@ConfigurationParameter(type = String.class)
+	@ConfigurationParameter(type = String.class, hints = @Hints(permitsAdditionalValues = true, value = { //
+			@Hint(value = "42   ", description = "A duration in seconds"), //
+			@Hint(value = "42 ns", description = "A duration in nanoseconds"), //
+			@Hint(value = "42 μs", description = "A duration in microseconds"), //
+			@Hint(value = "42 ms", description = "A duration in milliseconds"), //
+			@Hint(value = "42 s ", description = "A duration in seconds"), //
+			@Hint(value = "42 m ", description = "A duration in minutes"), //
+			@Hint(value = "42 h ", description = "A duration in hours"), //
+			@Hint(value = "42 d ", description = "A duration in days") //
+	}))
 	public static final String DEFAULT_TEST_TEMPLATE_METHOD_TIMEOUT_PROPERTY_NAME = Timeout.DEFAULT_TEST_TEMPLATE_METHOD_TIMEOUT_PROPERTY_NAME;
 
 	/**
@@ -365,15 +403,33 @@ public final class Constants {
 	 *
 	 * @see Timeout#DEFAULT_TEST_FACTORY_METHOD_TIMEOUT_PROPERTY_NAME
 	 */
-	@ConfigurationParameter(type = String.class)
+	@ConfigurationParameter(type = String.class, hints = @Hints(permitsAdditionalValues = true, value = { //
+			@Hint(value = "42   ", description = "A duration in seconds"), //
+			@Hint(value = "42 ns", description = "A duration in nanoseconds"), //
+			@Hint(value = "42 μs", description = "A duration in microseconds"), //
+			@Hint(value = "42 ms", description = "A duration in milliseconds"), //
+			@Hint(value = "42 s ", description = "A duration in seconds"), //
+			@Hint(value = "42 m ", description = "A duration in minutes"), //
+			@Hint(value = "42 h ", description = "A duration in hours"), //
+			@Hint(value = "42 d ", description = "A duration in days") //
+	}))
 	public static final String DEFAULT_TEST_FACTORY_METHOD_TIMEOUT_PROPERTY_NAME = Timeout.DEFAULT_TEST_FACTORY_METHOD_TIMEOUT_PROPERTY_NAME;
 
 	/**
 	 * Property name used to set the default timeout for all lifecycle methods: {@value}
 	 *
 	 * @see Timeout#DEFAULT_LIFECYCLE_METHOD_TIMEOUT_PROPERTY_NAME
 	 */
-	@ConfigurationParameter(type = String.class)
+	@ConfigurationParameter(type = String.class, hints = @Hints(permitsAdditionalValues = true, value = { //
+			@Hint(value = "42   ", description = "A duration in seconds"), //
+			@Hint(value = "42 ns", description = "A duration in nanoseconds"), //
+			@Hint(value = "42 μs", description = "A duration in microseconds"), //
+			@Hint(value = "42 ms", description = "A duration in milliseconds"), //
+			@Hint(value = "42 s ", description = "A duration in seconds"), //
+			@Hint(value = "42 m ", description = "A duration in minutes"), //
+			@Hint(value = "42 h ", description = "A duration in hours"), //
+			@Hint(value = "42 d ", description = "A duration in days") //
+	}))
 	public static final String DEFAULT_LIFECYCLE_METHOD_TIMEOUT_PROPERTY_NAME = Timeout.DEFAULT_LIFECYCLE_METHOD_TIMEOUT_PROPERTY_NAME;
 
 	/**
@@ -382,7 +438,16 @@ public final class Constants {
 	 *
 	 * @see Timeout#DEFAULT_BEFORE_ALL_METHOD_TIMEOUT_PROPERTY_NAME
 	 */
-	@ConfigurationParameter(type = String.class)
+	@ConfigurationParameter(type = String.class, hints = @Hints(permitsAdditionalValues = true, value = { //
+			@Hint(value = "42   ", description = "A duration in seconds"), //
+			@Hint(value = "42 ns", description = "A duration in nanoseconds"), //
+			@Hint(value = "42 μs", description = "A duration in microseconds"), //
+			@Hint(value = "42 ms", description = "A duration in milliseconds"), //
+			@Hint(value = "42 s ", description = "A duration in seconds"), //
+			@Hint(value = "42 m ", description = "A duration in minutes"), //
+			@Hint(value = "42 h ", description = "A duration in hours"), //
+			@Hint(value = "42 d ", description = "A duration in days") //
+	}))
 	public static final String DEFAULT_BEFORE_ALL_METHOD_TIMEOUT_PROPERTY_NAME = Timeout.DEFAULT_BEFORE_ALL_METHOD_TIMEOUT_PROPERTY_NAME;
 
 	/**
@@ -391,7 +456,16 @@ public final class Constants {
 	 *
 	 * @see Timeout#DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME
 	 */
-	@ConfigurationParameter(type = String.class)
+	@ConfigurationParameter(type = String.class, hints = @Hints(permitsAdditionalValues = true, value = { //
+			@Hint(value = "42   ", description = "A duration in seconds"), //
+			@Hint(value = "42 ns", description = "A duration in nanoseconds"), //
+			@Hint(value = "42 μs", description = "A duration in microseconds"), //
+			@Hint(value = "42 ms", description = "A duration in milliseconds"), //
+			@Hint(value = "42 s ", description = "A duration in seconds"), //
+			@Hint(value = "42 m ", description = "A duration in minutes"), //
+			@Hint(value = "42 h ", description = "A duration in hours"), //
+			@Hint(value = "42 d ", description = "A duration in days") //
+	}))
 	public static final String DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME = Timeout.DEFAULT_BEFORE_EACH_METHOD_TIMEOUT_PROPERTY_NAME;
 
 	/**
@@ -400,7 +474,16 @@ public final class Constants {
 	 *
 	 * @see Timeout#DEFAULT_AFTER_EACH_METHOD_TIMEOUT_PROPERTY_NAME
 	 */
-	@ConfigurationParameter(type = String.class)
+	@ConfigurationParameter(type = String.class, hints = @Hints(permitsAdditionalValues = true, value = { //
+			@Hint(value = "42   ", description = "A duration in seconds"), //
+			@Hint(value = "42 ns", description = "A duration in nanoseconds"), //
+			@Hint(value = "42 μs", description = "A duration in microseconds"), //
+			@Hint(value = "42 ms", description = "A duration in milliseconds"), //
+			@Hint(value = "42 s ", description = "A duration in seconds"), //
+			@Hint(value = "42 m ", description = "A duration in minutes"), //
+			@Hint(value = "42 h ", description = "A duration in hours"), //
+			@Hint(value = "42 d ", description = "A duration in days") //
+	}))
 	public static final String DEFAULT_AFTER_EACH_METHOD_TIMEOUT_PROPERTY_NAME = Timeout.DEFAULT_AFTER_EACH_METHOD_TIMEOUT_PROPERTY_NAME;
 
 	/**
@@ -409,15 +492,24 @@ public final class Constants {
 	 *
 	 * @see Timeout#DEFAULT_AFTER_ALL_METHOD_TIMEOUT_PROPERTY_NAME
 	 */
-	@ConfigurationParameter(type = String.class)
+	@ConfigurationParameter(type = String.class, hints = @Hints(permitsAdditionalValues = true, value = { //
+			@Hint(value = "42   ", description = "A duration in seconds"), //
+			@Hint(value = "42 ns", description = "A duration in nanoseconds"), //
+			@Hint(value = "42 μs", description = "A duration in microseconds"), //
+			@Hint(value = "42 ms", description = "A duration in milliseconds"), //
+			@Hint(value = "42 s ", description = "A duration in seconds"), //
+			@Hint(value = "42 m ", description = "A duration in minutes"), //
+			@Hint(value = "42 h ", description = "A duration in hours"), //
+			@Hint(value = "42 d ", description = "A duration in days") //
+	}))
 	public static final String DEFAULT_AFTER_ALL_METHOD_TIMEOUT_PROPERTY_NAME = Timeout.DEFAULT_AFTER_ALL_METHOD_TIMEOUT_PROPERTY_NAME;
 
 	/**
 	 * Property name used to configure whether timeouts are applied to tests: {@value}
 	 *
 	 * @see Timeout#TIMEOUT_MODE_PROPERTY_NAME
 	 */
-	@ConfigurationParameter(defaultValue = @Value(stringValue = Timeout.TIMEOUT_MODE_DEFAULT))
+	@ConfigurationParameter(type = Timeout.TimeoutMode.class, defaultValue = @Value(stringValue = Timeout.TIMEOUT_MODE_DEFAULT))
 	public static final String TIMEOUT_MODE_PROPERTY_NAME = Timeout.TIMEOUT_MODE_PROPERTY_NAME;
 
 	/**

junit-jupiter-api/src/main/java/org/junit/jupiter/api/Timeout.java

@@ -314,7 +314,7 @@
 	 * {@link Timeout @Timeout} is applied to tests.</p>
 	 *
 	 * <p>Value must be one names of enum constants defined in
-	 *  {@link ThreadMode}, ignoring case. If not specified, the default is
+	 *  {@link TimeoutMode}, ignoring case. If not specified, the default is
 	 *  {@value #TIMEOUT_MODE_DEFAULT}.
 	 *
 	 * @since 5.6
@@ -400,4 +400,20 @@ enum ThreadMode {
 		SEPARATE_THREAD,
 	}
 
+	@API(status = STABLE, since = "6.2")
+	enum TimeoutMode {
+		/**
+		 * Timeouts are applied to tests.
+		 */
+		ENABLED,
+		/**
+		 * Timeouts are not applied to tests.
+		 */
+		DISABLED,
+		/**
+		 * Timeouts are not applied to tests when the JVM is started in debug mode.
+		 */
+		DISABLED_ON_DEBUG
+	}
+
 }

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/extension/TimeoutConfiguration.java

@@ -30,6 +30,7 @@
 import java.util.function.Supplier;
 
 import org.junit.jupiter.api.Timeout.ThreadMode;
+import org.junit.jupiter.api.Timeout.TimeoutMode;
 import org.junit.jupiter.api.extension.ExtensionContext;
 import org.junit.jupiter.engine.config.EnumConfigurationParameterConverter;
 import org.junit.platform.commons.logging.Logger;
@@ -53,7 +54,7 @@ class TimeoutConfiguration {
 		this.extensionContext = extensionContext;
 		this.timeoutDisabled = new EnumConfigurationParameterConverter<>(TimeoutMode.class, "timeout mode") //
 				.get(extensionContext, TIMEOUT_MODE_PROPERTY_NAME) //
-				.map(TimeoutMode::isTimeoutDisabled) //
+				.map(TimeoutConfiguration::isTimeoutDisabled) //
 				.orElse(false);
 	}
 
@@ -138,30 +139,12 @@ private Optional<ThreadMode> parseTimeoutThreadModeConfiguration() {
 				.get(extensionContext, DEFAULT_TIMEOUT_THREAD_MODE_PROPERTY_NAME);
 	}
 
-	private enum TimeoutMode {
-
-		ENABLED {
-			@Override
-			boolean isTimeoutDisabled() {
-				return false;
-			}
-		},
-
-		DISABLED {
-			@Override
-			boolean isTimeoutDisabled() {
-				return true;
-			}
-		},
-
-		DISABLED_ON_DEBUG {
-			@Override
-			boolean isTimeoutDisabled() {
-				return RuntimeUtils.isDebugMode();
-			}
+	private static boolean isTimeoutDisabled(TimeoutMode timeoutMode) {
+		return switch (timeoutMode) {
+			case ENABLED -> false;
+			case DISABLED -> true;
+			case DISABLED_ON_DEBUG -> RuntimeUtils.isDebugMode();
 		};
-
-		abstract boolean isTimeoutDisabled();
 	}
 
 }

junit-platform-configuration-api/src/main/java/org/junit/platform/configuration/api/ConfigurationParameter.java

@@ -52,6 +52,15 @@
 	 */
 	Deprecation deprecation() default @Deprecation;
 
+	/**
+	 * Hints for valid values for the parameter.
+	 * <p>
+	 * Can be omitted when {@link #type()} is an enum or interface.
+	 *
+	 * @return hints for valid values about the parameter.
+	 */
+	Hints hints() default @Hints;
+
 	@interface Deprecation {
 		/**
 		 * A brief description of why the parameter was deprecated.
@@ -129,8 +138,41 @@
 
 		/**
 		 * The {@link Class} value to use as the default.
+		 *
+		 * <p>When the default is a class value, the {@link ConfigurationParameter#type()}
+		 * should also be set.
 		 */
 		Class<?>[] classValue() default {};
 	}
 
+	@interface Hints {
+		/**
+		 * Valid values for the value of the parameter.
+		 *
+		 * @return valid values for the value of the parameter.
+		 */
+		Hint[] value() default {};
+
+		/**
+		 * Returns true if values other than the provided hints are allowed.
+		 * By default, is assumed the hints are exhaustive.
+		 *
+		 * @return true if values other than the provided hints are allowed.
+		 */
+		boolean permitsAdditionalValues() default false;
+	}
+
+	@interface Hint {
+
+		/**
+		 * A valid value for the configuration parameter.
+		 */
+		String value() default "";
+
+		/**
+		 * A short description of the value.
+		 */
+		String description() default "";
+
+	}
 }

junit-platform-configuration-processor/src/main/java/module-info.java

@@ -56,6 +56,11 @@
 /// {@code .}. Likewise {@code {@code}} and {@code {@link}} tags are replaced
 /// with plain text versions.
 ///
+/// <h5>Hints</h5>
+///
+/// When the {@linkplain  org.junit.platform.configuration.api.ConfigurationParameter#type() type}
+/// or the type of the {@linkplain  org.junit.platform.configuration.api.ConfigurationParameter#defaultValue() default value}
+/// is a boolean, enum, or interface, hints are automatically generated.
 module org.junit.platform.configuration.processor {
 	requires static transitive org.jspecify;
 	requires static transitive org.apiguardian.api;

junit-platform-configuration-processor/src/main/java/org/junit/platform/configuration/processor/AnnotationMirrorUtil.java

@@ -51,6 +51,28 @@ private AnnotationMirrorUtil() {
 				.orElse(null);
 	}
 
+	static @Nullable AnnotationValue getAnnotationValue(AnnotationMirror annotation, String name) {
+		for (var entry : annotation.getElementValues().entrySet()) {
+			if (entry.getKey().getSimpleName().toString().equals(name)) {
+				return entry.getValue();
+			}
+		}
+		return null;
+	}
+
+	@SuppressWarnings("unchecked")
+	static @Nullable List<AnnotationMirror> getAnnotationMirrorList(AnnotationMirror annotation, String name) {
+		for (var entry : annotation.getElementValues().entrySet()) {
+			if (entry.getKey().getSimpleName().toString().equals(name)) {
+				var value = entry.getValue().getValue();
+				if (value instanceof List<?> list) {
+					return (List<AnnotationMirror>) list;
+				}
+			}
+		}
+		return null;
+	}
+
 	static Map<String, List<Object>> getValuesMap(AnnotationMirror annotation) {
 		return annotation.getElementValues().entrySet() //
 				.stream() //