JUnit5參數化測試的幾種方式

• 2021 年 7 月 15 日
• 筆記
• JUnit

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

依賴

JUnit5需要添加junit-jupiter-params依賴才能使用參數化：

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

簡單示例

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

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

執行結果：

palindromes(String) ✔
├─ [1] candidate=racecar ✔
├─ [2] candidate=radar ✔
└─ [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

示例：

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

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 結合了前面兩個

示例：

@ParameterizedTest
@NullSource
@EmptySource
@ValueSource(strings = { " ", "   ", "\t", "\n" })
void nullEmptyAndBlankStrings(String text) {
    assertTrue(text == null || text.trim().isEmpty());
}

等價於：

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

3 @EnumSource

參數化的值為枚舉類型。

示例：

@ParameterizedTest
@EnumSource
void testWithEnumSourceWithAutoDetection(ChronoUnit unit) {
    assertNotNull(unit);
}

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

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

@ParameterizedTest
@EnumSource(ChronoUnit.class)
void testWithEnumSource(TemporalUnit unit) {
    assertNotNull(unit);
}

因為JUnit5規定了@EnumSource的默認值的類型必須是枚舉類型。

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

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

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

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

比如採用正則匹配：

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

4 @MethodSource

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

示例：

@ParameterizedTest
@MethodSource("stringProvider")
void testWithExplicitLocalMethodSource(String argument) {
    assertNotNull(argument);
}

static Stream<String> stringProvider() {
    return Stream.of("apple", "banana");
}

除非是@TestInstance(Lifecycle.PER_CLASS)生命周期，否則factory方法必須是static。factory方法的返回值是能轉換為Stream的類型，比如Stream, DoubleStream, LongStream, IntStream, Collection, Iterator, Iterable, 對象數組, 或者基元類型數組，比如：

@ParameterizedTest
@MethodSource("range")
void testWithRangeMethodSource(int argument) {
    assertNotEquals(9, argument);
}

static IntStream range() {
    return IntStream.range(0, 20).skip(10);
}

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

@ParameterizedTest
@MethodSource
void testWithDefaultLocalMethodSource(String argument) {
    assertNotNull(argument);
}

static Stream<String> testWithDefaultLocalMethodSource() {
    return Stream.of("apple", "banana");
}

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

@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"))
    );
}

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

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

package example;

import java.util.stream.Stream;

import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.MethodSource;

class ExternalMethodSourceDemo {

    @ParameterizedTest
    @MethodSource("example.StringsProviders#tinyStrings")
    void testWithExternalMethodSource(String tinyString) {
        // test with tiny string
    }
}

class StringsProviders {

    static Stream<String> tinyStrings() {
        return Stream.of(".", "oo", "OOO");
    }
}

5 @CsvSource

參數化的值為csv格式的數據（默認逗號分隔），比如：

@ParameterizedTest
@CsvSource({
    "apple,         1",
    "banana,        2",
    "'lemon, lime', 0xF1"
})
void testWithCsvSource(String fruit, int rank) {
    assertNotNull(fruit);
    assertNotEquals(0, rank);
}

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

更多輸入輸出示例如下：

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

6 @CsvFileSource

顧名思義，選擇本地csv文件作為數據來源。

示例：

@ParameterizedTest
@CsvFileSource(resources = "/two-column.csv", numLinesToSkip = 1)
void testWithCsvFileSourceFromClasspath(String country, int reference) {
    assertNotNull(country);
    assertNotEquals(0, reference);
}

@ParameterizedTest
@CsvFileSource(files = "src/test/resources/two-column.csv", numLinesToSkip = 1)
void testWithCsvFileSourceFromFile(String country, int reference) {
    assertNotNull(country);
    assertNotEquals(0, reference);
}

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

7 @ArgumentsSource

自定義ArgumentsProvider。

示例：

@ParameterizedTest
@ArgumentsSource(MyArgumentsProvider.class)
void testWithArgumentsSource(String argument) {
    assertNotNull(argument);
}

public class MyArgumentsProvider implements ArgumentsProvider {

    @Override
    public Stream<? extends Arguments> provideArguments(ExtensionContext context) {
        return Stream.of("apple", "banana").map(Arguments::of);
    }
}

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

參數類型轉換

隱式轉換

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

@ParameterizedTest
@ValueSource(strings = "SECONDS")
void testWithImplicitArgumentConversion(ChronoUnit argument) {
    assertNotNull(argument.name());
}

更多轉換示例：

也可以把String轉換為自定義對象：

@ParameterizedTest
@ValueSource(strings = "42 Cats")
void testWithImplicitFallbackArgumentConversion(Book book) {
    assertEquals("42 Cats", book.getTitle());
}

public class Book {

    private final String title;

    private Book(String title) {
        this.title = title;
    }

    public static Book fromTitle(String title) {
        return new Book(title);
    }

    public String getTitle() {
        return this.title;
    }
}

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

顯式轉換

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

@ParameterizedTest
@EnumSource(ChronoUnit.class)
void testWithExplicitArgumentConversion(
        @ConvertWith(ToStringArgumentConverter.class) String argument) {

    assertNotNull(ChronoUnit.valueOf(argument));
}

並實現ArgumentConverter：

public class ToStringArgumentConverter extends SimpleArgumentConverter {

    @Override
    protected Object convert(Object source, Class<?> targetType) {
        assertEquals(String.class, targetType, "Can only convert to String");
        if (source instanceof Enum<?>) {
            return ((Enum<?>) source).name();
        }
        return String.valueOf(source);
    }
}

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

public class ToLengthArgumentConverter extends TypedArgumentConverter<String, Integer> {

    protected ToLengthArgumentConverter() {
        super(String.class, Integer.class);
    }

    @Override
    protected Integer convert(String source) {
        return source.length();
    }

}

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

@ParameterizedTest
@ValueSource(strings = { "01.01.2017", "31.12.2017" })
void testWithExplicitJavaTimeConverter(
        @JavaTimeConversionPattern("dd.MM.yyyy") LocalDate argument) {

    assertEquals(2017, argument.getYear());
}

參數聚合

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

@ParameterizedTest
@CsvSource({
    "Jane, Doe, F, 1990-05-20",
    "John, Doe, M, 1990-10-22"
})
void testWithArgumentsAccessor(ArgumentsAccessor arguments) {
    Person person = new Person(arguments.getString(0),
                               arguments.getString(1),
                               arguments.get(2, Gender.class),
                               arguments.get(3, LocalDate.class));

    if (person.getFirstName().equals("Jane")) {
        assertEquals(Gender.F, person.getGender());
    }
    else {
        assertEquals(Gender.M, person.getGender());
    }
    assertEquals("Doe", person.getLastName());
    assertEquals(1990, person.getDateOfBirth().getYear());
}

也可以自定義Aggregator：

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

然後通過@AggregateWith來使用：

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

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

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.PARAMETER)
@AggregateWith(PersonAggregator.class)
public @interface CsvToPerson {
}

@ParameterizedTest
@CsvSource({
    "Jane, Doe, F, 1990-05-20",
    "John, Doe, M, 1990-10-22"
})
void testWithCustomAggregatorAnnotation(@CsvToPerson Person person) {
    // perform assertions against person
}

自定義顯示名字

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

示例：

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

結果：

Display name of container ✔
├─ 1 ==> the rank of 'apple' is 1 ✔
├─ 2 ==> the rank of 'banana' is 2 ✔
└─ 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屬性實現。

參考資料：

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