JUnit 5 Advanced Features: Dynamic Tests, Extensions, and Parallel Execution
JUnit 5 goes far beyond basic @Test annotations. @TestFactory generates tests at runtime, @ExtendWith plugs in lifecycle hooks and parameter injection, parallel execution cuts CI time dramatically, @Nested organizes complex test hierarchies, and conditional annotations skip tests intelligently based on environment. This post covers all five with working Spring Boot examples.
JUnit 5 was a ground-up rewrite of the most widely used Java testing framework. It split into three modules — JUnit Platform (launcher), JUnit Jupiter (API), and JUnit Vintage (backward compat) — and introduced an extension model that replaces the old @RunWith and @Rule mechanisms completely. If you're still writing JUnit 5 tests the same way you wrote JUnit 4, you're leaving significant power on the table.
This post goes deep on five advanced capabilities that experienced teams use daily: dynamic test factories, custom extension development, parallel execution, nested test organization, and environment-aware conditional execution.
@TestFactory: Generating Tests at Runtime
The @TestFactory annotation turns a method into a factory that produces test cases dynamically — at runtime, not at compile time. This is fundamentally different from @ParameterizedTest: parameterized tests still represent a fixed test with varying inputs, while dynamic tests can have completely different names, behavior, and structure generated from runtime data.
The factory method must return a Stream, Collection, Iterable, or Iterator of DynamicTest objects (or DynamicContainer for nested dynamic tests).
import org.junit.jupiter.api.DynamicTest;
import org.junit.jupiter.api.TestFactory;
import org.junit.jupiter.api.function.Executable;
import java.util.Arrays;
import java.util.Collection;
import java.util.List;
import java.util.stream.Stream;
class PricingEngineTest {
private final PricingEngine engine = new PricingEngine();
@TestFactory
Stream<DynamicTest> dynamicPricingTests() {
List<PricingScenario> scenarios = loadScenariosFromDatabase();
return scenarios.stream()
.map(scenario -> DynamicTest.dynamicTest(
"Price for " + scenario.getProductId() + " in region " + scenario.getRegion(),
() -> {
Money result = engine.calculate(scenario.getProductId(), scenario.getRegion());
assertEquals(scenario.getExpectedPrice(), result);
}
));
}
@TestFactory
Collection<DynamicTest> discountRuleTests() {
return Arrays.asList(
DynamicTest.dynamicTest("10% discount for orders over $100", () -> {
Order order = new Order().withSubtotal(Money.of(150, "USD"));
assertEquals(Money.of(135, "USD"), engine.applyDiscounts(order));
}),
DynamicTest.dynamicTest("20% discount for premium members", () -> {
Order order = new Order().withSubtotal(Money.of(50, "USD"))
.withCustomerTier(CustomerTier.PREMIUM);
assertEquals(Money.of(40, "USD"), engine.applyDiscounts(order));
}),
DynamicTest.dynamicTest("Discounts stack: premium + volume", () -> {
Order order = new Order().withSubtotal(Money.of(200, "USD"))
.withCustomerTier(CustomerTier.PREMIUM);
assertEquals(Money.of(144, "USD"), engine.applyDiscounts(order)); // 20% + 10%
})
);
}
// Nested dynamic containers for hierarchical organization
@TestFactory
Stream<DynamicNode> hierarchicalPricingTests() {
return Stream.of(
DynamicContainer.dynamicContainer("Standard tier", Stream.of(
DynamicTest.dynamicTest("Basic product", () -> {
// ...
}),
DynamicTest.dynamicTest("Bundle product", () -> {
// ...
})
)),
DynamicContainer.dynamicContainer("Enterprise tier", Stream.of(
DynamicTest.dynamicTest("Volume licensing", () -> {
// ...
}),
DynamicTest.dynamicTest("Custom contract", () -> {
// ...
})
))
);
}
}A practical use case is loading test data from external files or databases. In one codebase, we load validation rules from a YAML config file and generate one test per rule — any change to the config file immediately creates or removes tests without touching test code.
@TestFactory
Stream<DynamicTest> validationRuleTests() throws Exception {
ValidationRuleConfig config = loadYaml("validation-rules.yml");
return config.getRules().stream()
.flatMap(rule -> Stream.of(
DynamicTest.dynamicTest(
rule.getName() + ": valid input passes",
() -> assertTrue(rule.validate(rule.getValidExample()))
),
DynamicTest.dynamicTest(
rule.getName() + ": invalid input fails",
() -> assertFalse(rule.validate(rule.getInvalidExample()))
)
));
}@ExtendWith: Building Custom Extensions
JUnit 5's extension model is the replacement for JUnit 4's @RunWith and @Rule. Extensions implement one or more callback interfaces. The framework calls them at defined lifecycle points. You can have multiple extensions on a single test class, and they compose cleanly.
Lifecycle Extension
import org.junit.jupiter.api.extension.*;
public class DatabaseCleanupExtension implements
BeforeEachCallback, AfterEachCallback, BeforeAllCallback {
private static final String DATASOURCE_KEY = "datasource";
@Override
public void beforeAll(ExtensionContext context) throws Exception {
DataSource ds = createTestDataSource();
runMigrations(ds);
getStore(context).put(DATASOURCE_KEY, ds);
}
@Override
public void beforeEach(ExtensionContext context) throws Exception {
DataSource ds = getStore(context).get(DATASOURCE_KEY, DataSource.class);
try (Connection conn = ds.getConnection()) {
conn.createStatement().execute("BEGIN");
}
}
@Override
public void afterEach(ExtensionContext context) throws Exception {
DataSource ds = getStore(context).get(DATASOURCE_KEY, DataSource.class);
try (Connection conn = ds.getConnection()) {
conn.createStatement().execute("ROLLBACK");
}
}
private ExtensionContext.Store getStore(ExtensionContext context) {
return context.getRoot().getStore(
ExtensionContext.Namespace.create(DatabaseCleanupExtension.class)
);
}
}Parameter Resolver Extension
Parameter resolvers inject custom objects into test methods and constructors. This is how @TempDir and @Autowired (in Spring) work.
public class RandomDataExtension implements ParameterResolver {
@Override
public boolean supportsParameter(ParameterContext parameterContext,
ExtensionContext extensionContext) {
return parameterContext.isAnnotated(RandomData.class);
}
@Override
public Object resolveParameter(ParameterContext parameterContext,
ExtensionContext extensionContext) {
RandomData annotation = parameterContext.findAnnotation(RandomData.class)
.orElseThrow();
Class<?> type = parameterContext.getParameter().getType();
if (type == String.class) {
return faker.internet().emailAddress();
} else if (type == User.class) {
return User.builder()
.email(faker.internet().emailAddress())
.name(faker.name().fullName())
.age(faker.number().numberBetween(18, 80))
.build();
}
throw new IllegalArgumentException("Cannot generate random " + type);
}
private static final Faker faker = new Faker();
}
// Usage:
@ExtendWith(RandomDataExtension.class)
class UserServiceTest {
@Test
void registrationSendsWelcomeEmail(@RandomData User user) {
userService.register(user);
verify(emailService).sendWelcome(user.getEmail());
}
}Composing Extensions into Custom Annotations
Instead of stacking @ExtendWith on every class, compose them into a meta-annotation:
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@ExtendWith(DatabaseCleanupExtension.class)
@ExtendWith(MockitoExtension.class)
@ExtendWith(TimingExtension.class)
@Tag("integration")
public @interface IntegrationTest {
}
// Usage:
@IntegrationTest
class OrderRepositoryTest {
// All three extensions active automatically
}Parallel Test Execution
JUnit 5 supports parallel execution natively since 5.3. Configure it in src/test/resources/junit-platform.properties:
junit.jupiter.execution.parallel.enabled=true
junit.jupiter.execution.parallel.mode.default=concurrent
junit.jupiter.execution.parallel.mode.classes.default=concurrent
junit.jupiter.execution.parallel.config.strategy=fixed
junit.jupiter.execution.parallel.config.fixed.parallelism=4The strategy options are:
fixed— fixed thread pool sizedynamic—availableProcessors * factor(configure with.dynamic.factor)custom— implementParallelExecutionConfigurationStrategy
By default with mode.default=concurrent, all tests within a class run in parallel and all classes run in parallel. You can override per class or per method:
@Execution(ExecutionMode.SAME_THREAD)
class SequentialTest {
// All tests in this class run sequentially, regardless of global config
}
class MixedTest {
@Test
@Execution(ExecutionMode.CONCURRENT)
void parallelTest1() { /* safe to parallelize */ }
@Test
@Execution(ExecutionMode.SAME_THREAD)
void sequentialTest() { /* uses shared mutable state */ }
}Shared State and @ResourceLock
When tests share external resources (databases, files, ports), use @ResourceLock to prevent races:
class PortBindingTest {
@Test
@ResourceLock(value = "PORT_8080", mode = ResourceAccessMode.READ_WRITE)
void testServerOnPort8080() {
// Only one test holds READ_WRITE at a time
Server server = new Server(8080);
server.start();
// ...
server.stop();
}
@Test
@ResourceLock(value = "PORT_8080", mode = ResourceAccessMode.READ)
void testClientConnectsTo8080() {
// Multiple READ tests can run concurrently
// ...
}
}Spring Boot Parallel Test Execution
With Spring Boot, you need to be careful about application context sharing. The default @SpringBootTest reuses contexts across tests, which works with parallel execution if your tests don't mutate the context:
@SpringBootTest
@TestPropertySource(properties = "spring.datasource.url=jdbc:h2:mem:testdb")
class ProductServiceIntegrationTest {
@Autowired
private ProductService productService;
// Spring context is shared — tests must not modify beans
@Test
void findsByCategory() {
List<Product> products = productService.findByCategory("electronics");
assertFalse(products.isEmpty());
}
}If tests do modify state, use @DirtiesContext or isolate with separate database transactions that roll back.
@Nested: Organizing Complex Test Hierarchies
@Nested lets you express "describe/context" style test organization inside a single file. Inner classes are non-static by default, so they can access outer class fields.
@SpringBootTest
class UserServiceTest {
@Autowired
private UserService userService;
@Autowired
private UserRepository userRepository;
@Nested
@DisplayName("when user does not exist")
class WhenUserDoesNotExist {
@Test
@DisplayName("findById returns empty Optional")
void findByIdReturnsEmpty() {
Optional<User> result = userService.findById(99999L);
assertTrue(result.isEmpty());
}
@Test
@DisplayName("deleteById throws UserNotFoundException")
void deleteByIdThrows() {
assertThrows(UserNotFoundException.class,
() -> userService.deleteById(99999L));
}
}
@Nested
@DisplayName("when user exists")
class WhenUserExists {
private User existingUser;
@BeforeEach
void createUser() {
existingUser = userRepository.save(User.builder()
.email("test@example.com")
.name("Test User")
.build());
}
@AfterEach
void deleteUser() {
userRepository.deleteById(existingUser.getId());
}
@Test
@DisplayName("findById returns the user")
void findByIdReturnsUser() {
Optional<User> result = userService.findById(existingUser.getId());
assertTrue(result.isPresent());
assertEquals("test@example.com", result.get().getEmail());
}
@Nested
@DisplayName("when user is suspended")
class WhenUserIsSuspended {
@BeforeEach
void suspendUser() {
existingUser.setSuspended(true);
userRepository.save(existingUser);
}
@Test
@DisplayName("login throws AccountSuspendedException")
void loginThrows() {
assertThrows(AccountSuspendedException.class,
() -> userService.login(existingUser.getEmail(), "password"));
}
}
}
}The @BeforeEach and @AfterEach in outer classes run for all inner class tests too. Inner class @BeforeEach runs after the outer one. This lets you build up state incrementally as you go deeper into the hierarchy.
Conditional Test Execution
JUnit 5 ships with a rich set of conditions that skip tests based on environment, OS, JVM version, system properties, or arbitrary expressions.
OS and JVM Conditions
@Test
@EnabledOnOs(OS.LINUX)
void linuxFilePermissionsTest() {
// Only runs on Linux
Path path = Path.of("/tmp/test-file");
Files.createFile(path);
Files.setPosixFilePermissions(path, PosixFilePermissions.fromString("rwx------"));
assertEquals("rwx------", PosixFilePermissions.toString(
Files.getPosixFilePermissions(path)));
}
@Test
@DisabledOnOs({OS.WINDOWS, OS.MAC})
void dockerSocketTest() {
// Docker socket test only makes sense on Linux CI
assertTrue(Files.exists(Path.of("/var/run/docker.sock")));
}
@Test
@EnabledOnJre(JRE.JAVA_17)
void recordPatternMatchingTest() {
// Feature only available on Java 17+
}
@Test
@EnabledForJreRange(min = JRE.JAVA_11, max = JRE.JAVA_17)
void legacyApiTest() {
// API available in this version range
}Environment Variable Conditions
@Test
@EnabledIfEnvironmentVariable(named = "CI", matches = "true")
void onlyInCI() {
// Skip locally, run in GitHub Actions
}
@Test
@DisabledIfEnvironmentVariable(named = "SKIP_SLOW_TESTS", matches = "true")
void slowIntegrationTest() {
// Developers can set SKIP_SLOW_TESTS=true to skip locally
}System Property Conditions
@Test
@EnabledIfSystemProperty(named = "database.type", matches = "postgresql")
void postgresSpecificTest() {
// Only run when -Ddatabase.type=postgresql
}Custom Conditions with @EnabledIf
For arbitrary logic, implement ExecutionCondition or use Spring's expression-based variant:
@Test
@EnabledIf("isRunningInDocker")
void containerNetworkTest() {
// Custom condition method in same class
}
boolean isRunningInDocker() {
return Files.exists(Path.of("/.dockerenv"));
}With Spring Boot's @SpringBootTest, you often combine this with profiles:
@SpringBootTest
@ActiveProfiles("integration")
@EnabledIfEnvironmentVariable(named = "DATABASE_URL", matches = ".*postgresql.*")
class PostgresIntegrationTest {
// Only runs when DATABASE_URL points to Postgres and "integration" profile is active
}Putting It All Together: A Real Spring Boot Test Suite
Here's how these features combine in a real-world service test:
@IntegrationTest // custom meta-annotation with @ExtendWith
@DisplayName("Order Processing Service")
class OrderProcessingServiceTest {
@Autowired
private OrderProcessingService orderService;
@Autowired
private OrderRepository orderRepository;
@Nested
@DisplayName("Order creation")
class OrderCreation {
@TestFactory
@DisplayName("creates orders for all product types")
Stream<DynamicTest> createsOrdersForAllProductTypes() {
return ProductType.stream()
.map(type -> DynamicTest.dynamicTest(
"Creates order for " + type,
() -> {
Order order = orderService.create(
OrderRequest.forProduct(type).withQuantity(1)
);
assertNotNull(order.getId());
assertEquals(type, order.getProductType());
assertEquals(OrderStatus.PENDING, order.getStatus());
}
));
}
@Test
@DisabledIfEnvironmentVariable(named = "PAYMENT_GATEWAY", matches = "mock")
@DisplayName("charges payment gateway in production mode")
void chargesPaymentGateway() {
// Only runs against real payment gateway
}
}
@Nested
@DisplayName("Order fulfillment")
@Execution(ExecutionMode.SAME_THREAD) // fulfillment changes order state
class OrderFulfillment {
private Order pendingOrder;
@BeforeEach
void createPendingOrder() {
pendingOrder = orderRepository.save(Order.pending());
}
@Test
void fulfillmentChangesStatusToCompleted() {
orderService.fulfill(pendingOrder.getId());
Order reloaded = orderRepository.findById(pendingOrder.getId()).orElseThrow();
assertEquals(OrderStatus.COMPLETED, reloaded.getStatus());
}
@Test
void fulfillmentSendsConfirmationEmail() {
orderService.fulfill(pendingOrder.getId());
// verify email was sent
}
}
}Summary
JUnit 5's advanced features solve real problems:
- @TestFactory — test cases that come from runtime data, external files, or databases
- @ExtendWith — lifecycle hooks, parameter injection, and reusable test infrastructure without inheritance
- Parallel execution — cut test suite time with
junit-platform.propertiesconfig and@ResourceLockfor safety - @Nested — BDD-style organization with shared setup/teardown that composes hierarchically
- Conditional annotations — smart test selection based on environment without if-statements in test bodies
The key insight is that JUnit 5 was designed for extensibility at every layer. The extension model means you write infrastructure once (a parameter resolver, a lifecycle extension, a custom annotation) and apply it everywhere. The result is test code that reads like documentation and runs only when it should.