JUnit 5 Dynamic Tests: @TestFactory, DynamicTest.stream(), and Runtime Test Generation
@TestFactory in JUnit 5 generates test cases at runtime instead of compile time. Unlike @ParameterizedTest (same test, different inputs), dynamic tests can have entirely different names, structure, and behavior. They're generated from a factory method that returns a Stream, Collection, or Iterable of DynamicTest objects. This post covers DynamicTest.stream(), DynamicContainer for nested dynamic tests, generating from external data sources, and when to choose dynamic tests over parameterized tests.
Most tests are static: you write them, they compile, they run. But some test scenarios are only fully known at runtime — the set of test cases comes from a database, a file, an API, or computed logic that depends on runtime conditions.
JUnit 5's @TestFactory solves this. It's a method that produces test cases dynamically, at runtime, and returns them as a stream. The test count isn't fixed at compile time. The test names aren't fixed at compile time. Even the test logic can vary per case.
Static Tests vs. Dynamic Tests vs. Parameterized Tests
These three mechanisms solve related but different problems:
@Test: One test, one behavior, fixed at compile time.
@ParameterizedTest: One test template, multiple input sets, fixed at compile time. Same assertions, different data.
@TestFactory: N tests, potentially different behavior per test, generated at runtime. Test count, names, and logic can all vary based on runtime data.
The line between parameterized and dynamic blurs in practice. Use dynamic tests when:
- Test cases come from an external source (file, database, API)
- Test names must be computed from data
- Test structure varies between cases (not just inputs)
- The number of test cases isn't known at compile time
Basic @TestFactory
A @TestFactory method must return a Stream, Collection, Iterable, or Iterator of DynamicNode objects (either DynamicTest or DynamicContainer):
import org.junit.jupiter.api.DynamicTest;
import org.junit.jupiter.api.TestFactory;
import java.util.stream.Stream;
class MathOperationsTest {
@TestFactory
Stream<DynamicTest> squareRoot_shouldReturnCorrectValues() {
return Stream.of(
new double[]{0, 0},
new double[]{1, 1},
new double[]{4, 2},
new double[]{9, 3},
new double[]{16, 4},
new double[]{100, 10}
).map(data -> DynamicTest.dynamicTest(
"sqrt(" + data[0] + ") should be " + data[1],
() -> assertEquals(data[1], Math.sqrt(data[0]), 0.001)
));
}
}Each DynamicTest has a display name and an executable (the test body). The factory returns 6 tests with computed names. Test output:
✓ sqrt(0.0) should be 0.0
✓ sqrt(1.0) should be 1.0
✓ sqrt(4.0) should be 2.0
✓ sqrt(9.0) should be 3.0
✓ sqrt(16.0) should be 4.0
✓ sqrt(100.0) should be 10.0DynamicTest.stream() for Concise Generation
DynamicTest.stream() is a static factory method designed for the common case: iterate over inputs, name each test, run an assertion:
@TestFactory
Stream<DynamicTest> isValidEmail_shouldAcceptValidAddresses() {
List<String> validEmails = List.of(
"user@example.com",
"user+tag@example.com",
"user.name@subdomain.example.co.uk",
"123@example.com",
"user@[192.168.1.1]"
);
return DynamicTest.stream(
validEmails.iterator(),
email -> "Should accept: " + email, // display name function
email -> assertTrue(EmailValidator.isValid(email)) // test body
);
}DynamicTest.stream() takes three arguments: an iterator, a display-name function, and an executable function. It produces one DynamicTest per element.
Pair it with a test for invalid cases:
@TestFactory
Stream<DynamicTest> isValidEmail_shouldRejectInvalidAddresses() {
List<String> invalidEmails = List.of(
"notanemail",
"@missinglocal.com",
"missing@tld",
"two@@signs.com",
""
);
return DynamicTest.stream(
invalidEmails.iterator(),
email -> "Should reject: \"" + email + "\"",
email -> assertFalse(EmailValidator.isValid(email))
);
}Generating from External Data
Dynamic tests really shine when test data comes from external sources. Here's loading test cases from a CSV file:
@TestFactory
Stream<DynamicTest> discountCalculation_fromCsvFile() throws IOException {
Path csvFile = Paths.get("src/test/resources/discount-test-cases.csv");
return Files.lines(csvFile)
.skip(1) // skip header
.map(line -> line.split(","))
.map(parts -> {
String description = parts[0].trim();
double originalPrice = Double.parseDouble(parts[1].trim());
String discountCode = parts[2].trim();
double expectedPrice = Double.parseDouble(parts[3].trim());
return DynamicTest.dynamicTest(description,
() -> {
DiscountCalculator calc = new DiscountCalculator();
double result = calc.apply(originalPrice, discountCode);
assertEquals(expectedPrice, result, 0.01,
"Failed for: " + description);
});
});
}discount-test-cases.csv:
Description,OriginalPrice,DiscountCode,ExpectedPrice
10% off with SAVE10,100.00,SAVE10,90.00
Free shipping over 50,75.00,FREESHIP,75.00
20% off with SUMMER20,200.00,SUMMER20,160.00
No discount with INVALID,50.00,INVALID,50.00Adding test cases means editing the CSV. No recompilation. Test names come from the data.
Generating from a Database
For integration tests, generate test cases from a query:
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
class ProductPricingDynamicTest {
private ProductRepository repository;
@BeforeAll
void setUp() {
repository = new ProductRepository(testDataSource);
}
@TestFactory
Stream<DynamicTest> allActiveProducts_shouldHaveValidPricing() {
return repository.findAllActive().stream()
.map(product -> DynamicTest.dynamicTest(
"Product " + product.sku() + " (" + product.name() + ") should have valid price",
() -> {
assertThat(product.price())
.isNotNull()
.isGreaterThan(Money.ZERO);
assertThat(product.compareAtPrice())
.satisfiesAnyOf(
cmp -> assertThat(cmp).isNull(),
cmp -> assertThat(cmp).isGreaterThan(product.price())
);
}
));
}
}Every product in the database gets a named test. When you add products, the test suite automatically covers them.
DynamicContainer for Nested Structure
DynamicContainer lets you organize dynamic tests into named groups:
import org.junit.jupiter.api.DynamicContainer;
import org.junit.jupiter.api.DynamicNode;
@TestFactory
Stream<DynamicNode> currencyConversion_shouldHandleAllSupportedPairs() {
Map<String, List<double[]>> testData = Map.of(
"USD → EUR", List.of(
new double[]{1, 0.92},
new double[]{100, 92.0},
new double[]{0, 0}
),
"USD → GBP", List.of(
new double[]{1, 0.79},
new double[]{100, 79.0},
new double[]{0, 0}
),
"EUR → GBP", List.of(
new double[]{1, 0.86},
new double[]{50, 43.0}
)
);
return testData.entrySet().stream()
.map(entry -> {
String pair = entry.getKey();
List<DynamicTest> tests = entry.getValue().stream()
.map(data -> DynamicTest.dynamicTest(
data[0] + " " + pair + " = " + data[1],
() -> {
String[] currencies = pair.split(" → ");
double result = CurrencyConverter.convert(
data[0], currencies[0], currencies[1]);
assertEquals(data[1], result, 0.01);
}))
.collect(toList());
return DynamicContainer.dynamicContainer(pair, tests);
});
}Test output:
✓ currencyConversion_shouldHandleAllSupportedPairs
USD → EUR
✓ 1.0 USD → EUR = 0.92
✓ 100.0 USD → EUR = 92.0
✓ 0.0 USD → EUR = 0.0
USD → GBP
✓ 1.0 USD → GBP = 0.79
...Lifecycle Limitations
Dynamic tests have a constraint worth knowing: @BeforeEach and @AfterEach do NOT run around each dynamic test. They run around the @TestFactory method itself:
class DynamicTestLifecycleExample {
@BeforeEach
void setUp() {
// Runs ONCE before the @TestFactory method, not before each DynamicTest
System.out.println("BeforeEach");
}
@TestFactory
Stream<DynamicTest> dynamicTests() {
return Stream.of("a", "b", "c").map(s ->
DynamicTest.dynamicTest("test " + s, () -> {
// BeforeEach did NOT run again before this
System.out.println("test " + s);
}));
}
}If each dynamic test needs its own setup, do it inside the test body:
@TestFactory
Stream<DynamicTest> tests() {
return Stream.of("a", "b", "c").map(s ->
DynamicTest.dynamicTest("test " + s, () -> {
MyService service = new MyService(); // setup inside test
assertNotNull(service.process(s));
}));
}This is the main functional difference from @ParameterizedTest + @BeforeEach. If lifecycle hooks per-test-case are critical, parameterized tests may serve better.
When Dynamic Tests Beat Parameterized Tests
| Scenario | Use |
|---|---|
| Same assertion, different inputs | @ParameterizedTest |
| Test cases from a CSV/YAML/database | @TestFactory |
| Number of cases unknown at compile time | @TestFactory |
| Test name must be computed from data | @TestFactory |
| Different assertions per case | @TestFactory |
Lifecycle hooks (@BeforeEach) around each case |
@ParameterizedTest |
| Cases need to be reported individually in JUnit XML | @ParameterizedTest (better IDE/CI support) |
Handling Streams Lazily
@TestFactory returning a Stream is lazy — JUnit pulls from the stream only when it's ready to run each test. This matters for streams backed by I/O:
@TestFactory
Stream<DynamicTest> testFromApiData() {
return apiClient.streamTestCases() // HTTP call happens lazily
.map(tc -> DynamicTest.dynamicTest(tc.name(), () -> {
// test body
}));
}The API isn't called until JUnit starts consuming the stream. For very large datasets, this prevents loading everything into memory at once.
Close resources properly using Stream.onClose():
@TestFactory
Stream<DynamicTest> testFromFile() throws IOException {
Stream<String> lines = Files.lines(Paths.get("test-data.txt"));
return lines
.map(line -> DynamicTest.dynamicTest(line, () -> {
// test body
}))
.onClose(lines::close); // file closed when stream is exhausted
}Summary
@TestFactory generates test cases at runtime rather than compile time. Use DynamicTest.stream() for the common case of iterating over inputs. Use DynamicContainer to nest dynamic tests into named groups. Generate tests from CSV files, databases, or any runtime data source. Remember that @BeforeEach/@AfterEach run around the factory method, not around each dynamic test — put per-test setup inside the test body. Choose dynamic tests when test count or structure is unknown at compile time; choose parameterized tests when you need lifecycle hooks around each case or want better IDE/CI reporting support.