Mastering JUnit 5: The Modern Java Unit‑Testing Framework

JUnit 5 Architecture Overview

JUnit 5 consists of three sub‑projects that make the framework more flexible than earlier versions:

JUnit Platform – the core launcher that runs tests and reports results across IDEs, Maven, Gradle, and third‑party frameworks.

JUnit Jupiter – the new programming and extension model that introduces all of the new annotations and features.

JUnit Vintage – provides backward compatibility for JUnit 3 and JUnit 4 tests, allowing seamless migration to the new platform.

Core Features

New Annotation Model

JUnit 5 redesigns the annotation set to be more intuitive and flexible: @Test – marks a test method; it can now handle expected exceptions directly. @BeforeEach and @AfterEach – run before/after each test method, replacing JUnit 4’s @Before and @After. @BeforeAll and @AfterAll – run once before/after all tests; the methods must be static. @DisplayName – supplies a readable name for a test method, shown in reports. @Disabled – disables a test or class, similar to JUnit 4’s @Ignore.

Dynamic Tests

Dynamic tests are generated at runtime, which is useful for data‑driven scenarios.

@TestFactory
Stream<DynamicTest> dynamicTests() {
    return Stream.of("A", "B", "C")
        .map(str -> DynamicTest.dynamicTest("测试 " + str,
            () -> assertTrue(str.length() > 0)));
}

Parameterized Tests

Parameterized tests run the same logic with different input data using @ParameterizedTest together with source annotations such as @ValueSource or @CsvSource.

@ParameterizedTest
@ValueSource(strings = { "hello", "world" })
void testWithStringValueSource(String word) {
    assertNotNull(word);
}

Test Tagging and Grouping

Tags allow grouping tests and selecting subsets to run, which is handy for large projects with mixed environments.

@Tag("fast")
@Test
void fastTest() {
    // quick test
}

@Tag("slow")
@Test
void slowTest() {
    // slow test
}

Exception Assertions

Exception testing is simplified with assertThrows, which verifies that a specific exception is thrown.

@Test
void shouldThrowException() {
    Exception exception = assertThrows(IllegalArgumentException.class, () -> {
        throw new IllegalArgumentException("非法参数");
    });
    assertEquals("非法参数", exception.getMessage());
}

Nested Tests

Nested tests enable logical grouping of related tests inside inner classes annotated with @Nested.

@Nested
class InnerClassTests {
    @Test
    void innerTest() {
        assertTrue(true);
    }
}

Practical Usage Example

Below is a simple Calculator class and a corresponding test class that demonstrates the most common JUnit 5 features.

class Calculator {
    int add(int a, int b) { return a + b; }
    int subtract(int a, int b) { return a - b; }
}

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class CalculatorTest {
    Calculator calculator = new Calculator();

    @Test
    void testAddition() {
        assertEquals(5, calculator.add(2, 3), "2 + 3 should equal 5");
    }

    @Test
    void testSubtraction() {
        assertEquals(1, calculator.subtract(3, 2), "3 - 2 should equal 1");
    }
}

Tests can be run from an IDE or via build tools. With Maven, the command is:

mvn test

JUnit 5 vs. JUnit 4

Key differences include:

Annotation changes – e.g., @BeforeEach replaces @Before, @Disabled replaces @Ignore.

Full support for Java 8+ lambda expressions and functional programming style.

Dynamic tests – a feature absent in JUnit 4.

Enhanced parameterized tests with more data sources.

Conclusion

JUnit 5 is a powerful, highly flexible Java unit‑testing framework that offers richer functionality for writing and organizing tests. Its new annotation model, dynamic and parameterized test support, tagging, exception assertions, and nested tests help developers automate testing more effectively, improve code quality, and increase development efficiency. Users of JUnit 4 are encouraged to migrate gradually to benefit from these modern capabilities.