JUnit 6 Gradle Dependency

Learn how to configure JUnit 6 with Gradle. This tutorial discusses the artifacts we need, how to set up our build.gradle, 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 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:

Artifacts	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 Gradle.	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 Gradle Example

An example build.gradle file is given below.

plugins {
    id 'java'
}

group = 'com.howtodoinjava'
version = '1.0-SNAPSHOT'

repositories {
    mavenCentral()
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

dependencies {
    // Dependency management (JUnit 6 BOM)
    testImplementation platform("org.junit:junit-bom:6.0.1")

    // JUnit 6 Jupiter (API + Engine)
    testImplementation "org.junit.jupiter:junit-jupiter"
}

test {
    // Equivalent to Maven Surefire running JUnit Platform
    useJUnitPlatform()

    // Optional logging for readability
    testLogging {
        events "passed", "skipped", "failed"
    }
}

3. Production-ready JUnit 6 Gradle Setup Example

This is the “enterprise-ready” JUnit 6 Gradle 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

plugins {
    id 'java'
    id 'jacoco' // Optional: JaCoCo coverage
}

group = 'com.example'
version = '1.0.0'

repositories {
    mavenCentral()
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

dependencies {
    // JUnit 6 BOM for version alignment
    testImplementation platform("org.junit:junit-bom:6.0.1")

    // JUnit 6 Jupiter API + Engine
    testImplementation "org.junit.jupiter:junit-jupiter"

    // Parameterized tests
    testImplementation "org.junit.jupiter:junit-jupiter-params"

    // Suite API for @Suite test classes
    testImplementation "org.junit.platform:junit-platform-suite-api"

    // Platform launcher for programmatic test execution
    testRuntimeOnly "org.junit.platform:junit-platform-launcher"

    // Optional: AssertJ for fluent assertions
    testImplementation "org.assertj:assertj-core:3.26.3"
}

// Unit tests (equivalent to Surefire)
tasks.test {
    useJUnitPlatform()

    // Include patterns equivalent to Maven Surefire configuration
    include '**/*Test.class', '**/*Tests.class', '**/*TestCase.class'

    testLogging {
        events "passed", "skipped", "failed", "standardOut", "standardError"
    }
}

// Integration tests (equivalent to Failsafe)
sourceSets {
    integrationTest {
        java {
            compileClasspath += sourceSets.main.output + configurations.testRuntimeClasspath
            runtimeClasspath += output + compileClasspath
            srcDir file('src/integrationTest/java')
        }
        resources.srcDir file('src/integrationTest/resources')
    }
}

configurations {
    integrationTestImplementation.extendsFrom testImplementation
    integrationTestRuntimeOnly.extendsFrom testRuntimeOnly
}

task integrationTest(type: Test) {
    description = 'Runs integration tests.'
    group = 'verification'
    testClassesDirs = sourceSets.integrationTest.output.classesDirs
    classpath = sourceSets.integrationTest.runtimeClasspath
    useJUnitPlatform()
    include '**/*IT.class'
    shouldRunAfter test
}

check.dependsOn integrationTest

// JaCoCo configuration
jacoco {
    toolVersion = "0.8.12"
}

tasks.jacocoTestReport {
    dependsOn tasks.test
    reports {
        xml.required.set(true)
        html.required.set(true)
    }
}

4. Conclusion

Setting up JUnit 6 with Gradle 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 !!