引數化測試一直是津津樂道的話題，我們都知道JMeter有四種引數化方式：使用者自定義變數、使用者引數、CSV檔案、函式助手，那麼JUnit5有哪些引數化測試的方式呢？

依賴

JUnit5需要新增junit-jupiter-params依賴才能使用引數化：

  1. <dependency>
  2.     <groupId>org.junit.jupiter</groupId>
  3.     <artifactId>junit-jupiter-params</artifactId>
  4.     <version>5.7.2</version>
  5.     <scope>test</scope>
  6. </dependency>

簡單示例

@ParameterizedTest用來定義引數化測試，@ValueSource用來定義引數值：

  1. @ParameterizedTest
  2. @ValueSource(strings = { "racecar", "radar", "able was I ere I saw elba" })
  3. void palindromes(String candidate) {
  4.     assertTrue(StringUtils.isPalindrome(candidate));
  5. }

執行結果：

  1. palindromes(String)
  2. ├─ [1] candidate=racecar
  3. ├─ [2] candidate=radar
  4. └─ [3] candidate=able was I ere I saw elba

引數值會匹配測試方法的引數列表，然後依次賦值，這裡一共產生了3個測試。

七種方式

1 @ValueSource

@ValueSource是最簡單的引數化方式，它是一個數組，支援以下資料型別：

  • short
  • byte
  • int
  • long
  • float
  • double
  • char
  • boolean
  • java.lang.String
  • java.lang.Class

示例：

  1. @ParameterizedTest
  2. @ValueSource(ints = { 1, 2, 3 })
  3. void testWithValueSource(int argument) {
  4.     assertTrue(argument > 0 && argument < 4);
  5. }

2 Null and Empty Sources

  • @NullSource 值為null

    不能用在基元型別的測試方法。

  • @EmptySource 值為空，根據測試方法的引數類決定資料型別，支援java.lang.String, java.util.List, java.util.Set, java.util.Map, 基元型別陣列 (int[], char[][]等), 物件陣列 (String[], Integer[][]等)

  • @NullAndEmptySource 結合了前面兩個

示例：

  1. @ParameterizedTest
  2. @NullSource
  3. @EmptySource
  4. @ValueSource(strings = { " ", "   ", "\t", "\n" })
  5. void nullEmptyAndBlankStrings(String text) {
  6.     assertTrue(text == null || text.trim().isEmpty());
  7. }

等價於：

  1. @ParameterizedTest
  2. @NullAndEmptySource
  3. @ValueSource(strings = { " ", "   ", "\t", "\n" })
  4. void nullEmptyAndBlankStrings(String text) {
  5.     assertTrue(text == null || text.trim().isEmpty());
  6. }

3 @EnumSource

引數化的值為列舉型別。

示例：

  1. @ParameterizedTest
  2. @EnumSource
  3. void testWithEnumSourceWithAutoDetection(ChronoUnit unit) {
  4.     assertNotNull(unit);
  5. }

其中的ChronoUnit是個日期列舉類。

ChronoUnit是介面TemporalUnit的實現類，如果測試方法的引數為TemporalUnit，那麼需要給@EnumSource加上值：

  1. @ParameterizedTest
  2. @EnumSource(ChronoUnit.class)
  3. void testWithEnumSource(TemporalUnit unit) {
  4.     assertNotNull(unit);
  5. }

因為JUnit5規定了@EnumSource的預設值的型別必須是列舉型別。

names屬性用來指定使用哪些特定的列舉值：

  1. @ParameterizedTest
  2. @EnumSource(names = { "DAYS", "HOURS" })
  3. void testWithEnumSourceInclude(ChronoUnit unit) {
  4.     assertTrue(EnumSet.of(ChronoUnit.DAYS, ChronoUnit.HOURS).contains(unit));
  5. }

mode屬性用來指定使用模式，比如排除哪些列舉值：

  1. @ParameterizedTest
  2. @EnumSource(mode = EXCLUDE, names = { "ERAS", "FOREVER" })
  3. void testWithEnumSourceExclude(ChronoUnit unit) {
  4.     assertFalse(EnumSet.of(ChronoUnit.ERAS, ChronoUnit.FOREVER).contains(unit));
  5. }

比如採用正則匹配：

  1. @ParameterizedTest
  2. @EnumSource(mode = MATCH_ALL, names = "^.*DAYS$")
  3. void testWithEnumSourceRegex(ChronoUnit unit) {
  4.     assertTrue(unit.name().endsWith("DAYS"));
  5. }

4 @MethodSource

引數值為factory方法，並且factory方法不能帶引數。

示例：

  1. @ParameterizedTest
  2. @MethodSource("stringProvider")
  3. void testWithExplicitLocalMethodSource(String argument) {
  4.     assertNotNull(argument);
  5. }
  7. static Stream<String> stringProvider() {
  8.     return Stream.of("apple", "banana");
  9. }

除非是@TestInstance(Lifecycle.PER_CLASS)生命週期，否則factory方法必須是static。factory方法的返回值是能轉換為Stream的型別，比如Stream, DoubleStream, LongStream, IntStream, Collection, Iterator, Iterable, 物件陣列, 或者基元型別陣列，比如：

  1. @ParameterizedTest
  2. @MethodSource("range")
  3. void testWithRangeMethodSource(int argument) {
  4.     assertNotEquals(9, argument);
  5. }
  7. static IntStream range() {
  8.     return IntStream.range(0, 20).skip(10);
  9. }

@MethodSource的屬性如果省略了，那麼JUnit Jupiter會找跟測試方法同名的factory方法，比如：

  1. @ParameterizedTest
  2. @MethodSource
  3. void testWithDefaultLocalMethodSource(String argument) {
  4.     assertNotNull(argument);
  5. }
  7. static Stream<String> testWithDefaultLocalMethodSource() {
  8.     return Stream.of("apple", "banana");
  9. }

如果測試方法有多個引數，那麼factory方法也應該返回多個：

  1. @ParameterizedTest
  2. @MethodSource("stringIntAndListProvider")
  3. void testWithMultiArgMethodSource(String str, int num, List<String> list) {
  4.     assertEquals(5, str.length());
  5.     assertTrue(num >=1 && num <=2);
  6.     assertEquals(2, list.size());
  7. }
  9. static Stream<Arguments> stringIntAndListProvider() {
  10.     return Stream.of(
  11.         arguments("apple", 1, Arrays.asList("a", "b")),
  12.         arguments("lemon", 2, Arrays.asList("x", "y"))
  13.     );
  14. }

其中arguments(Object…)是Arguments介面的static factory method，也可以換成Arguments.of(Object…)。

factory方法也可以防止測試類外部：

  1. package example;
  3. import java.util.stream.Stream;
  5. import org.junit.jupiter.params.ParameterizedTest;
  6. import org.junit.jupiter.params.provider.MethodSource;
  8. class ExternalMethodSourceDemo {
  10.     @ParameterizedTest
  11.     @MethodSource("example.StringsProviders#tinyStrings")
  12.     void testWithExternalMethodSource(String tinyString) {
  13.         // test with tiny string
  14.     }
  15. }
  17. class StringsProviders {
  19.     static Stream<String> tinyStrings() {
  20.         return Stream.of(".", "oo", "OOO");
  21.     }
  22. }

5 @CsvSource

引數化的值為csv格式的資料（預設逗號分隔），比如：

  1. @ParameterizedTest
  2. @CsvSource({
  3.     "apple,         1",
  4.     "banana,        2",
  5.     "'lemon, lime', 0xF1"
  6. })
  7. void testWithCsvSource(String fruit, int rank) {
  8.     assertNotNull(fruit);
  9.     assertNotEquals(0, rank);
  10. }

delimiter屬性可以設定分隔字元。delimiterString屬性可以設定分隔字串（String而非char）。

更多輸入輸出示例如下：

注意，如果null引用的目標型別是基元型別，那麼會報異常ArgumentConversionException。

6 @CsvFileSource

顧名思義，選擇本地csv檔案作為資料來源。

示例：

  1. @ParameterizedTest
  2. @CsvFileSource(resources = "/two-column.csv", numLinesToSkip = 1)
  3. void testWithCsvFileSourceFromClasspath(String country, int reference) {
  4.     assertNotNull(country);
  5.     assertNotEquals(0, reference);
  6. }
  8. @ParameterizedTest
  9. @CsvFileSource(files = "src/test/resources/two-column.csv", numLinesToSkip = 1)
  10. void testWithCsvFileSourceFromFile(String country, int reference) {
  11.     assertNotNull(country);
  12.     assertNotEquals(0, reference);
  13. }

delimiter屬性可以設定分隔字元。delimiterString屬性可以設定分隔字串（String而非char）。需要特別注意的是，#開頭的行會被認為是註釋而略過。

7 @ArgumentsSource

自定義ArgumentsProvider。

示例：

  1. @ParameterizedTest
  2. @ArgumentsSource(MyArgumentsProvider.class)
  3. void testWithArgumentsSource(String argument) {
  4.     assertNotNull(argument);
  5. }
  1. public class MyArgumentsProvider implements ArgumentsProvider {
  3.     @Override
  4.     public Stream<? extends Arguments> provideArguments(ExtensionContext context) {
  5.         return Stream.of("apple", "banana").map(Arguments::of);
  6.     }
  7. }

MyArgumentsProvider必須是外部類或者static內部類。

引數型別轉換

隱式轉換

JUnit Jupiter會對String型別進行隱式轉換。比如：

  1. @ParameterizedTest
  2. @ValueSource(strings = "SECONDS")
  3. void testWithImplicitArgumentConversion(ChronoUnit argument) {
  4.     assertNotNull(argument.name());
  5. }

更多轉換示例：

也可以把String轉換為自定義物件：

  1. @ParameterizedTest
  2. @ValueSource(strings = "42 Cats")
  3. void testWithImplicitFallbackArgumentConversion(Book book) {
  4.     assertEquals("42 Cats", book.getTitle());
  5. }
  1. public class Book {
  3.     private final String title;
  5.     private Book(String title) {
  6.         this.title = title;
  7.     }
  9.     public static Book fromTitle(String title) {
  10.         return new Book(title);
  11.     }
  13.     public String getTitle() {
  14.         return this.title;
  15.     }
  16. }

JUnit Jupiter會找到Book.fromTitle(String)方法，然後把@ValueSource的值傳入進去，進而把String型別轉換為Book型別。轉換的factory方法既可以是接受單個String引數的構造方法，也可以是接受單個String引數並返回目標型別的普通方法。詳細規則如下（官方原文）：

顯式轉換

顯式轉換需要使用@ConvertWith註解：

  1. @ParameterizedTest
  2. @EnumSource(ChronoUnit.class)
  3. void testWithExplicitArgumentConversion(
  4.         @ConvertWith(ToStringArgumentConverter.class) String argument) {
  6.     assertNotNull(ChronoUnit.valueOf(argument));
  7. }

並實現ArgumentConverter：

  1. public class ToStringArgumentConverter extends SimpleArgumentConverter {
  3.     @Override
  4.     protected Object convert(Object source, Class<?> targetType) {
  5.         assertEquals(String.class, targetType, "Can only convert to String");
  6.         if (source instanceof Enum<?>) {
  7.             return ((Enum<?>) source).name();
  8.         }
  9.         return String.valueOf(source);
  10.     }
  11. }

如果只是簡單型別轉換，實現TypedArgumentConverter即可：

  1. public class ToLengthArgumentConverter extends TypedArgumentConverter<String, Integer> {
  3.     protected ToLengthArgumentConverter() {
  4.         super(String.class, Integer.class);
  5.     }
  7.     @Override
  8.     protected Integer convert(String source) {
  9.         return source.length();
  10.     }
  12. }

JUnit Jupiter只內建了一個JavaTimeArgumentConverter，通過@JavaTimeConversionPattern使用：

  1. @ParameterizedTest
  2. @ValueSource(strings = { "01.01.2017", "31.12.2017" })
  3. void testWithExplicitJavaTimeConverter(
  4.         @JavaTimeConversionPattern("dd.MM.yyyy") LocalDate argument) {
  6.     assertEquals(2017, argument.getYear());
  7. }

引數聚合

測試方法的多個引數可以聚合為一個ArgumentsAccessor引數，然後通過get來取值，示例：

  1. @ParameterizedTest
  2. @CsvSource({
  3.     "Jane, Doe, F, 1990-05-20",
  4.     "John, Doe, M, 1990-10-22"
  5. })
  6. void testWithArgumentsAccessor(ArgumentsAccessor arguments) {
  7.     Person person = new Person(arguments.getString(0),
  8.                                arguments.getString(1),
  9.                                arguments.get(2, Gender.class),
  10.                                arguments.get(3, LocalDate.class));
  12.     if (person.getFirstName().equals("Jane")) {
  13.         assertEquals(Gender.F, person.getGender());
  14.     }
  15.     else {
  16.         assertEquals(Gender.M, person.getGender());
  17.     }
  18.     assertEquals("Doe", person.getLastName());
  19.     assertEquals(1990, person.getDateOfBirth().getYear());
  20. }

也可以自定義Aggregator：

  1. public class PersonAggregator implements ArgumentsAggregator {
  2.     @Override
  3.     public Person aggregateArguments(ArgumentsAccessor arguments, ParameterContext context) {
  4.         return new Person(arguments.getString(0),
  5.                           arguments.getString(1),
  6.                           arguments.get(2, Gender.class),
  7.                           arguments.get(3, LocalDate.class));
  8.     }
  9. }

然後通過@AggregateWith來使用：

  1. @ParameterizedTest
  2. @CsvSource({
  3.     "Jane, Doe, F, 1990-05-20",
  4.     "John, Doe, M, 1990-10-22"
  5. })
  6. void testWithArgumentsAggregator(@AggregateWith(PersonAggregator.class) Person person) {
  7.     // perform assertions against person
  8. }

藉助於組合註解，我們可以進一步簡化程式碼：

  1. @Retention(RetentionPolicy.RUNTIME)
  2. @Target(ElementType.PARAMETER)
  3. @AggregateWith(PersonAggregator.class)
  4. public @interface CsvToPerson {
  5. }
  1. @ParameterizedTest
  2. @CsvSource({
  3.     "Jane, Doe, F, 1990-05-20",
  4.     "John, Doe, M, 1990-10-22"
  5. })
  6. void testWithCustomAggregatorAnnotation(@CsvToPerson Person person) {
  7.     // perform assertions against person
  8. }

自定義顯示名字

引數化測試生成的test，JUnit Jupiter給定了預設名字，我們可以通過name屬性進行自定義。

示例：

  1. @DisplayName("Display name of container")
  2. @ParameterizedTest(name = "{index} ==> the rank of ''{0}'' is {1}")
  3. @CsvSource({ "apple, 1", "banana, 2", "'lemon, lime', 3" })
  4. void testWithCustomDisplayNames(String fruit, int rank) {
  5. }

結果：

  1. Display name of container
  2. ├─ 1 ==> the rank of 'apple' is 1
  3. ├─ 2 ==> the rank of 'banana' is 2
  4. └─ 3 ==> the rank of 'lemon, lime' is 3

注意如果要顯示'apple'，需要使用兩層''apple''，因為name是MessageFormat。

佔位符說明如下：

小結

本文介紹了JUnit5引數化測試的7種方式，分別是@ValueSource，Null and Empty Sources，@EnumSource，@MethodSource，@CsvSource，@CsvFileSource，@ArgumentsSource，比較偏向於Java語法，符合JUnit單元測試框架的特徵。另外還介紹了JUnit Jupiter的引數型別轉換和引數聚合。最後，如果想要自定義引數化測試的名字，可以使用name屬性實現。

參考資料：

https://junit.org/junit5/docs/current/user-guide/#writing-tests-parameterized-tests