JUnit 5

Visit Website

Introduction

JUnit 5 is the test framework current Java projects use. It is three pieces that share a version line. JUnit Platform launches tests and reports results to Maven Surefire, Gradle, and IDEs. JUnit Jupiter is the programming model for new tests (@Test, @ParameterizedTest, extensions). JUnit Vintage runs existing JUnit 4 tests on that platform so a codebase can migrate file by file.

The code is EPL-2.0, developed at junit-team/junit5. JUnit 5 does not start browsers, devices, or containers. Libraries such as Selenium and Testcontainers plug into Jupiter’s extension model. Assertions live in org.junit.jupiter.api.Assertions. Many teams add AssertJ on top.

Features

1. Jupiter annotations: @Test, @BeforeEach, @AfterEach, @BeforeAll, @AfterAll, @DisplayName, and @Disabled.
2. Parameterized tests: @ParameterizedTest with @ValueSource, @CsvSource, @MethodSource, and @EnumSource.
3. Nested tests: @Nested classes group cases and share setup without a deep inheritance tree.
4. Tags: @Tag("slow") plus Surefire or Gradle filters include or exclude groups in CI.
5. Extensions: Extension hooks replace most JUnit 4 Rules. @TempDir, @RegisterExtension, and conditional execution (@EnabledOnOs, @DisabledIf) ship with Jupiter.
6. Parallel execution: Jupiter can run tests concurrently when junit.jupiter.execution.parallel.enabled is set. Tests must tolerate that.
7. Vintage: JUnit 4 tests run on the Platform during a migration. New tests should not target Vintage.
8. Reporting: Platform listeners emit XML and console output that CI systems already parse. The build tool, not JUnit, uploads the files.

Pros

1. It is the default on the JVM: IDEs, Maven Surefire, and Gradle’s useJUnitPlatform() treat Jupiter as the normal runner.
2. Migration has a supported bridge: Vintage keeps JUnit 4 tests running while new code uses Jupiter.
3. Parameters are annotations, not a second framework: CSV and method sources cover tables of inputs without a custom runner class.
4. Extensions are explicit: Setup is a class you can read, not a global fixture file discovered by name.
5. Free: EPL-2.0. No seat license for the framework.

Cons

1. Three artifacts to version: Platform, Jupiter, and (if needed) Vintage must be compatible. A BOM (junit-bom) is the usual fix, and forgetting it causes classpath clashes.
2. Surefire and Gradle need a one-line switch: An old Surefire that only runs JUnit 4 reports “no tests” until useJUnitPlatform or a current Surefire provider is set.
3. Parallel mode is off for a reason: Shared static state and order-dependent tests fail when it is turned on. Enabling it is a project change, not a flag you flip in CI only.
4. Assertions are minimal: Jupiter’s assertEquals is enough, but failure messages are plainer than AssertJ. Most codebases add a second library.
5. Vintage is a trap if it stays forever: Leaving JUnit 4 rules in place means two extension styles in one repo.

Usage and Links (Example)

Maven:

<dependency>
  <groupId>org.junit.jupiter</groupId>
  <artifactId>junit-jupiter</artifactId>
  <scope>test</scope>
</dependency>

Import junit-bom in dependencyManagement and omit the version on the test dependency, or pin the current 5.x from Maven Central. Platform and Jupiter versions must match.

import static org.junit.jupiter.api.Assertions.assertEquals;

import org.junit.jupiter.api.Test;

class CalculatorTest {
  @Test
  void adds() {
    assertEquals(2, 1 + 1);
  }
}

mvn test or gradle test launches the Platform. In Gradle, the test task needs useJUnitPlatform().

Resources:

• JUnit 5 website
• JUnit 5 user guide
• GitHub: junit-team/junit5

Pricing

1. Free: JUnit 5 is EPL-2.0. There is no commercial JUnit edition.
2. Build tools are separate: You run tests with Maven, Gradle, or Bazel. Those tools have their own licenses and CI cost.

Recommended for?

1. Java and Kotlin unit tests on the JVM, including Spring Boot tests that already use @ExtendWith or @SpringBootTest.
2. Codebases leaving JUnit 4, using Vintage only while files are converted.
3. Integration tests that add Testcontainers or an embedded server through a Jupiter extension.
4. Libraries published to Maven Central whose consumers expect junit-jupiter as a test dependency.

Conclusion

JUnit 5 is the JVM unit framework to standardize on. Use Jupiter for new tests, the Platform so the build can see them, and Vintage only as a temporary bridge from JUnit 4. Pin the artifacts with the BOM, and treat parallel execution as a deliberate change. Browser, API, and container tooling sit beside JUnit; they are not included in it.