JUnit Dynamic Tests With TestFactory and DynamicTest
Generate tests at runtime in JUnit with TestFactory, DynamicTest and DynamicContainer, and learn how they differ from parameterized tests.

Parameterized tests cover data you can list in an annotation. A dynamic test covers data that is only known when the tests start: one test per file in a directory, per row loaded from a service, per rule in a configuration.
A basic factory
class PricingRulesTest {
@TestFactory
Stream<DynamicTest> everyRuleHasAPositiveThreshold() {
return PricingRules.all().stream()
.map(rule -> dynamicTest("rule " + rule.name(),
() -> assertTrue(rule.threshold() > 0, rule.name() + " threshold")));
}
}JUnit calls the factory, then registers a test for each element. If a rule is added to PricingRules, a new test appears with no change here. In the IDE each dynamic test is listed under the factory with its display name.
One test per file
@TestFactory
Collection<DynamicTest> goldenFiles() throws IOException {
Path dir = Path.of("src/test/resources/golden");
try (Stream<Path> files = Files.list(dir)) {
return files.filter(p -> p.toString().endsWith(".json"))
.map(p -> dynamicTest(p.getFileName().toString(), () -> {
String expected = Files.readString(p);
assertEquals(expected, renderer.render(inputFor(p)));
}))
.toList();
}
}This is the typical use: a folder of example inputs and expected outputs where adding a file adds a test. The factory reads the file list eagerly, so close the stream before returning, as the try does.
Grouping
@TestFactory
Stream<DynamicNode> byCountry() {
return countries().map(country ->
dynamicContainer(country.code(), Stream.of(
dynamicTest("currency", () -> assertNotNull(country.currency())),
dynamicTest("tax rate", () -> assertTrue(country.taxRate().signum() >= 0)))));
}dynamicContainer makes a nested node, so the report shows a tree.
The lifecycle difference
Dynamic tests do not get their own @BeforeEach and @AfterEach. Those run once around the @TestFactory method, as if it were a single test. State shared between dynamic tests is therefore shared for real, and a failure in one does not reset anything. Create fresh objects inside each executable, not in a field, if isolation matters. The details of the callbacks are in JUnit 5 lifecycle.
Dynamic versus parameterized
| Need | Use |
|---|---|
| Known list of inputs in code | Parameterized test |
| Inputs discovered from files or services | Dynamic test |
| Per-case lifecycle hooks | Parameterized test |
| Nested grouping of cases | Dynamic containers |
If a parameterized test can express it, prefer it, since the framework handles lifecycle and display. See parameterized tests.
Pitfalls
- A factory that returns
nullor a non-test type is an error. - Dynamic tests cannot be selected by name from the command line as easily as normal ones.
- A factory failing while generating tests fails as one test, so keep the generation code trivial.
When a dynamic test is the right tool
Dynamic tests exist for the case where the list of tests is not known when the code is compiled. The classic examples are one test per file in a directory of fixtures, one per rule loaded from a configuration file, or one per row of a spreadsheet the business owns. If the cases are a fixed list of inputs, a @ParameterizedTest is simpler and better supported by IDEs. Reach for @TestFactory when the generator itself has logic: reading, filtering, grouping and naming. Each DynamicTest is reported as its own test with its own display name, so give it a name that tells a reader which fixture failed, such as the file name, and not test 7.
Exceptions and failures inside the factory
An exception thrown from the factory method itself, for instance because a fixture directory does not exist, fails the whole container and produces no tests at all. In a CI report that looks like a single failure with a stack trace and nothing to compare against last run. Validate the inputs at the top of the factory with a clear message, and decide on purpose whether an empty directory is an error. A factory that quietly generates zero tests passes, which is the worst outcome: the suite is green because it is empty. Add an assertion that the stream is not empty.
What you give up
A dynamic test has no lifecycle of its own. @BeforeEach and @AfterEach run around the factory method once, not around each dynamic test, which surprises people who expect fresh state per case. If each case needs its own setup, do it inside the executable. Parallel execution also differs: dynamic tests in one container run sequentially even when the class is configured to run in parallel. And you cannot run a single dynamic test from the IDE the way you run a normal method, because it does not exist until the factory runs, so keep cases fast enough that running them all is no burden.
A realistic example: one test per fixture file
A team keeps sample invoices as JSON files under src/test/resources/invoices, each with an expected total beside it. Adding a case means adding two files, and the test code never changes. That is the use case dynamic tests were made for, because the list of cases is data that business people can extend without touching Java.
@TestFactory
Stream<DynamicTest> invoicesMatchExpectedTotals() throws IOException {
Path dir = Path.of("src/test/resources/invoices");
try (Stream<Path> files = Files.list(dir)) {
List<Path> inputs = files.filter(p -> p.toString().endsWith(".json")).sorted().toList();
assertFalse(inputs.isEmpty(), "no invoice fixtures found in " + dir);
return inputs.stream().map(p -> dynamicTest(p.getFileName().toString(),
() -> assertEquals(expectedTotal(p), calculator.total(load(p)))));
}
}Read the directory eagerly and return a stream over a list, because the directory stream is closed when the try block ends, and a lazy stream over it would fail when JUnit consumed it later with a confusing closed stream error. Sorting makes the order stable across file systems, so a failing run on CI reads the same as the one on your laptop.
Reporting and the IDE
Each dynamic test shows up in the report under the factory method's name, with the display name you supplied. Surefire's XML report records them as separate test cases, so CI dashboards that count tests see every fixture. In IntelliJ and Eclipse you can rerun the whole factory but not one dynamic child, which is the trade for generating them at run time. If a single fixture needs repeated debugging, copy its path into a small ordinary test while you work and delete it afterward. Choose display names with this in mind: the file name is better than an index, and for rule-based tests the rule id is better than its description.
When the factory grows
If a factory needs more than a screenful of code, move the generation logic into a plain method that returns a list of cases, and unit test that method like any other code. The factory then does only the wiring, and a bug in how fixtures are grouped or named is found by an ordinary test and not by staring at a report that has nine hundred entries.
Where this does not apply
A factory is not a place for test logic that depends on execution order between cases. Each dynamic test should stand alone, in line with the rule from test doubles and isolation. The reference is Dynamic Tests, and the [Javadoc for DynamicTest](https://docs.junit.org/current/api/org.junit.jupiter.api/org/junit/jupiter/api/DynamicTest.html) lists the factories.


