Support arbitrary Java versions with JRE conditions

Prior to JUnit Jupiter 5.12, JRE-based conditions could only rely on
predefined constants in the JRE enum. Furthermore, those constants are
only updated as long as the particular JUnit Jupiter branch is
supported. For example, once JUnit Jupiter 5.12 is released, there is
no guarantee that the JRE enum constants will be updated in the 5.11.x
branch.

Consequently, users previously did not have the ability to enable or
disable tests for Java versions released after a particular JUnit
Jupiter branch was no longer supported.

To address that, this commit introduces support for arbitrary Java
versions in the JRE enum and related condition annotations.

Users can now specify arbitrary Java versions via the `versions`
attributes in @⁠EnabledOnJre and @⁠DisabledOnJre and via the
`minVersion` and `maxVersion` attributes in @⁠EnabledForJreRange and
@⁠DisabledForJreRange.

Closes: #3930
Closes: #3931

Author: sbrannen

documentation/src/docs/asciidoc/release-notes/release-notes-5.12.0-RC1.adoc

@@ -3,11 +3,11 @@
 
 *Date of Release:* ❓
 
-*Scope:* ❓
+*Scope:* Minor enhancements since JUnit 5.12 M1.
 
 For a complete list of all _closed_ issues and pull requests for this release, consult the
-link:{junit5-repo}+/milestone/88?closed=1+[5.12.0-RC1] milestone page in the
-JUnit repository on GitHub.
+link:{junit5-repo}+/milestone/88?closed=1+[5.12.0-RC1] milestone page in the JUnit
+repository on GitHub.
 
 
 [[release-notes-5.12.0-RC1-junit-platform]]
@@ -45,7 +45,10 @@ JUnit repository on GitHub.
 [[release-notes-5.12.0-RC1-junit-jupiter-new-features-and-improvements]]
 ==== New Features and Improvements
 
-* ❓
+* `JRE`-based conditions such as `@EnabledOnJre` and `@DisabledForJreRange` now support
+  arbitrary Java versions. See the
+  <<../user-guide/index.adoc#writing-tests-conditional-execution-jre, User Guide>> for
+  details.
 
 
 [[release-notes-5.12.0-RC1-junit-vintage]]

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

@@ -646,18 +646,36 @@ include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_arc
 [[writing-tests-conditional-execution-jre]]
 ==== Java Runtime Environment Conditions
 
-A container or test may be enabled or disabled on particular versions of the Java
-Runtime Environment (JRE) via the `{EnabledOnJre}` and `{DisabledOnJre}` annotations
-or on a particular range of versions of the JRE via the `{EnabledForJreRange}` and
-`{DisabledForJreRange}` annotations. The range defaults to `{JRE}.JAVA_8` as the lower
-border (`min`) and `{JRE}.OTHER` as the higher border (`max`), which allows usage of
-half open ranges.
+A container or test may be enabled or disabled on particular versions of the Java Runtime
+Environment (JRE) via the `{EnabledOnJre}` and `{DisabledOnJre}` annotations or on a
+particular range of versions of the JRE via the `{EnabledForJreRange}` and
+`{DisabledForJreRange}` annotations. The range effectively defaults to `JRE.JAVA_8` as the
+lower bound and `JRE.OTHER` as the upper bound, which allows usage of half open ranges.
+
+The following listing demonstrates the use of these annotations with predefined {JRE} enum
+constants.
 
 [source,java,indent=0]
 ----
 include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_jre]
 ----
 
+Since the enum constants defined in {JRE} are static for any given JUnit release, you
+might find that you need to configure a Java version that is not supported by the `JRE`
+enum. For example, as of JUnit Jupiter 5.12 the `JRE` enum defines `JAVA_25` as the
+highest supported Java version. However, you may wish to run your tests against later
+versions of Java. To support such use cases, you can specify arbitrary Java versions via
+the `versions` attributes in `@EnabledOnJre` and `@DisabledOnJre` and via the `minVersion`
+and `maxVersion` attributes in `@EnabledForJreRange` and `@DisabledForJreRange`.
+
+The following listing demonstrates the use of these annotations with arbitrary Java
+versions.
+
+[source,java,indent=0]
+----
+include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_jre_arbitrary_versions]
+----
+
 [[writing-tests-conditional-execution-native]]
 ==== Native Image Conditions
 

documentation/src/test/java/example/ConditionalTestExecutionDemo.java

@@ -10,9 +10,10 @@
 
 package example;
 
-import static org.junit.jupiter.api.condition.JRE.JAVA_10;
 import static org.junit.jupiter.api.condition.JRE.JAVA_11;
-import static org.junit.jupiter.api.condition.JRE.JAVA_8;
+import static org.junit.jupiter.api.condition.JRE.JAVA_17;
+import static org.junit.jupiter.api.condition.JRE.JAVA_21;
+import static org.junit.jupiter.api.condition.JRE.JAVA_25;
 import static org.junit.jupiter.api.condition.JRE.JAVA_9;
 import static org.junit.jupiter.api.condition.OS.LINUX;
 import static org.junit.jupiter.api.condition.OS.MAC;
@@ -101,26 +102,26 @@ void notOnNewMacs() {
 
 	// tag::user_guide_jre[]
 	@Test
-	@EnabledOnJre(JAVA_8)
-	void onlyOnJava8() {
+	@EnabledOnJre(JAVA_17)
+	void onlyOnJava17() {
 		// ...
 	}
 
 	@Test
-	@EnabledOnJre({ JAVA_9, JAVA_10 })
-	void onJava9Or10() {
+	@EnabledOnJre({ JAVA_17, JAVA_21 })
+	void onJava17And21() {
 		// ...
 	}
 
 	@Test
 	@EnabledForJreRange(min = JAVA_9, max = JAVA_11)
-	void fromJava9to11() {
+	void fromJava9To11() {
 		// ...
 	}
 
 	@Test
 	@EnabledForJreRange(min = JAVA_9)
-	void fromJava9toCurrentJavaFeatureNumber() {
+	void onJava9AndHigher() {
 		// ...
 	}
 
@@ -138,23 +139,73 @@ void notOnJava9() {
 
 	@Test
 	@DisabledForJreRange(min = JAVA_9, max = JAVA_11)
-	void notFromJava9to11() {
+	void notFromJava9To11() {
 		// ...
 	}
 
 	@Test
 	@DisabledForJreRange(min = JAVA_9)
-	void notFromJava9toCurrentJavaFeatureNumber() {
+	void notOnJava9AndHigher() {
 		// ...
 	}
 
 	@Test
 	@DisabledForJreRange(max = JAVA_11)
-	void notFromJava8to11() {
+	void notFromJava8To11() {
 		// ...
 	}
 	// end::user_guide_jre[]
 
+	// tag::user_guide_jre_arbitrary_versions[]
+	@Test
+	@EnabledOnJre(versions = 26)
+	void onlyOnJava26() {
+		// ...
+	}
+
+	@Test
+	@EnabledOnJre(value = JAVA_25, versions = 26)
+	void onJava25And26() {
+		// ...
+	}
+
+	@Test
+	@EnabledForJreRange(minVersion = 26)
+	void onJava26AndHigher() {
+		// ...
+	}
+
+	@Test
+	@EnabledForJreRange(min = JAVA_25, maxVersion = 27)
+	void fromJava25To27() {
+		// ...
+	}
+
+	@Test
+	@DisabledOnJre(versions = 26)
+	void notOnJava26() {
+		// ...
+	}
+
+	@Test
+	@DisabledOnJre(value = JAVA_25, versions = 26)
+	void notOnJava25And26() {
+		// ...
+	}
+
+	@Test
+	@DisabledForJreRange(minVersion = 26)
+	void notOnJava26AndHigher() {
+		// ...
+	}
+
+	@Test
+	@DisabledForJreRange(min = JAVA_25, maxVersion = 27)
+	void notFromJava25To27() {
+		// ...
+	}
+	// end::user_guide_jre_arbitrary_versions[]
+
 	// tag::user_guide_native[]
 	@Test
 	@EnabledInNativeImage

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/AbstractJreCondition.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2015-2025 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junit.jupiter.api.condition;
+
+import java.lang.annotation.Annotation;
+import java.util.Arrays;
+import java.util.function.Function;
+import java.util.stream.IntStream;
+
+import org.junit.platform.commons.util.Preconditions;
+
+/**
+ * Abstract base class for {@link EnabledOnJreCondition} and
+ * {@link DisabledOnJreCondition}.
+ *
+ * @since 5.12
+ */
+abstract class AbstractJreCondition<A extends Annotation> extends BooleanExecutionCondition<A> {
+
+	static final String ENABLED_ON_CURRENT_JRE = //
+		"Enabled on JRE version: " + System.getProperty("java.version");
+
+	static final String DISABLED_ON_CURRENT_JRE = //
+		"Disabled on JRE version: " + System.getProperty("java.version");
+
+	private final String annotationName;
+
+	AbstractJreCondition(Class<A> annotationType, Function<A, String> customDisabledReason) {
+		super(annotationType, ENABLED_ON_CURRENT_JRE, DISABLED_ON_CURRENT_JRE, customDisabledReason);
+		this.annotationName = annotationType.getSimpleName();
+	}
+
+	protected final IntStream validatedVersions(JRE[] jres, int[] versions) {
+		Preconditions.condition(jres.length > 0 || versions.length > 0,
+			() -> "You must declare at least one JRE or version in @" + this.annotationName);
+
+		return IntStream.concat(//
+			Arrays.stream(jres).mapToInt(jre -> {
+				Preconditions.condition(jre != JRE.UNDEFINED,
+					() -> "JRE.UNDEFINED is not supported in @" + this.annotationName);
+				return jre.version();
+			}), //
+			Arrays.stream(versions).map(version -> {
+				Preconditions.condition(version >= JRE.MINIMUM_VERSION,
+					() -> String.format("Version [%d] in @%s must be greater than or equal to %d", version,
+						this.annotationName, JRE.MINIMUM_VERSION));
+				return version;
+			})//
+		);
+	}
+
+}

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/AbstractJreRangeCondition.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2015-2025 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junit.jupiter.api.condition;
+
+import static org.junit.jupiter.api.condition.AbstractJreCondition.DISABLED_ON_CURRENT_JRE;
+import static org.junit.jupiter.api.condition.AbstractJreCondition.ENABLED_ON_CURRENT_JRE;
+
+import java.lang.annotation.Annotation;
+import java.util.function.Function;
+
+import org.junit.platform.commons.util.Preconditions;
+
+/**
+ * Abstract base class for {@link EnabledForJreRangeCondition} and
+ * {@link DisabledForJreRangeCondition}.
+ *
+ * @since 5.12
+ */
+abstract class AbstractJreRangeCondition<A extends Annotation> extends BooleanExecutionCondition<A> {
+
+	private final String annotationName;
+
+	AbstractJreRangeCondition(Class<A> annotationType, Function<A, String> customDisabledReason) {
+		super(annotationType, ENABLED_ON_CURRENT_JRE, DISABLED_ON_CURRENT_JRE, customDisabledReason);
+		this.annotationName = annotationType.getSimpleName();
+	}
+
+	protected final boolean isCurrentVersionWithinRange(JRE minJre, JRE maxJre, int minVersion, int maxVersion) {
+		boolean minJreSet = minJre != JRE.UNDEFINED;
+		boolean maxJreSet = maxJre != JRE.UNDEFINED;
+		boolean minVersionSet = minVersion != JRE.UNDEFINED_VERSION;
+		boolean maxVersionSet = maxVersion != JRE.UNDEFINED_VERSION;
+
+		// Users must choose between JRE enum constants and version numbers.
+		Preconditions.condition(!minJreSet || !minVersionSet, () -> String.format(
+			"@%s's minimum value must be configured with either a JRE enum constant or numeric version, but not both",
+			this.annotationName));
+		Preconditions.condition(!maxJreSet || !maxVersionSet, () -> String.format(
+			"@%s's maximum value must be configured with either a JRE enum constant or numeric version, but not both",
+			this.annotationName));
+
+		// Users must supply valid values for minVersion and maxVersion.
+		Preconditions.condition(!minVersionSet || (minVersion >= JRE.MINIMUM_VERSION),
+			() -> String.format("@%s's minVersion [%d] must be greater than or equal to %d", this.annotationName,
+				minVersion, JRE.MINIMUM_VERSION));
+		Preconditions.condition(!maxVersionSet || (maxVersion >= JRE.MINIMUM_VERSION),
+			() -> String.format("@%s's maxVersion [%d] must be greater than or equal to %d", this.annotationName,
+				maxVersion, JRE.MINIMUM_VERSION));
+
+		// Now that we have checked the basic preconditions, we need to ensure that we are
+		// using valid JRE enum constants.
+		if (!minJreSet) {
+			minJre = JRE.JAVA_8;
+		}
+		if (!maxJreSet) {
+			maxJre = JRE.OTHER;
+		}
+
+		int min = (minVersionSet ? minVersion : minJre.version());
+		int max = (maxVersionSet ? maxVersion : maxJre.version());
+
+		// Finally, we need to validate the effective minimum and maximum values.
+		Preconditions.condition((min != JRE.MINIMUM_VERSION || max != Integer.MAX_VALUE),
+			() -> "You must declare a non-default value for the minimum or maximum value in @" + this.annotationName);
+		Preconditions.condition(min >= JRE.MINIMUM_VERSION,
+			() -> String.format("@%s's minimum value [%d] must greater than or equal to %d", this.annotationName, min,
+				JRE.MINIMUM_VERSION));
+		Preconditions.condition(min <= max,
+			() -> String.format("@%s's minimum value [%d] must be less than or equal to its maximum value [%d]",
+				this.annotationName, min, max));
+
+		return JRE.isCurrentVersionWithinRange(min, max);
+	}
+
+}

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/BooleanExecutionCondition.java

@@ -23,31 +23,32 @@
 
 abstract class BooleanExecutionCondition<A extends Annotation> implements ExecutionCondition {
 
-	private final Class<A> annotationType;
+	protected final Class<A> annotationType;
 	private final String enabledReason;
 	private final String disabledReason;
 	private final Function<A, String> customDisabledReason;
 
 	BooleanExecutionCondition(Class<A> annotationType, String enabledReason, String disabledReason,
 			Function<A, String> customDisabledReason) {
+
 		this.annotationType = annotationType;
 		this.enabledReason = enabledReason;
 		this.disabledReason = disabledReason;
 		this.customDisabledReason = customDisabledReason;
 	}
 
-	abstract boolean isEnabled(A annotation);
-
 	@Override
 	public ConditionEvaluationResult evaluateExecutionCondition(ExtensionContext context) {
-		return findAnnotation(context.getElement(), annotationType) //
-				.map(annotation -> isEnabled(annotation) ? enabled(enabledReason)
-						: disabled(disabledReason, customDisabledReason.apply(annotation))) //
+		return findAnnotation(context.getElement(), this.annotationType) //
+				.map(annotation -> isEnabled(annotation) ? enabled(this.enabledReason)
+						: disabled(this.disabledReason, this.customDisabledReason.apply(annotation))) //
 				.orElseGet(this::enabledByDefault);
 	}
 
+	abstract boolean isEnabled(A annotation);
+
 	private ConditionEvaluationResult enabledByDefault() {
-		String reason = String.format("@%s is not present", annotationType.getSimpleName());
+		String reason = String.format("@%s is not present", this.annotationType.getSimpleName());
 		return enabled(reason);
 	}