JUnitException: TestEngine with ID 'junit-jupiter' Failed to Discover Tests

When working with JUnit 5 in Gradle or Maven projects, you might encounter the error: org.junit.platform.commons.JUnitException: TestEngine with ID 'junit-jupiter' failed to discover tests. This error typically indicates that JUnit cannot find or load your test classes properly.

Problem Overview

The error occurs when JUnit's test discovery mechanism fails to locate or process your test classes. The stack trace usually includes:

Caused by: java.lang.ClassNotFoundException: [YourTestClassName]
    at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:641)

Common causes include:

• Dependency version conflicts
• Incorrect project structure
• Missing required JUnit components
• IDE configuration issues
• Java version/preview features incompatibility

Solutions

1. Dependency Management (Most Common Solution)

The most frequent cause is version conflicts between JUnit components. Use the JUnit BOM (Bill of Materials) to ensure consistent versions:

For Maven:

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

For Gradle:

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

2. Spring Boot Projects

If using Spring Boot, rely on the spring-boot-starter-test which provides compatible testing dependencies:

// Gradle
testImplementation 'org.springframework.boot:spring-boot-starter-test:3.2.0'

<!-- Maven -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <version>3.2.0</version>
    <scope>test</scope>
</dependency>

3. Check Dependency Conflicts

Generate a dependency tree to identify version conflicts:

# Maven
mvn dependency:tree

# Gradle
gradle dependencies

Look for inconsistent versions of:

• junit-jupiter-api
• junit-jupiter-engine
• junit-platform-commons
• junit-platform-engine

4. Project Structure Validation

Ensure your tests are in the correct directory structure:

project-dir
 -- src
     -- main
        -- java
            -- your.package
                -- MainClass.java
     -- test
        -- java
            -- your.package
                -- YourTestClass.java

5. IDE Configuration

In IntelliJ, mark your test directory as a Test Sources Root:

1. Right-click on the test directory
2. Select "Mark Directory as" > "Test Sources Root"

WARNING

Ensure your test classes follow JUnit 5 naming conventions. Test methods don't need to be public, but the classes must be discoverable by JUnit.

6. Java Preview Features

If using Java preview features, ensure both compilation and test execution enable preview features:

Maven Configuration:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <source>21</source>
        <target>21</target>
        <compilerArgs>--enable-preview</compilerArgs>
    </configuration>
</plugin>

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <argLine>--enable-preview</argLine>
    </configuration>
</plugin>

7. Clean and Rebuild

Sometimes a simple clean and rebuild resolves the issue:

# Maven
mvn clean compile test

# Gradle
gradle clean test

Common Pitfalls and Solutions

VERSION CONFLICTS

Mixing different versions of JUnit components is the most common cause. Always use the JUnit BOM or let Spring Boot manage the versions for you.

SPRING BOOT USERS

If you're using Spring Boot, avoid manually adding JUnit dependencies. The spring-boot-starter-test already includes all necessary testing dependencies with compatible versions.

JAVA VERSION COMPATIBILITY

Some JUnit versions have issues with specific Java versions. If you recently upgraded Java, try:

• JUnit 5.9.x for Java 17+
• JUnit 5.8.x for Java 11-16
• JUnit 5.7.x for older Java versions

Example Working Configuration

Here's a complete Gradle configuration that works with Java 17 and Spring Boot:

plugins {
    id 'org.springframework.boot' version '3.2.0'
    id 'io.spring.dependency-management' version '1.1.4'
    id 'java'
}

group = 'com.example'
version = '0.0.1'
sourceCompatibility = '17'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

test {
    useJUnitPlatform()
}

Troubleshooting Steps

1. Check dump files: Look for .dump files in your build output for detailed error information
2. Verify classpath: Ensure your test classes are on the test classpath
3. Check annotations: Use @Test from org.junit.jupiter.api.Test
4. Review imports: Remove any JUnit 4 imports (org.junit.Test)
5. Examine dependency tree: Look for version conflicts

INFO

If you're migrating from JUnit 4 to JUnit 5, ensure you've removed all JUnit 4 dependencies and replaced all @Test annotations with the JUnit 5 variant.

By following these solutions and best practices, you should be able to resolve the TestEngine discovery failure and successfully run your JUnit 5 tests.