The annotation @EnumSource allows to specify a parameterized test in which the argument source is a Java enumeration class. By default, each value of the enumeration will be used to feed the parameterized test, one at a time.

For example, in the following test class, the method testWithEnum is annotated with @ParameterizedTest in conjunction with @EnumSource. As we can see, the value of this annotation is TimeUnit.class, which is a standard Java annotation (package java.util.concurrent) used to represent time duration. The possible values defined in this enumeration are NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, and DAYS:

package io.github.bonigarcia;

import static org.junit.jupiter.api.Assertions.assertNotNull;

import java.util.concurrent.TimeUnit;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.EnumSource;

class EnumSourceParameterizedTest {

    @ParameterizedTest
    @EnumSource(TimeUnit.class)
    void testWithEnum(TimeUnit argument) {
        System.out.println("Parameterized test with (TimeUnit)         
            argument: " + argument);
        assertNotNull(argument);
    }

}

Therefore, the execution of this test will be carried out seven times, that is, one per TimeUnit enumeration value. We can check this in the trace of the output console when executing the test:

Moreover, the @EnumSource annotation allows to filter the members of the enumeration in several ways. To implement this selection, the following elements can be specified within a @EnumSource annotation:

• mode: Constant value which determines the type of filtering. This is defined as an enumeration in the inner class org.junit.jupiter.params.provider.EnumSource.Mode, and the possible values are:
  • INCLUDE: Used to select those values whose names are supplied via the names element. This is the default option.
  • EXCLUDE: Used to select all values except those supplied with the names element.
  • MATCH_ALL: Used to select those values whose names match the patterns in names element.
  • MATCH_ANY: Used to select those values whose names match any pattern in the names element.
• names: The array of string which allows to select a group of enum constants. The criteria for inclusion/exclusion is directly linked to the value of mode. In addition, this element also allows to define regular expressions to select the names of enum constants to be matched.

Consider the following example. In this class, there are three parameterized tests. First one, named testWithFilteredEnum, uses the class TimeUnit to feed the @EnumSource argument provider. Moreover, the enum constant set is filtered using the element names. As we can see, only the constant "DAYS" and "HOURS" will be used to feed this test (take into account that the default mode is INCLUDE):

package io.github.bonigarcia;

import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.params.provider.EnumSource.Mode.EXCLUDE;
import static org.junit.jupiter.params.provider.EnumSource.Mode.MATCH_ALL;

import java.util.concurrent.TimeUnit;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.EnumSource;

class EnumSourceFilteringParameterizedTest {

    @ParameterizedTest
    @EnumSource(value = TimeUnit.class, names = { "DAYS", "HOURS" })
    void testWithFilteredEnum(TimeUnit argument) {
        System.out.println("Parameterized test with some (TimeUnit) 
            argument: "+ argument);
        assertNotNull(argument);
    }

    @ParameterizedTest
    @EnumSource(value = TimeUnit.class, mode = EXCLUDE, names = { 
    "DAYS", "HOURS" })
    void testWithExcludeEnum(TimeUnit argument) {
        System.out.println("Parameterized test with excluded (TimeUnit) 
            argument: " + argument);
        assertNotNull(argument);
    }

    @ParameterizedTest
    @EnumSource(value = TimeUnit.class, mode = MATCH_ALL, names = 
    "^(M|N).+SECONDS$")
    void testWithRegexEnum(TimeUnit argument) {
        System.out.println("Parameterized test with regex filtered 
            (TimeUnit) argument: " + argument);
        assertNotNull(argument);
    }

}

Thus, when executing this class in the console, the output we obtain is the following. Regarding the first test, we can see that only traces for "DAYS" and "HOURS" are present:

Consider now the second test method, named testWithExcludeEnum. This test is exactly the same as before with a difference: the mode here is EXCLUSION (instead of INCLUSION, chosen by default in the previous test). All in all, in the execution (see screenshot before) when can see that this test is executed five times, per one of the enum constant different to DAYS and HOURS. To check that, track the traces with the sentence "Parameterized test with excluded (TimeUnit) argument".

The third and last method of this class (called testWithRegexEnum) defines an inclusion mode, MATCH_ALL, using a regular expression to filter the enumeration (in this case, it is also TimeUnit). The concrete regular expression used in this example is ^(M|N).+SECONDS$, which means that only will be included in those enum constants starting with M or N and ending with SECONDS. As can be checked in the execution screenshot, there are three TimeUnit constants matching these conditions: NANOSECONDS, MICROSECONDS, and MILISECONDS.