Repeated and dynamic tests
Two kinds of test do not fit a fixed list of arguments. A repeated test runs the same body a number of times, for a race or a randomised input. A dynamic test factory builds its cases at run time from a stream. Both appear as ordinary tests in the report, one line per repetition or per dynamic case.
@RepeatedTest
@RepeatedTest(3) runs the method three times. Each run is a separate test in the report, named repetition 1 of 3 and so on. The method may take a RepetitionInfo parameter when it needs to know which run it is.
The repetitions are not a loop with one verdict: a failure in the second run is one failed test while the first and third can still pass. That is the point for a test of a concurrent queue or a random generator, where the same code must hold more than once.
@TestFactory
A factory method is marked @TestFactory and returns a stream of DynamicTest. Jupiter runs the method once, reads the stream, and runs every element as a test. The cases can be built from a file, a list or a computation; the method is ordinary Java, so a loop is enough.
DynamicTest
DynamicTest.dynamicTest(name, executable) gives a case its name and its body. The name is a string, so it can include the value the case is about. The body is an Executable, the same functional interface that assertAll uses.
import static org.junit.jupiter.api.Assertions.assertEquals;
import java.util.stream.Stream;
import org.junit.jupiter.api.DynamicTest;
import org.junit.jupiter.api.RepeatedTest;
import org.junit.jupiter.api.TestFactory;
public class RepeatTest {
@RepeatedTest(3)
void stableSum() {
assertEquals(4, 2 + 2);
}
@TestFactory
Stream<DynamicTest> lengths() {
return Stream.of("a", "bb").map(text -> DynamicTest.dynamicTest(
"length of " + text,
() -> assertEquals(text.length(), text.length())));
}
}
The report
javac -Xlint:all -cp /opt/java-tools/junit-platform-console-standalone.jar -d out RepeatTest.java
junit execute --class-path out --scan-classpath --disable-ansi-colors
Thanks for using JUnit! Support its development at https://junit.org/sponsoring
╷
├─ JUnit Platform Suite ✔
├─ JUnit Jupiter ✔
│ └─ RepeatTest ✔
│ ├─ lengths() ✔
│ │ ├─ length of a ✔
│ │ └─ length of bb ✔
│ └─ stableSum() ✔
│ ├─ repetition 1 of 3 ✔
│ ├─ repetition 2 of 3 ✔
│ └─ repetition 3 of 3 ✔
└─ JUnit Vintage ✔
Test run finished after 917 ms
[ 6 containers found ]
[ 0 containers skipped ]
[ 6 containers started ]
[ 0 containers aborted ]
[ 6 containers successful ]
[ 0 containers failed ]
[ 5 tests found ]
[ 0 tests skipped ]
[ 5 tests started ]
[ 0 tests aborted ]
[ 5 tests successful ]
[ 0 tests failed ]
Two dynamic cases and three repetitions make five tests. Six containers are the platform, Jupiter, the class, the factory, and the two repeated or factory groups; the exact count is the launcher's, and the table is the authority. A dynamic case is a test, not a container, and its name is the one the factory gave it.
When to use them
A parameterised test is still the first choice for a table of cases: the values are visible in the source and the report names them. A factory is for cases that only exist at run time, such as the files of a folder or the rows of a query. A repeated test is for a property that must hold more than once, not for a loop that would be clearer as one test.
Both forms are part of Jupiter and need no extra jar. A factory can return an empty stream, and the method is then a container with no tests; that is legal, and the counts table shows one fewer test than the reader might expect.
Exercises
- Change the repetition count to 5 and predict the counts before you run.
- Add a third string to the factory stream. Which line appears in the tree?
- Make the factory return an empty stream. What does the report say about the method?
- Add a RepetitionInfo parameter and print the current repetition. Where does the print appear?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
How many tests does
@RepeatedTest(3)add to the counts?Answer
3, one per repetition
Every repetition is a separate test with its own verdict.
-
What does a
@TestFactorymethod return?Answer
A stream of DynamicTest
Jupiter runs every DynamicTest in the returned stream as a test.
-
When is a factory better than a parameterised test?
Answer
When the cases are known only at run time
A factory builds cases from data the source cannot know, such as files or query rows.
-
What does this program print?
public class Q1 { public static void main(String[] args) { int count = 0; for (int n = 1; n != 4; n++) { count++; } System.out.println(count); } }Answer
3
The loop runs for 1, 2 and 3, so count is 3.
-
What does this program print?
public class Q2 { public static void main(String[] args) { System.out.println("bb".length()); } }Answer
2
The string has two characters.
-
What does this program print?
public class Q3 { public static void main(String[] args) { System.out.println(java.util.stream.Stream.of("a", "b", "c").count()); } }Answer
3
The stream has three elements, so count is 3.
-
What does this program print?
public class Q4 { public static void main(String[] args) { String text = "length of a"; System.out.println(text.contains("of")); } }Answer
true
The text contains the substring of, so contains is true.
-
What does a failure in repetition 2 do to repetitions 1 and 3?
Answer
They keep their own verdicts
Each repetition is its own test, so the others are unaffected.
-
What does this program print?
public class Q5 { public static void main(String[] args) { int total = 0; for (int n : new int[] {1, 2}) { total += n; } System.out.println(total); } }Answer
3
The loop adds 1 and 2, so the total is 3.
-
How is a dynamic test named in the report?
Answer
By the name passed to DynamicTest.dynamicTest
The factory chooses the name, and the tree prints it as the case line.
The code on this page was built with OpenJDK 21.0.13 (javac) and run with JUnit Platform Console Launcher 1.14.3 on Alpine Linux in a Docker container.
Article author: Arthur Isaev