JUnit 5 Advanced Features: Dynamic Tests, Extensions, and Parallel Execution

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=4

The strategy options are:

  • fixed — fixed thread pool size
  • dynamic — availableProcessors * factor (configure with .dynamic.factor)
  • custom — implement ParallelExecutionConfigurationStrategy

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.properties config and @ResourceLock for 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.

Read more

Start now free