JUnit5 enables us to execute a single test method multiple times with a different sets of data. This is called Parameterization. Parameterized Tests are declared just like regular @Test methods but use the @ParameterizedTest annotation.
This article shows you how to run a test multiple times with different arguments, so-called ‘Parameterized Tests’, let’s see the following ways to provide arguments to the test:
- @ValueSource
- @EnumSource
- @MethodSource
- @CsvSource
- @CsvFileSource
- @ArgumentsSource
We need to add junit-jupiter-params to support parameterized tests. In the case of Maven, add the dependency to POM.xml
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-params</artifactId>
<version>5.8.2</version>
<scope>test</scope>
</dependency>
In case of Gradle, add the dependency as
testCompile("org.junit.jupiter:junit-jupiter-params:5.8.2")
1. @ValueSource
Let us start with a simple example. The following example demonstrates a parameterized test that uses the @ValueSource annotation to specify an integer array as the source of arguments. The following @ParameterizedTest method will be invoked three times, with the values 5,6, and 0 respectively.
@ParameterizedTest
@ValueSource(ints = {5, 6, 0})
void test_int_arrays(int b) {
int a= 5;
int sum = a + b;
assertTrue(sum>8);
}
When executing the above-parameterized test method, each invocation will be reported separately.
The output of the above program is:
One of the limitations of value sources is that they only support these types:
- short (with the shorts attribute)
- byte (bytes attribute)
- int (ints attribute)
- long (longs attribute)
- float (floats attribute)
- double (doubles attribute)
- char (chars attribute)
- java.lang.String (strings attribute)
- java.lang.Class (classes attribute)
Also, we can only pass one argument to the test method each time.
In the below example, an array of strings is passed as the argument to the Parameterized Test.
@ParameterizedTest(name = "#{index} - Run test with args={0}")
@ValueSource(strings = {"java", "python", "javascript","php"})
void test_string_arrays(String arg) {
assertTrue(arg.length() > 1);
}
The output of the above program is:
@NullSource
It provides a single null an argument to the annotated @ParameterizedTest method.
@ParameterizedTest()
@NullSource
void nullString(String text) {
assertTrue(text == null);
}
The output of the above program is:
@EmptySource
It provides a single empty argument to the annotated @ParameterizedTest method of the following types:
- java.lang.String
- java.util.List
- java.util.Set
- java.util.Map
- primitive arrays (e.g. int[])
- object arrays (e.g. String[])
@ParameterizedTest
@EmptySource
void testMethodEmptySource(String argument) {
assertTrue(StringUtils.isEmpty(argument));
assertTrue(StringUtils.isBlank(argument));
}
The output of the above program is:
@NullAndEmptySource
We can pass empty or null values into the test via @EmptySource, @NullSource, or @NullAndEmptySource (since JUnit 5.4).
Let’s see the following example to test an isEmpty() method.
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.EmptySource;
import org.junit.jupiter.params.provider.NullSource;
import org.junit.jupiter.params.provider.ValueSource;
import static org.junit.jupiter.api.Assertions.*;
public class ParameterizedTestDemo {
@ParameterizedTest(name = "#{index} - isEmpty()? {0}")
@NullSource
@EmptySource
@ValueSource(strings = { " ", " ", "\t", "\n","a"})
void nullEmptyAndBlankStrings(String text) {
assertTrue(text == null || text.trim().isEmpty());
}
}
The parameterized test method result in seven invocations: 1 for null, 1 for the empty string, 4 for the explicit blank strings supplied via @ValueSource, and 1 non-blank string “a” supplied via @ValueSource.
The output of the above program is:
2. @EnumSource
@EnumSource provides a convenient way to use Enum constants.
public class EnumParameterizedTest {
enum Error {
Request_Invalid,
Request_Timeout,
RequestHeader_Invalid,
Concurrency_Failed,
ExternalCall_Failed,
Schema_Invalid,
Authentication_Failed;
}
@ParameterizedTest
@EnumSource(Error.class)
void test_enum(Error error) {
assertNotNull(error);
}
}
The output of the above program is:
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.
@ParameterizedTest(name = "#{index} - Is Error contains {0}?")
@EnumSource(value = Error.class, names = {"Request_Invalid", "ExternalCall_Failed", "Concurrency_Failed", "Authentication_Failed"})
void test_enum_include(Error error) {
assertTrue(EnumSet.allOf(Error.class).contains(error));
}
The output of the above program is:
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 following examples.
@ParameterizedTest
@EnumSource(value = Error.class, mode = EnumSource.Mode.EXCLUDE, names = {"Request_Invalid", "Request_Timeout", "RequestHeader_Invalid"})
void test_enum_exclude(Error error) {
EnumSet<Error> excludeRequestRelatedError = EnumSet.range(Error.Concurrency_Failed, Error.Authentication_Failed);
assertTrue(excludeRequestRelatedError.contains(error));
}
The output of the above program is:
EnumSource.Mode.EXCLUDE – It selects all declared enum constants except those supplied via the names attribute.
EnumSource.Mode.MATCH_ALL – It selects only those enum constants whose names match any pattern supplied via the names attribute.
@ParameterizedTest
@EnumSource(mode = EnumSource.Mode.MATCH_ALL, names = "^.*Invalid")
void test_match(Error error) {
assertTrue(error.name().contains("Invalid"));
}
The output of the above program is
3. @MethodSource
@MethodSource allows you to refer to one or more factory methods of the test class or external classes.
Factory methods within the test class must be static unless the test class is annotated with @TestInstance(Lifecycle.PER_CLASS); whereas, factory methods in external classes must always be static. In addition, such factory methods must not accept any arguments.
If you only need a single parameter, you can return a Stream of instances of the parameter type as demonstrated in the following example.
@ParameterizedTest(name = "#{index} - Test with String : {0}")
@MethodSource("stringProvider")
void test_method_string(String arg) {
assertNotNull(arg);
}
// this need static
static Stream<String> stringProvider() {
return Stream.of("java", "junit5", null);
}
The output of the above program is
If you do not explicitly provide a factory method name via @MethodSource, JUnit Jupiter will search for a factory method that has the same name as the current @ParameterizedTest method by convention. This is demonstrated in the following example.
@ParameterizedTest(name = "#{index} - Test with String : {0}")
@MethodSource
void test_no_factory_methodname(String arg) {
assertNotNull(arg);
}
static Stream<String> test_no_factory_methodname() {
return Stream.of("java", "junit5", null);
}
The output of the above program is
Streams for primitive types (DoubleStream, IntStream, and LongStream) are also supported as demonstrated by the following example.
@ParameterizedTest(name = "#{index} - Test with Int : {0}")
@MethodSource("rangeProvider")
void test_method_int(int arg) {
assertTrue(arg < 6);
}
static IntStream rangeProvider() {
return IntStream.range(0, 6);
}
The output of the above program is
If a parameterized test method declares multiple parameters, you need to return a collection, stream, or array of Arguments instances or object arrays as shown below.
@ParameterizedTest
@MethodSource("stringIntAndListProvider")
void testWithMultiArgMethodSource(String str, int num, List<String> list) {
assertEquals(5, str.length());
assertTrue(num >=1 && num <=2);
assertEquals(2, list.size());
}
static Stream<Arguments> stringIntAndListProvider() {
return Stream.of(
arguments("apple", 1, Arrays.asList("a", "b")),
arguments("lemon", 2, Arrays.asList("x", "y"))
);
}
The output of the above program is
4. @CsvSource
@CsvSource allows you to express argument lists as comma-separated values (i.e., CSV String literals). Each string provided via the value attribute in @CsvSource represents a CSV record and results in one invocation of the parameterized test.
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import static org.junit.jupiter.api.Assertions.assertEquals;
public class CSVParameterizedTest {
@ParameterizedTest
@CsvSource({
"java, 4",
"javascript, 7",
"python, 6",
"HTML, 4",
})
void test(String str, int length) {
assertEquals(length, str.length());
}
}
The output of the above program is
5. @CsvFileSource
@CsvFileSource lets us use comma-separated value (CSV) files from the classpath or the local file system. Each record from a CSV file results in one invocation of the parameterized test. The first record may optionally be used to supply CSV headers.
csvdemo.csv
@ParameterizedTest
@CsvFileSource(resources = "/csvdemo.csv")
void testLength(String str, int length) {
Assertions.assertEquals(length, str.length());
}
The output of the above program is
csv file with the heading
JUnit can ignore the headers via the numLinesToSkip attribute.
@ParameterizedTest
@CsvFileSource(files = "src/test/resources/csvdemo.csv",numLinesToSkip = 1)
void testStringLength(String str, int length) {
Assertions.assertEquals(length, str.length());
}
The output of the above program is
If you would like the headers to be used in the display names, you can set the useHeadersInDisplayName attribute to true. The examples below demonstrate the use of useHeadersInDisplayName.
@ParameterizedTest(name = "[{index}] {arguments}")
@CsvFileSource(files = "src/test/resources/csvdemo.csv",useHeadersInDisplayName = true)
void testStringLength1(String str, int length) {
assertEquals(length, str.length());
}
The output of the above program is
6. @ArgumentsSource
@ArgumentsSource can be used to specify a custom, reusable ArgumentsProvider. Note that an implementation of ArgumentsProvider must be declared as either a top-level class or as a static nested class.
import org.junit.jupiter.api.extension.ExtensionContext;
import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.ArgumentsProvider;
import java.util.stream.Stream;
public class CustomArgumentsProvider implements ArgumentsProvider {
@Override
public Stream<? extends Arguments>
provideArguments(ExtensionContext extensionContext) throws Exception {
return Stream.of("java", "junit5", "junit4", null).map(Arguments::of);
}
}
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ArgumentsSource;
import static org.junit.jupiter.api.Assertions.assertNotNull;
public class ArgumentsSourceTest {
@ParameterizedTest
@ArgumentsSource(CustomArgumentsProvider.class)
void test_argument_custom(String arg) {
assertNotNull(arg);
}
}
The output of the above program is
Congratulation. We have understood parameterization in JUnit5 tests. Happy Learning!!
QA Automation Expert 