Junit5中的参数化测试（Parameterized Tests）指南

作为新一代的测试框架，Junit5中有很多大家喜欢的测试方案，个人认为最突出的就是能够进行参数化的测试（Parameterized Tests）。

简介

通常，会遇到这样的情况，同一个测试案例，改变的只是测试时候输入的参数不同。按照之前的做法，可能会是通过每个输入参数都写一个测试，或者将测试参数封装到集合中循环遍历执行测试。在新版的Junit5中，已经提供了一种更加优雅的方式来进行。

该特性允许我们：该特性可以让我们运行单个测试多次，且使得每次运行仅仅是参数不同而已。

安装依赖

为了使用 JUnit 5 的参数化测试（parameterized tests）。需要在Junit Platform的基础上，导入而外的 junit-jupiter-params 架包。

maven:

<dependency><groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter-params</artifactId><version>5.4.2</version><scope>test</scope>
</dependency>

Gradle:

testCompile("org.junit.jupiter:junit-jupiter-params:5.4.2")

简单的案例

比如，需要测试一个函数是判断输入值否为基数。

public class Numbers {public static boolean isOdd(int number) {return number % 2 != 0;}
}

通过Parameterized Test，则可以写成如下的形式：

@ParameterizedTest
@ValueSource(ints = {1, 3, 5, -3, 15, Integer.MAX_VALUE}) // six numbers
void isOdd_ShouldReturnTrueForOddNumbers(int number) {assertTrue(Numbers.isOdd(number));
}

JUnit5 将会执行上面的测试6次，每次都会分配来之*@ValueSource*中不同的int参数.

如何定义不同参数的来源

上面简单的展示了如何通过不同的参数来运行同一个测试。但是很多时候并不仅仅是Int类型。

简单值 Simple Value

@ValueSource 可以往测试方法中传递一个数据或者迭代器。可支持的简单参数如下：

short (with the shorts attribute)
byte (with the bytes attribute)
int (with the ints attribute)
long (with the longs attribute)
float (with the floats attribute)
double (with the doubles attribute)
char (with the chars attribute)
java.lang.String (with the strings attribute)
java.lang.Class (with the classes attribute)

值得注意的是，@ValueSource不允许传入Null值和Empty值。从JUnit 5.4开始，我们可以使用@NullSource、@EmptySource 和 @NullAndEmptySource 注解可以分别将单个null值、单个Empty和 Null和Empty 传递给参数化测试方法。

枚举类 Enum

为了运行将一个枚举类的所有的值传入到测试中，可以使用 @EnumSource注解。比如使用枚举类Month

@ParameterizedTest
@EnumSource(Month.class) // passing all 12 months
void getValueForAMonth_IsAlwaysBetweenOneAndTwelve(Month month) {int monthNumber = month.getValue();assertTrue(monthNumber >= 1 && monthNumber <= 12);
}

或者通过names可以过滤掉一些某些枚举类

@ParameterizedTest
@EnumSource(value = Month.class, names = {"APRIL", "JUNE", "SEPTEMBER", "NOVEMBER"})
void someMonths_Are30DaysLong(Month month) {final boolean isALeapYear = false;assertEquals(30, month.length(isALeapYear));
}

通常的情况下，会被认为names是对匹配的这些名字的枚举类进行操作，但是通过mode=EXCLUDE属性可以设置为取反。

@ParameterizedTest
@EnumSource(value = Month.class,names = {"APRIL", "JUNE", "SEPTEMBER", "NOVEMBER", "FEBRUARY"},mode = EnumSource.Mode.EXCLUDE)
void exceptFourMonths_OthersAre31DaysLong(Month month) {final boolean isALeapYear = false;assertEquals(31, month.length(isALeapYear));
}

另外，也可以通过在names属性上增加正则表达式来操作这些迭代的字符串。

@ParameterizedTest
@EnumSource(value = Month.class, names = ".+BER", mode = EnumSource.Mode.MATCH_ANY)
void fourMonths_AreEndingWithBer(Month month) {EnumSet<Month> months =EnumSet.of(Month.SEPTEMBER, Month.OCTOBER, Month.NOVEMBER, Month.DECEMBER);assertTrue(months.contains(month));
}

CSV(最常用)

很多时候，需要同时传入参数和预期结果，来验证测试逻辑。比如，需要去测试toUpperCase()方法（能够将预期的String字符串转换成预期的大写字母字符串）。

@ParameterizedTest
@CsvSource({"test,TEST", "tEst,TEST", "Java,JAVA"})
void toUpperCase_ShouldGenerateTheExpectedUppercaseValue(String input, String expected) {String actualValue = input.toUpperCase();assertEquals(expected, actualValue);
}

其中 @CsvSource 注解接受一个以逗号分隔的数组，并且每个数组项都对应于CSV文件中的一行。该注解包含了一个 delimiter 属性，可以用来定义分割符（默认是逗号）。

CSV Files

同前面的CSV一样，只是把参数写到具体的CSV文件存储起来。通过@CsvFileSource注解说明文件路径。

@ParameterizedTest
@CsvFileSource(resources = "/data.csv", numLinesToSkip = 1)
void toUpperCase_ShouldGenerateTheExpectedUppercaseValueCSVFile(String input, String expected) {String actualValue = input.toUpperCase();assertEquals(expected, actualValue);
}

通常情况下，@CsvFileSource注解回去解析每一行，但有些时候，第一行可能会是列名，所以在上面的方法中加上了numLinesToSkip 属性来跳过第一行。

方法 Method

通过@MethodSource注解可以传递一些复杂的迭代对象到测试中。

@ParameterizedTest
@MethodSource("provideStringsForIsBlank")
void isBlank_ShouldReturnTrueForNullOrBlankStrings(String input, boolean expected) {assertEquals(expected, Strings.isBlank(input));
}

其中@MethodSource 注解需要匹配现有存在方法，通常会在同测试类中查询该方法，如果不在同测试类文件下，则需要加上方法名的全限定名。比如下面例子

class StringsUnitTest {@ParameterizedTest@MethodSource("com.baeldung.parameterized.StringParams#blankStrings")void isBlank_ShouldReturnTrueForNullOrBlankStringsExternalSource(String input) {assertTrue(Strings.isBlank(input));}
}public class StringParams {static Stream<String> blankStrings() {return Stream.of(null, "", "  ");}
}

自定义参数提供器 Custom Argument Provider

通过实现ArgumentsProvider接口可以使用一些更加高级的方式去传递参数。比如

class BlankStringsArgumentsProvider implements ArgumentsProvider {@Overridepublic Stream<? extends Arguments> provideArguments(ExtensionContext context) {return Stream.of(Arguments.of((String) null), Arguments.of(""), Arguments.of("   ") );}
}

然后在实际的测试类中引用上面的自定义参数提供器。

@ParameterizedTest
@ArgumentsSource(BlankStringsArgumentsProvider.class)
void isBlank_ShouldReturnTrueForNullOrBlankStringsArgProvider(String input) {assertTrue(Strings.isBlank(input));
}

如何自定义注解

前面的都是Junit 参数化解析框架提供的注解，也可以自定义一些参数注解，以一种更加优美的方式来实现参数化得测试。比如，想实现一个从静态变量里面加载测试参数的注解。类似于如下的代码。

static Stream<Arguments> arguments = Stream.of(Arguments.of(null, true), // null strings should be considered blankArguments.of("", true),Arguments.of("  ", true),Arguments.of("not blank", false)
);@ParameterizedTest
@VariableSource("arguments")
void isBlank_ShouldReturnTrueForNullOrBlankStringsVariableSource(String input, boolean expected) {assertEquals(expected, Strings.isBlank(input));
}

JUnit5 提供了如下的两个基类来帮助我们实现。一个用来实现注解细节，一个用来提供测试参数。

AnnotationConsumer 基类提供注解细节
ArgumentsProvider 基类提供测试的参数

实际的实现如下：

class VariableArgumentsProvider implements ArgumentsProvider, AnnotationConsumer<VariableSource> {private String variableName;@Overridepublic Stream<? extends Arguments> provideArguments(ExtensionContext context) {return context.getTestClass().map(this::getField).map(this::getValue).orElseThrow(() -> new IllegalArgumentException("Failed to load test arguments"));}@Overridepublic void accept(VariableSource variableSource) {variableName = variableSource.value();}private Field getField(Class<?> clazz) {try {return clazz.getDeclaredField(variableName);} catch (Exception e) {return null;}}@SuppressWarnings("unchecked")private Stream<Arguments> getValue(Field field) {Object value = null;try {value = field.get(null);} catch (Exception ignored) {}return value == null ? null : (Stream<Arguments>) value;}
}

参数的类型转换

隐式转换

假设通过@CsvSource 注解来重写了前面@EmumTests 测试。在@CSVSource中通过传入字符串，而不是枚举类。

@ParameterizedTest
@CsvSource({"APRIL", "JUNE", "SEPTEMBER", "NOVEMBER"}) // Pssing strings
void someMonths_Are30DaysLongCsv(Month month) {final boolean isALeapYear = false;assertEquals(30, month.length(isALeapYear));
}

按理来说是应该失败的，但是实际运行你会发现，它能够正常的运行。

因为Junit5默认会对字符串进行隐式的转换。String默认可以转换成如下的几种类型

UUID
Locale
LocalDate, LocalTime, LocalDateTime, Year, Month, etc.
File and Path
URL and URI
Enum subclasses

显式转换

有些时候，需要提供一种自定义的显式参数类型转换器。例如，想将 yyyy/mm/dd 格式的字符串数据转换成LocalDate实例。

第一步是实现 ArgumentConverter接口

class SlashyDateConverter implements ArgumentConverter {@Overridepublic Object convert(Object source, ParameterContext context)throws ArgumentConversionException {if (!(source instanceof String)) {throw new IllegalArgumentException("The argument should be a string: " + source);}try {String[] parts = ((String) source).split("/");int year = Integer.parseInt(parts[0]);int month = Integer.parseInt(parts[1]);int day = Integer.parseInt(parts[2]);return LocalDate.of(year, month, day);} catch (Exception e) {throw new IllegalArgumentException("Failed to convert", e);}}
}

然后通过 @ConvertWith 注解来引用指定的转换器。

@ParameterizedTest
@CsvSource({"2018/12/25,2018", "2019/02/11,2019"})
void getYear_ShouldWorkAsExpected(@ConvertWith(SlashyDateConverter.class) LocalDate date, int expected) {assertEquals(expected, date.getYear());
}

参数存取器

通常情况下，一个测试参数，会对应一个形参参数。但是当通过一个参数源传递多个参数的时候，则有些时候就会显得很大和混乱。这时候，可以通过一个参数存取器 ArgumentsAccessor来聚合这些参数，然后在使用的时候，根据索引来获得。比如，想测试下面的Person类中的 fullName方法

class Person {String firstName;String middleName;String lastName;// constructorpublic String fullName() {if (middleName == null || middleName.trim().isEmpty()) {return String.format("%s %s", firstName, lastName);}return String.format("%s %s %s", firstName, middleName, lastName);}
}

如果想测试fullName方法，则需要传入 firstName, middleName, lastName, 和 the expected fullName.。我们不通过定义不同的测试形参参数，而是通过 ArgumentsAccessor来解析这些测试参数。

@ParameterizedTest
@CsvSource({"Isaac,,Newton,Isaac Newton", "Charles,Robert,Darwin,Charles Robert Darwin"})
void fullName_ShouldGenerateTheExpectedFullName(ArgumentsAccessor argumentsAccessor) {String firstName = argumentsAccessor.getString(0);String middleName = (String) argumentsAccessor.get(1);String lastName = argumentsAccessor.get(2, String.class);String expectedFullName = argumentsAccessor.getString(3);Person person = new Person(firstName, middleName, lastName);assertEquals(expectedFullName, person.fullName());
}

（讲道理，没有看出太大的优势）好处就是将所有的参数都聚合存储在一起，并且通过下面定义的几个方法来解析。

getString(index) 直接通过索引解析了具体的值，成字符串。（返回类型就是String）
get(index) 简单通过索引元素解析成 Object对象
get(index, type) 将指定的索引元素解析成指定的类型对象 type

参数聚合器

使用前面的参数存取器 ArgumentsAccessor可能会使得代码缺少可读性和复用性。可以提通过自定义一个aggregator来实现。

首先就是实现 ArgumentsAggregator接口

class PersonAggregator implements ArgumentsAggregator {@Overridepublic Object aggregateArguments(ArgumentsAccessor accessor, ParameterContext context)throws ArgumentsAggregationException {return new Person(accessor.getString(1), accessor.getString(2), accessor.getString(3));}
}

然后通过指定 @AggregateWith 注解来引用

@ParameterizedTest
@CsvSource({"Isaac Newton,Isaac,,Newton", "Charles Robert Darwin,Charles,Robert,Darwin"})
void fullName_ShouldGenerateTheExpectedFullName(String expectedFullName,@AggregateWith(PersonAggregator.class) Person person) {assertEquals(expectedFullName, person.fullName());
}

上面的 PersonAggregator用例中，聚合了最后的3个参数，并且实例化出了一个Person对象。

自定义显式名称 Customizing Display Names

默认情况下，测试运行之后显式的测试名如下

├─ someMonths_Are30DaysLongCsv(Month)
│     │  ├─ [1] APRIL
│     │  ├─ [2] JUNE
│     │  ├─ [3] SEPTEMBER
│     │  └─ [4] NOVEMBER

但是我们可以通过 @ParameterizedTest 注解中的 name 属性来自定义显示名称。例如

@ParameterizedTest(name = "{index} {0} is 30 days long")
@EnumSource(value = Month.class, names = {"APRIL", "JUNE", "SEPTEMBER", "NOVEMBER"})
void someMonths_Are30DaysLong(Month month) {final boolean isALeapYear = false;assertEquals(30, month.length(isALeapYear));
}

显示的’ April is 30 days long’ 可能更加的表意。

在自定义显示名下，可以使用下面的几个占位符。

{index} 表示调用索引，从1开始，然后2，3等
{arguments} 表示完整的参数列表，以逗号分隔。
**{0}, {1}, …****.*表示单个参数名称。

总结

Junit5 会越来越流行，上面的相关源代码请参考 tutorials/testing-modules/junit5-annotations at master · eugenp/tutorials。

参考文档

https://www.baeldung.com/parameterized-tests-junit-5