JUnit Maven Dependency: JUnit 5, JUnit 6, and Surefire Setup

JUnit 5 and JUnit 6 Maven Dependency

Add this to the dependencies element of pom.xml. The version is the current release on Maven Central at the time of writing; check the junit-jupiter listing before you pin it in a long-lived build. Projects that must stay on Java 8 or 11 use the latest 5.x version with the same coordinates.

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

junit-jupiter is an aggregator: it has no code of its own and depends on junit-jupiter-api, junit-jupiter-engine, and junit-jupiter-params. That is why one line is enough to compile tests, run them, and write parameterized tests. Test scope keeps all of it off the application's runtime classpath.

After saving, reload the Maven project in your IDE so it picks up the new classpath, then create a class under src/test/java with a method annotated @Test from org.junit.jupiter.api. The Write JUnit Test Cases chapter picks up from there.

The JUnit Artifacts and When You Need Each

The aggregator covers the common case. Declare the pieces individually only when you have a reason to, such as a library module that should compile against the API without shipping an engine.

• junit-jupiter-api - the annotations (@Test, @BeforeEach, @Nested) and the Assertions and Assumptions classes. Compile scope for test code, and the only artifact a test-support library needs.
• junit-jupiter-engine - the engine that discovers and runs Jupiter tests. Needed at test runtime; without it the build compiles and runs zero tests.
• junit-jupiter-params - @ParameterizedTest and its sources. Only needed if you write parameterized tests, which the JUnit Parameterized Tests chapter covers.
• junit-platform-launcher - the API build tools and IDEs use to launch engines. Surefire 3.x and Gradle add it themselves; Surefire 2.22 and some IDE runners need it declared with test scope.
• junit-platform-suite - @Suite and @SelectPackages for composing suites in code, the JUnit answer to testng.xml.
• junit-vintage-engine - runs JUnit 3 and 4 tests on the platform; see the JUnit 4 section below.

Aligning Versions with junit-bom

As soon as you declare more than one JUnit artifact, or a library such as Mockito's JUnit extension pulls one in transitively, versions can drift and Jupiter will refuse to start with an UnsupportedClassVersionError or a launcher mismatch. The bill of materials pins them all at once:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.junit</groupId>
            <artifactId>junit-bom</artifactId>
            <version>6.1.3</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

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

With the BOM imported, no JUnit dependency carries its own version, and upgrading the whole framework is a one-line change. Since JUnit 6, Platform, Jupiter, and Vintage share a single version number, which the BOM reflects; the Migrate from JUnit 5 to JUnit 6 chapter walks through the upgrade.

Surefire Configuration

Maven runs tests through the Surefire plugin, and only Surefire 2.22 or newer understands the JUnit Platform. Pin a 3.x release so the version your build uses does not depend on the Maven default:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.6.0</version>
        </plugin>
    </plugins>
</build>

No further configuration is needed for discovery. Surefire runs classes whose names match *Test, Test*, *Tests, or *TestCase; a class named LoginSpec is skipped until you add an includes rule. Tags declared with @Tag are selected with groups and excludedGroups, and parallel execution is switched on through junit-platform.properties rather than Surefire, as the Parallel Testing with JUnit 5 chapter shows.

mvn test                              # every test class Surefire can find
mvn test -Dtest=CalculatorTest        # one class
mvn test -Dtest=CalculatorTest#adds   # one method
mvn test -Dgroups=smoke               # only tests tagged @Tag("smoke")

JUnit in Gradle

dependencies {
    testImplementation platform('org.junit:junit-bom:6.1.3')
    testImplementation 'org.junit.jupiter:junit-jupiter'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

test {
    useJUnitPlatform()
}

The platform(...) line imports the BOM, and useJUnitPlatform() switches the test task from the JUnit 4 default to the platform. Gradle 9 requires the launcher on the test runtime classpath explicitly, which the testRuntimeOnly line provides. Kotlin DSL users write the same three dependencies with parentheses and tasks.test { useJUnitPlatform() }.

JUnit 4 Dependency and Vintage

JUnit 4 is the artifact junit:junit, and 4.13.2 is its final release. A project that still has JUnit 4 tests can run them on the JUnit 5 platform next to new Jupiter tests by adding the Vintage engine, which lets you migrate class by class instead of all at once:

<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.13.2</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.vintage</groupId>
    <artifactId>junit-vintage-engine</artifactId>
    <scope>test</scope>
</dependency>

JUnit 6 still ships Vintage but marks it deprecated, so treat it as a bridge. The JUnit 4 vs JUnit 5 vs JUnit 6 chapter lists the annotation renames and the migration steps.

Troubleshooting the JUnit Maven Dependency

• Tests run: 0. Surefire is 2.x, or only junit-jupiter-api is declared. Pin Surefire 3.x and use the junit-jupiter aggregator.
• Package org.junit.jupiter.api does not exist. The test lives under src/main/java, or the IDE has not reloaded the project. Move it to src/test/java and reload Maven.
• UnsupportedClassVersionError. JUnit 6 is compiled for Java 17 and the build runs on an older JDK. Point JAVA_HOME at 17 or newer, or stay on the 5.x line.
• Tests run in the IDE but not in Maven. The class name does not match Surefire's include pattern. Rename it or add an includes block.
• NoSuchMethodError inside org.junit.platform. Mixed versions of Platform and Jupiter. Import junit-bom and remove explicit versions from the individual artifacts.
• JUnit 4 tests are ignored. Vintage is missing, or the JUnit 4 test class uses the wrong @Test import. Add junit-vintage-engine and check the import is org.junit.Test.

Conclusion

One junit-jupiter dependency with test scope and a Surefire 3.x plugin are all Maven needs for JUnit 5 and 6; add junit-bom once the project declares more than one JUnit artifact, and Vintage only while JUnit 4 tests remain. With the build in place, the next chapter, Run JUnit from the Command Line, runs the tests without an IDE.