In the modern Java ecosystem, developer productivity is often measured by the speed and reliability of the feedback loop. As a Java developer, two tools you’ll inevitably encounter are Gradle (or Maven) for building your projects and JUnit for testing them.

JUnit 5, the latest generation of this popular testing framework, isn’t just an incremental update; it’s a complete modular overhaul designed to support modern Java features (like Lambdas) and provide a more robust extension model. Integrating it into your build lifecycle is a fundamental skill. This guide will walk you through the architecture, configuration, and execution of JUnit 5 tests, ensuring your setup is optimized for high-performance development.

⚡ Quick Start: TL;DR Setup

If you’re in a hurry or just need a quick reference, here are the essential steps for your build files:

Gradle (Groovy)

• Add Dependencies: junit-jupiter-api (compile) and junit-jupiter-engine (runtime).
• Enable Platform: Add useJUnitPlatform() inside the test { ... } block.

Maven

• Add Dependency: Include the junit-jupiter aggregator artifact.
• Plugin Check: Ensure maven-surefire-plugin is version 2.22.0 or higher.

A Deep Dive into the JUnit 5 Architecture

To configure your build tool correctly, you must first understand that JUnit 5 is a modular framework composed of three main sub-projects. Unlike JUnit 4, which was a monolithic library, JUnit 5 separates concerns to allow for better integration with IDEs and build tools.

1. JUnit Platform

This is the core foundation. It defines the TestEngine API, which tools like IntelliJ IDEA, Gradle, and Maven use to discover and launch tests.

2. JUnit Jupiter

This is the module you will interact with most. It includes the API (annotations like @Test) and the Engine specifically for JUnit 5 tests.

3. JUnit Vintage

Provides backward compatibility for JUnit 3 or JUnit 4 tests, allowing them to run alongside new JUnit 5 tests.

Configuring JUnit 5 with Gradle

1. Adding the Dependencies

In your build.gradle, distinguish between writing tests and running them to keep your classpath clean.

dependencies {
    // API: Needed to compile your test classes
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.10.2'

    // Engine: Needed only at runtime to execute the tests
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.10.2'
    
    // Support for Parameterized Tests
    testImplementation 'org.junit.jupiter:junit-jupiter-params:5.10.2'
}

💡 Pro Tip: By using testRuntimeOnly for the engine, you ensure that engine-specific internal logic doesn’t leak into your test compilation phase.

2. Enabling the JUnit Platform

⚠ Common Mistake: If you skip this, Gradle defaults to a legacy runner and won’t find your JUnit 5 tests.

test {
    useJUnitPlatform()
    
    testLogging {
        events "passed", "skipped", "failed"
    }
}

Configuring JUnit 5 with Maven

1. The Aggregator Dependency

Maven simplifies things with the junit-jupiter artifact, which automatically pulls in the API, Engine, and Params modules.

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

2. The Maven Surefire Plugin

Ensure you are using a modern version of the Surefire plugin for native JUnit 5 support.

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

Writing Professional Tests in JUnit 5

In a real-world project, your source code and test code live in separate directories. By default, build tools look for source code in src/main/java and tests in src/test/java.

1. The Source Class: Calculator.java

Path: src/main/java/com/ankurm/testing/Calculator.java

package com.ankurm.testing;

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

2. The Test Class: CalculatorTest.java

Path: src/test/java/com/ankurm/testing/CalculatorTest.java

package com.ankurm.testing;

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

@DisplayName("Standard Math Operations")
class CalculatorTest {

    Calculator calc;

    @BeforeEach
    void setUp() {
        calc = new Calculator(); // Fresh instance for every test
    }

    @Test
    @DisplayName("Verify Addition: 5 + 10 = 15")
    void testAddition() {
        assertEquals(15, calc.add(5, 10), "The sum should be 15");
    }

    @Test
    @DisplayName("Verify Subtraction: 20 - 5 = 15")
    void testSubtraction() {
        assertEquals(15, calc.subtract(20, 5), "Subtraction logic failed");
    }
}

Advanced Feature: Parameterized Tests

This allows you to test multiple scenarios with a single method.

Gradle Dependency: testImplementation 'org.junit.jupiter:junit-jupiter-params:5.10.2'

Maven Dependency: Included in the junit-jupiter aggregator.

@ParameterizedTest
@ValueSource(ints = {1, 2, 3, 100})
@DisplayName("Ensure inputs are recognized as positive")
void testIsPositive(int number) {
    assertTrue(number > 0);
}

Running and Analyzing Test Results

The Terminal & CI/CD

Running tests from the command line is essential for automation. Because JUnit 5 integrates directly with these build tools, the same configuration works locally and in GitHub Actions or Jenkins—no runner rewrites required.

Output:

> Task :test
com.ankurm.testing.CalculatorTest > Verify Addition: 5 + 10 = 15 PASSED
com.ankurm.testing.CalculatorTest > Verify Subtraction: 20 - 5 = 15 PASSED
com.ankurm.testing.CalculatorTest > Ensure inputs are recognized as positive [1] PASSED

BUILD SUCCESSFUL in 2s

• Gradle: ./gradlew test
• Maven: mvn test

Detailed HTML Reports

• Gradle: Open build/reports/tests/test/index.html.
• Maven: Use mvn surefire-report:report to generate a full site.

Conclusion: Why This Matters for Your Career

Setting up JUnit 5 correctly isn’t just a configuration chore—it’s about setting a standard. By leveraging Jupiter’s modularity, Gradle’s build speed, and Maven’s structured dependencies, you create an environment where bugs have nowhere to hide.

Summary Recap:

• Modularity: Know the difference between Platform, Jupiter, and Vintage.
• Classpath: Keep API and Engine separate in Gradle for cleaner builds.
• Automation: Modern Surefire/Gradle settings ensure seamless CI/CD integration.

With this foundation, you are ready to explore more advanced topics like Mockito integration, Testcontainers, and Cloud-native testing.

Happy Testing!