JUnit 6 Maven Dependency

Learn how to configure JUnit 6 with Maven. This tutorial discusses the artifacts we need, how to set up our pom.xml, and how to execute the tests. Because JUnit 6 builds on the JUnit Platform, we must ensure a TestEngine is on the classpath.

Please note that JUnit 6 requires the minimum versions of Java 17 and Maven Surefire / Failsafe plugin 3.0.0 (or newer) to run tests.

1. JUnit 6 Modules

The following table summarizes the contained in JUnit 6 and their purposes:

Maven Artifact	Description	Required?
junit-jupiter	Convenience “starter” artifact that brings in both junit-jupiter-api and junit-jupiter-engine. This is the simplest way to use JUnit 6 with Maven.	Yes (recommended)
junit-jupiter-api	Contains all public annotations and API classes such as @Test, @BeforeEach, Assertions, etc. Required to compile tests.	If using junit-jupiter → No; otherwise Yes
junit-jupiter-engine	The TestEngine implementation that actually runs JUnit 6 tests. Must be present at test runtime.	If using junit-jupiter → No; otherwise Yes
junit-platform-launcher	Used when launching the JUnit Platform programmatically. Useful for custom test runners or IDEs.	No
junit-platform-suite-api	Provides annotations like @Suite to group and execute test suites.	No
junit-platform-reporting	Additional reporting features for JUnit Platform runs.	No
junit-vintage-engine	Enables running legacy JUnit 4 and JUnit 3 tests on the JUnit Platform.	Optional, only for old test support
junit-bom	BOM (Bill of Materials) used to align all JUnit module versions automatically.	Recommended but not mandatory

2. Minimal JUnit 6 Maven Example

An example pom.xml file is given below.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.howtodoinjava</groupId>
  <artifactId>examples</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>jar</packaging>

  <name>examples</name>
  <url>http://maven.apache.org</url>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.release>17</maven.compiler.release>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.junit</groupId>
        <artifactId>junit-bom</artifactId>
        <version>6.0.1</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>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.4</version>
      </plugin>
    </plugins>
  </build>

</project>

3. Production-ready JUnit 6 Setup Example

This is the “enterprise-ready” JUnit 6 Maven configuration. This confirmation has the following test tool supports:

Feature	Description
BOM import	Keeps all JUnit 6 module versions aligned automatically
Jupiter Engine + Params	Full modern JUnit 6 feature support
Suite API	Supports test suites using @Suite annotations
Launcher API	Allows programmatic test runs (IDE, CI tools)
Surefire + Failsafe	Clear separation: unit tests + integration tests
Parallel execution	Enabled via junit-platform.properties
Jacoco ready	Automatic code coverage reports
Custom test includes	Cleaner file naming conventions

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
             https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>junit6-advanced-demo</artifactId>
    <version>1.0.0</version>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <junit.platform.properties>junit-platform.properties</junit.platform.properties>
    </properties>

    <!-- Import JUnit BOM for consistent versions -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.junit</groupId>
                <artifactId>junit-bom</artifactId>
                <version>6.0.1</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>

        <!-- JUnit 6 starter: API + Engine -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- Parameterized tests -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-params</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- Suite API for @Suite test classes -->
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-suite-api</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- Programmatic launching, used by some tools -->
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-launcher</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- Optional: AssertJ for fluent assertions -->
        <dependency>
            <groupId>org.assertj</groupId>
            <artifactId>assertj-core</artifactId>
            <version>3.26.3</version>
            <scope>test</scope>
        </dependency>

    </dependencies>

    <build>
        <plugins>

            <!-- Surefire for Unit Tests -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>3.2.5</version>
                <configuration>
                    <useModulePath>false</useModulePath>
                    <includes>
                        <include>**/*Test.java</include>
                        <include>**/*Tests.java</include>
                        <include>**/*TestCase.java</include>
                    </includes>

                    <!-- Enable JUnit Platform -->
                    <properties>
                        <property>
                            <name>junit.platform.properties</name>
                            <value>${junit.platform.properties}</value>
                        </property>
                    </properties>
                </configuration>
            </plugin>

            <!-- Failsafe for integration tests -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-failsafe-plugin</artifactId>
                <version>3.2.5</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>integration-test</goal>
                            <goal>verify</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <includes>
                        <include>**/*IT.java</include>
                    </includes>
                </configuration>
            </plugin>

            <!-- Optional: JaCoCo test coverage -->
            <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
                <version>0.8.12</version>
                <executions>
                    <execution>
                        <id>prepare-agent</id>
                        <goals>
                            <goal>prepare-agent</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>report</id>
                        <phase>verify</phase>
                        <goals>
                            <goal>report</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

        </plugins>
    </build>

</project>

4. Conclusion

Setting up JUnit 6 with Maven is straightforward thanks to its modular architecture and the unified JUnit Platform. By including the mandatory junit-jupiter-engine along with optional modules such as the API, params, and platform components, we can assemble exactly the testing stack the project needs.

Happy Learning !!