JUnit 5: Annotations, Lifecycle, Assertions and Parameterized Tests Reference Guide

  
    org.junit.jupiter
    junit-jupiter            
    5.11.0
    test
  



  
    
      maven-surefire-plugin  
      3.5.0
    
    
      maven-failsafe-plugin  
      3.5.0
    
  



plugins { `java-library` }
dependencies {
    testImplementation(platform("org.junit:junit-bom:5.11.0"))
    testImplementation("org.junit.jupiter:junit-jupiter")
    testImplementation("org.junit.jupiter:junit-jupiter-params")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}
tasks.test { useJUnitPlatform() }

# Run
mvn test                                 # all tests
mvn -Dtest=UserServiceTest test          # one class
mvn -Dtest='UserServiceTest#testLogin*' test
mvn -Dgroups="fast" test                 # @Tag filter (since 4.7.1)
gradle test --tests com.x.UserServiceTest
gradle test --tests "*Login*" -i        # filter + info logs

import java.util.stream.Stream;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.*;

class CalcTest {

    // 1. Inline values
    @ParameterizedTest
    @ValueSource(ints = {1, 2, 4, 8})
    void isEven(int n) {
        // pytest-style — name shows the arg
    }

    // 2. Multi-arg from CSV
    @ParameterizedTest(name = "[{index}] {0} + {1} = {2}")
    @CsvSource({
        "1, 2, 3",
        "5, 7, 12",
        "'',  0, 0",                              // empty string is null/0
    })
    void add(int a, int b, int expected) {
        assertEquals(expected, Math.addExact(a, b));
    }

    // 3. From a CSV file on classpath
    @ParameterizedTest
    @CsvFileSource(resources = "/cases.csv", numLinesToSkip = 1)
    void fromFile(String input, String expected) {}

    // 4. Enum source — all values or a subset
    @ParameterizedTest
    @EnumSource(value = Day.class, names = {"SAT", "SUN"})
    void weekend(Day d) {}

    // 5. Method source — most flexible
    @ParameterizedTest
    @MethodSource("usersWithExpectedRoles")
    void rolesProject(User u, Role expected) {}

    static Stream usersWithExpectedRoles() {
        return Stream.of(
            Arguments.of(new User("alice"), Role.ADMIN),
            Arguments.of(new User("bob"),   Role.MEMBER)
        );
    }

    // 6. Dynamic tests — generate at runtime
    @TestFactory
    Stream evenNumbers() {
        return Stream.of(2, 4, 6).map(n -> dynamicTest("is " + n + " even", () -> {
            assertEquals(0, n % 2);
        }));
    }
}

// 1. A custom extension — measure each test's wall clock
package com.example.test;

import org.junit.jupiter.api.extension.*;
import org.slf4j.*;

public class TimingExtension implements BeforeTestExecutionCallback, AfterTestExecutionCallback {
    private static final Logger LOG = LoggerFactory.getLogger(TimingExtension.class);
    private static final ExtensionContext.Namespace NS =
        ExtensionContext.Namespace.create(TimingExtension.class);

    @Override
    public void beforeTestExecution(ExtensionContext ctx) {
        ctx.getStore(NS).put("t0", System.nanoTime());
    }

    @Override
    public void afterTestExecution(ExtensionContext ctx) {
        long t0 = (long) ctx.getStore(NS).remove("t0");
        long ms = (System.nanoTime() - t0) / 1_000_000;
        LOG.info("{} took {} ms", ctx.getDisplayName(), ms);
    }
}

// 2. Register it
@ExtendWith(TimingExtension.class)
class UserServiceTest { /* ... */ }

// 3. Or, register globally via SPI:
//    META-INF/services/org.junit.jupiter.api.extension.Extension
//    com.example.test.TimingExtension
//    + set junit.jupiter.extensions.autodetection.enabled=true

import static org.junit.jupiter.api.Assertions.*;
import org.junit.jupiter.api.*;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;

@TestInstance(TestInstance.Lifecycle.PER_CLASS)
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
@DisplayName("UserService")
class UserServiceTest {

    UserRepo repo;
    UserService svc;

    @BeforeAll
    void initDb() { /* one-time DB seed — needs PER_CLASS to avoid static */ }

    @BeforeEach
    void newTransaction() {
        repo = new InMemoryUserRepo();
        svc  = new UserService(repo);
    }

    @Test @Order(1)
    @DisplayName("rejects blank email")
    void rejectsBlankEmail() {
        var ex = assertThrows(IllegalArgumentException.class,
                              () -> svc.register("", "pw"));
        assertTrue(ex.getMessage().contains("email"));
    }

    @ParameterizedTest(name = "{0} → {1}")
    @CsvSource({ "alice@x.com, alice", "bob@y.com, bob" })
    @Tag("smoke")
    void registersFromEmail(String email, String expectedHandle) {
        var u = svc.register(email, "pw");
        assertAll("user",
            () -> assertNotNull(u.id()),
            () -> assertEquals(expectedHandle, u.handle()),
            () -> assertEquals(email, u.email())
        );
    }

    @Test
    @Disabled("flaky on CI — TICK-742")
    void deletesAccount() { /* ... */ }

    @AfterEach
    void teardown() { repo.clear(); }
}