Introduce from and to attributes on @EnumSource (#4221)

The new attributes allow defining the range of enum constants to be 
tested.

Resolves #4185.

---------

Co-authored-by: Marc Philipp <[email protected]>

Author: yhkuo41

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

@@ -137,6 +137,8 @@ JUnit repository on GitHub.
   thread dump to `System.out` prior to interrupting a test thread due to a timeout.
 * `TestReporter` now allows publishing files for a test method or test class which can be
   used to include them in test reports, such as the Open Test Reporting format.
+* New `from` and `to` attributes added to `@EnumSource` to support range selection of
+  enum constants.
 * Auto-registered extensions can now be
   <<../user-guide/index.adoc#extensions-registration-automatic-filtering, filtered>> using
   include and exclude patterns that can be specified as configuration parameters.

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

@@ -1560,14 +1560,28 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=EnumSource_example_au
 ----
 
 The annotation provides an optional `names` attribute that lets you specify which
-constants shall be used, like in the following example. If omitted, all constants will be
-used.
+constants shall be used, like in the following example.
 
 [source,java,indent=0]
 ----
 include::{testDir}/example/ParameterizedTestDemo.java[tags=EnumSource_include_example]
 ----
 
+In addition to `names`, you can use the `from` and `to` attributes to specify a range of
+constants. The range starts from the constant specified in the `from` attribute and
+includes all subsequent constants up to and including the one specified in the `to`
+attribute, based on the natural order of the enum constants.
+
+If `from` and `to` attributes are omitted, they default to the first and last constants
+in the enum type, respectively. If all `names`, `from`, and `to` attributes are omitted,
+all constants will be used. The following example demonstrates how to specify a range of
+constants.
+
+[source,java,indent=0]
+----
+include::{testDir}/example/ParameterizedTestDemo.java[tags=EnumSource_range_example]
+----
+
 The `@EnumSource` annotation also provides an optional `mode` attribute that enables
 fine-grained control over which constants are passed to the test method. For example, you
 can exclude names from the enum constant pool or specify regular expressions as in the
@@ -1583,6 +1597,14 @@ include::{testDir}/example/ParameterizedTestDemo.java[tags=EnumSource_exclude_ex
 include::{testDir}/example/ParameterizedTestDemo.java[tags=EnumSource_regex_example]
 ----
 
+You can also combine `mode` with the `from`, `to` and `names` attributes to define a
+range of constants while excluding specific values from that range as shown below.
+
+[source,java,indent=0]
+----
+include::{testDir}/example/ParameterizedTestDemo.java[tags=EnumSource_range_exclude_example]
+----
+
 [[writing-tests-parameterized-tests-sources-MethodSource]]
 ===== @MethodSource
 

documentation/src/test/java/example/ParameterizedTestDemo.java

@@ -148,6 +148,14 @@ void testWithEnumSourceInclude(ChronoUnit unit) {
 	}
 	// end::EnumSource_include_example[]
 
+	// tag::EnumSource_range_example[]
+	@ParameterizedTest
+	@EnumSource(from = "HOURS", to = "DAYS")
+	void testWithEnumSourceRange(ChronoUnit unit) {
+		assertTrue(EnumSet.of(ChronoUnit.HOURS, ChronoUnit.HALF_DAYS, ChronoUnit.DAYS).contains(unit));
+	}
+	// end::EnumSource_range_example[]
+
 	// tag::EnumSource_exclude_example[]
 	@ParameterizedTest
 	@EnumSource(mode = EXCLUDE, names = { "ERAS", "FOREVER" })
@@ -164,6 +172,15 @@ void testWithEnumSourceRegex(ChronoUnit unit) {
 	}
 	// end::EnumSource_regex_example[]
 
+	// tag::EnumSource_range_exclude_example[]
+	@ParameterizedTest
+	@EnumSource(from = "HOURS", to = "DAYS", mode = EXCLUDE, names = { "HALF_DAYS" })
+	void testWithEnumSourceRangeExclude(ChronoUnit unit) {
+		assertTrue(EnumSet.of(ChronoUnit.HOURS, ChronoUnit.DAYS).contains(unit));
+		assertFalse(EnumSet.of(ChronoUnit.HALF_DAYS).contains(unit));
+	}
+	// end::EnumSource_range_exclude_example[]
+
 	// tag::simple_MethodSource_example[]
 	@ParameterizedTest
 	@MethodSource("stringProvider")

junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/EnumArgumentsProvider.java

@@ -43,7 +43,19 @@ protected Stream<? extends Arguments> provideArguments(ExtensionContext context,
 
 	private <E extends Enum<E>> Set<? extends E> getEnumConstants(ExtensionContext context, EnumSource enumSource) {
 		Class<E> enumClass = determineEnumClass(context, enumSource);
-		return EnumSet.allOf(enumClass);
+		E[] constants = enumClass.getEnumConstants();
+		if (constants.length == 0) {
+			Preconditions.condition(enumSource.from().isEmpty() && enumSource.to().isEmpty(),
+				"No enum constant in " + enumClass.getSimpleName() + ", but 'from' or 'to' is not empty.");
+			return EnumSet.noneOf(enumClass);
+		}
+		E from = enumSource.from().isEmpty() ? constants[0] : Enum.valueOf(enumClass, enumSource.from());
+		E to = enumSource.to().isEmpty() ? constants[constants.length - 1] : Enum.valueOf(enumClass, enumSource.to());
+		Preconditions.condition(from.compareTo(to) <= 0,
+			() -> String.format(
+				"Invalid enum range: 'from' (%s) must come before 'to' (%s) in the natural order of enum constants.",
+				from, to));
+		return EnumSet.range(from, to);
 	}
 
 	@SuppressWarnings({ "unchecked", "rawtypes" })

junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/EnumSource.java

@@ -40,8 +40,8 @@
  * attribute. Otherwise, the declared type of the first parameter of the
  * {@code @ParameterizedTest} method is used.
  *
- * <p>The set of enum constants can be restricted via the {@link #names} and
- * {@link #mode} attributes.
+ * <p>The set of enum constants can be restricted via the {@link #names},
+ * {@link #from}, {@link #to} and {@link #mode} attributes.
  *
  * @since 5.0
  * @see org.junit.jupiter.params.provider.ArgumentsSource
@@ -63,6 +63,8 @@
 	 * first parameter of the {@code @ParameterizedTest} method is used.
 	 *
 	 * @see #names
+	 * @see #from
+	 * @see #to
 	 * @see #mode
 	 */
 	Class<? extends Enum<?>> value() default NullEnum.class;
@@ -71,19 +73,61 @@
 	 * The names of enum constants to provide, or regular expressions to select
 	 * the names of enum constants to provide.
 	 *
-	 * <p>If no names or regular expressions are specified, all enum constants
-	 * declared in the specified {@linkplain #value enum type} will be provided.
+	 * <p>If no names or regular expressions are specified, and neither {@link #from}
+	 * nor {@link #to} are specified, all enum constants declared in the specified
+	 * {@linkplain #value enum type} will be provided.
+	 *
+	 * <p>If {@link #from} or {@link #to} are specified, the elements in names must
+	 * fall within the range defined by {@link #from} and {@link #to}.
 	 *
 	 * <p>The {@link #mode} determines how the names are interpreted.
 	 *
 	 * @see #value
+	 * @see #from
+	 * @see #to
 	 * @see #mode
 	 */
 	String[] names() default {};
 
+	/**
+	 * The starting enum constant of the range to be included.
+	 *
+	 * <p>Defaults to an empty string, where the range starts from the first enum
+	 * constant of the specified {@linkplain #value enum type}.
+	 *
+	 * @see #value
+	 * @see #names
+	 * @see #to
+	 * @see #mode
+	 *
+	 * @since 5.12
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12")
+	String from() default "";
+
+	/**
+	 * The ending enum constant of the range to be included.
+	 *
+	 * <p>Defaults to an empty string, where the range ends at the last enum
+	 * constant of the specified {@linkplain #value enum type}.
+	 *
+	 * @see #value
+	 * @see #names
+	 * @see #from
+	 * @see #mode
+	 *
+	 * @since 5.12
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12")
+	String to() default "";
+
 	/**
 	 * The enum constant selection mode.
 	 *
+	 * <p>The mode only applies to the {@link #names} attribute and does not change
+	 * the behavior of {@link #from} and {@link #to}, which always define a range
+	 * based on the natural order of the enum constants.
+	 *
 	 * <p>Defaults to {@link Mode#INCLUDE INCLUDE}.
 	 *
 	 * @see Mode#INCLUDE
@@ -92,6 +136,8 @@
 	 * @see Mode#MATCH_ANY
 	 * @see Mode#MATCH_NONE
 	 * @see #names
+	 * @see #from
+	 * @see #to
 	 */
 	Mode mode() default Mode.INCLUDE;