Parameterised tests: one method, many cases

Six inputs and one rule should not be six methods. A parameterised test is one method that takes arguments, plus a source that supplies them; the framework calls the method once per case and reports every call with its own mark. The report is the reason to use it: a failure names the case, so a reader knows which input broke the rule without opening the test.

The class under test

Three methods over words: count the vowels, ask whether a word reads the same backwards, and reverse it. All three are pure, which is what makes them a good subject for a table of cases:

public class Words { static int vowels(String word) { int count = 0; for (char c : word.toLowerCase().toCharArray()) { if ("aeiou".indexOf(c) >= 0) { count++; } } return count; } static boolean isPalindrome(String word) { return word.contentEquals(new StringBuilder(word).reverse()); } static String reverse(String word) { return new StringBuilder(word).reverse().toString(); } public static void main(String[] args) { System.out.println("vowels of queue: " + vowels("queue")); System.out.println("level is a palindrome: " + isPalindrome("level")); System.out.println("reverse of abc: " + reverse("abc")); } }

The main is three lines of proof that the class works before any test exists. The tests then take the same three methods and push more inputs through them than the demonstration ever would.

@ValueSource

The simplest source is a list of literals of one type. The method takes one parameter, and the annotation says where the values come from. Two methods below show the two outcomes: a list of palindromes that must be accepted and a list of words that must be refused:

import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertTrue; import java.util.stream.Stream; import org.junit.jupiter.api.MethodOrderer; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.TestMethodOrder; import org.junit.jupiter.params.ParameterizedTest; import org.junit.jupiter.params.provider.Arguments; import org.junit.jupiter.params.provider.CsvSource; import org.junit.jupiter.params.provider.MethodSource; import org.junit.jupiter.params.provider.ValueSource; @TestMethodOrder(MethodOrderer.MethodName.class) public class WordsTest { @ParameterizedTest @ValueSource(strings = {"level", "noon", "ada"}) void readsAPalindrome(String word) { assertTrue(Words.isPalindrome(word)); } @ParameterizedTest @ValueSource(strings = {"java", "code"}) void rejectsANonPalindrome(String word) { assertFalse(Words.isPalindrome(word)); } @ParameterizedTest @CsvSource({"hello,2", "sky,0", "queue,4", "AEIOU,5"}) void countsTheVowels(String word, int expected) { assertEquals(expected, Words.vowels(word)); } @ParameterizedTest @MethodSource("reversals") void reversesTheWord(String word, String reversed) { assertEquals(reversed, Words.reverse(word)); } static Stream<Arguments> reversals() { return Stream.of( Arguments.of("abc", "cba"), Arguments.of("a", "a"), Arguments.of("", "")); } @Test void knowsTheEmptyWord() { assertEquals(0, Words.vowels("")); assertTrue(Words.isPalindrome("")); } }

The last method is a plain @Test in the same class, and that is allowed: a class may mix both kinds. It is there because the empty string is the case that a table of examples forgets, and because a handful of assertions that belong together is clearer as a method than as a one-line case.

@CsvSource

A case with two or more values is a row of comma-separated text, which is the form a spreadsheet exports and a person reads. The method takes one parameter per column, and the types are converted for it: 2 becomes an int because the parameter is one. A quoted field holds a comma, and an empty pair of quotes is the empty string.

The four rows of countsTheVowels are the whole table: hello has two vowels, sky none, queue four and AEIOU five. The expected value is part of the case, so the same method checks four different inputs against four different answers, which a @ValueSource cannot do.

@MethodSource

When a case is not a literal, a static method supplies it. reversals returns a stream of Arguments, each one a row, and the test method names it in the annotation. That is the hook for a case that has to be computed, read from a file or built from an object, and it is the only source that can pass any type at all.

The method must be static unless the test is annotated to use the test instance, and it must return a stream, an iterable or an array. Its name is a string in the annotation, so a rename in a refactoring tool does not update it; a test that fails to find the method reports that as a configuration error before any case runs.

The run

The parameterised annotations live in junit-jupiter-params, which is inside the standalone jar, so the compile has nothing extra to name. The program prints its three lines and the launcher runs the thirteen cases:

javac -Xlint:all -cp /opt/java-tools/junit-platform-console-standalone.jar -d out Words.java WordsTest.java
java -cp out Words

vowels of queue: 4
level is a palindrome: true
reverse of abc: cba

junit execute --class-path out --select-class WordsTest --disable-ansi-colors

Thanks for using JUnit! Support its development at https://junit.org/sponsoring

╷
├─ JUnit Platform Suite ✔
├─ JUnit Jupiter ✔
│ └─ WordsTest ✔
│ ├─ countsTheVowels(String, int) ✔
│ │ ├─ [1] hello, 2 ✔
│ │ ├─ [2] sky, 0 ✔
│ │ ├─ [3] queue, 4 ✔
│ │ └─ [4] AEIOU, 5 ✔
│ ├─ knowsTheEmptyWord() ✔
│ ├─ readsAPalindrome(String) ✔
│ │ ├─ [1] level ✔
│ │ ├─ [2] noon ✔
│ │ └─ [3] ada ✔
│ ├─ rejectsANonPalindrome(String) ✔
│ │ ├─ [1] java ✔
│ │ └─ [2] code ✔
│ └─ reversesTheWord(String, String) ✔
│ ├─ [1] abc, cba ✔
│ ├─ [2] a, a ✔
│ └─ [3] , ✔
└─ JUnit Vintage ✔

Test run finished after 421 ms
[ 8 containers found ]
[ 0 containers skipped ]
[ 8 containers started ]
[ 0 containers aborted ]
[ 8 containers successful ]
[ 0 containers failed ]
[ 13 tests found ]
[ 0 tests skipped ]
[ 13 tests started ]
[ 0 tests aborted ]
[ 13 tests successful ]
[ 0 tests failed ]

The names in the report

Every case is a leaf under its method, numbered in the order of the source and named by its arguments. The empty case is the third line of the reversals: [3] , ✔ is two empty strings and a separator, which is ugly and honest. When a case fails, its line carries the message and the values, and the method above it still shows the number of the case that broke.

Thirteen tests from five methods: three palindromes, two non-palindromes, four vowel tables, three reversals and the one plain test. The counts of containers also grow, because every parameterised method is a container of its cases, and that is why the report reads eight containers and thirteen tests rather than five and five.

What comes next

A table of cases shares one thing with a set of methods: the object it tests is built for every case. The next page is the lifecycle, where a fixture is made before each test and taken down after it, and where a value that is expensive to build is made once for the class.

The Java course covers the same annotations in lesson 127 and the streams that @MethodSource returns in the streams lesson.

The code on this page was compiled with OpenJDK 21.0.13 (javac) and run with the JUnit Platform Console Launcher 1.14.3 on Alpine Linux in a Docker container. The time in the report is that machine's and changes between runs.

Article author: Arthur Isaev

Banner image