A well-organised test project is just as important as well-organised production code. Poor test structure leads to duplication, brittle tests, and test suites that are hard to navigate and maintain. This guide shows you exactly how to structure a JUnit 6 project — from package layout to naming conventions, test base classes, shared utilities, and the practices that keep test suites healthy at scale.

Whether you are starting fresh or cleaning up an existing project, the patterns here apply to any Java application — monolith, microservice, or library.

The Standard Maven/Gradle Directory Layout

JUnit 6 follows the standard Maven directory convention, which Gradle also adopts by default:

my-app/
├── src/
│   ├── main/
│   │   └── java/
│   │       └── com/example/
│   │           ├── service/
│   │           │   └── OrderService.java
│   │           ├── repository/
│   │           │   └── OrderRepository.java
│   │           └── model/
│   │               └── Order.java
│   └── test/
│       ├── java/
│       │   └── com/example/          <-- mirrors main package structure
│       │       ├── service/
│       │       │   └── OrderServiceTest.java
│       │       ├── repository/
│       │       │   └── OrderRepositoryIT.java  <-- IT suffix = integration test
│       │       └── common/
│       │           └── BaseTest.java           <-- shared test base class
│       └── resources/
│           └── junit-platform.properties  <-- JUnit 6 config
├── pom.xml
└── README.md

Key principles of this layout:

• Test packages mirror production packages so you can immediately find the test for any class
• Unit tests end with Test; integration tests end with IT
• Shared test infrastructure lives in a common sub-package
• JUnit 6 configuration goes in src/test/resources/junit-platform.properties

Continue reading JUnit 6 Project Structure and Best Practices →

Setting up JUnit 6 with Maven and Gradle correctly is more than adding one dependency. You need the right plugin versions, the right configuration flags, and the right test source layout so tests are discovered, executed, and reported correctly every time. This guide covers every configuration option from a basic single-module project to advanced multi-module and CI-ready setups.

If you are brand new to JUnit 6, start with Getting Started with JUnit 6 first. This post goes deeper into build tool specifics.

Part 1: JUnit 6 with Maven

Step 1 — The Core Dependency

Add junit-jupiter to your pom.xml. This single aggregator pulls in the API, params module, and engine in one shot:

<properties>
    <junit.version>6.1.1</junit.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

<dependencies>
    <!-- JUnit Jupiter aggregator: API + Params + Engine -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>${junit.version}</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Step 2 — Maven Surefire Plugin (Unit Tests)

The Maven Surefire Plugin runs unit tests during the test phase. You must use a 3.x version (3.2.5 or higher recommended) — JUnit 6 no longer supports Surefire/Failsafe older than 3.0.0:

<build>
    <plugins>
        <!-- Surefire: runs tests in the 'test' lifecycle phase -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.2.5</version>
            <configuration>
                <!-- Show test output in the console during build -->
                <useFile>false</useFile>
                <!-- Include these naming patterns for test discovery -->
                <includes>
                    <include>**/*Test.java</include>
                    <include>**/*Tests.java</include>
                    <include>**/Test*.java</include>
                </includes>
            </configuration>
        </plugin>
    </plugins>
</build>

Step 3 — Maven Failsafe Plugin (Integration Tests)

For integration tests (tests that start a server, connect to a database, etc.), use the Failsafe Plugin. By convention, integration test classes end with IT:

<!-- Failsafe: runs integration tests in 'verify' phase -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-failsafe-plugin</artifactId>
    <version>3.2.5</version>
    <executions>
        <execution>
            <goals>
                <!-- 'integration-test' runs the tests -->
                <goal>integration-test</goal>
                <!-- 'verify' checks the results and fails the build if needed -->
                <goal>verify</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <!-- Integration tests match *IT.java by convention -->
        <includes>
            <include>**/*IT.java</include>
        </includes>
    </configuration>
</plugin>

Run integration tests with: mvn verify

Continue reading JUnit 6 with Maven and Gradle: Complete Setup Guide →