The @Nested annotation is used to mark an inner class to be treated as a test class by the Jupiter engine. If we don't use the @Nested annotation on the inner class, the tests inside it won't be scanned, even if the methods are annotated with @Test. The same applies to static nested classes; they are not scanned for tests even if we annotate their methods with @Test or even annotate the class itself with @Nested.
Inner test classes help organize related test cases logically while maintaining test isolation.
Java source and doc
Definition of Nested(Version: junit-5 6.0.1) package org.junit.jupiter.api;
@java.lang.annotation.Target(java.lang.annotation.ElementType.TYPE)
@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.RUNTIME)
@java.lang.annotation.Documented
@org.apiguardian.api.API(status = org.apiguardian.api.API.Status.STABLE, since = "5.0")
public @interface Nested {
}
Examples
package com.logicbig.example;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertTrue;
public class IntroductionToNestedTests {
@Test
void outerTest() {
assertTrue(true);
}
@Nested
class MyNestedTests {
@Test
void nestedMethodTest() {
assertTrue(true);
}
}
}
mvn test -Dtest=IntroductionToNestedTests OutputD:\example-projects\junit-5\nested-classes\junit-5-introduction-to-nested-tests>mvn test -Dtest=IntroductionToNestedTests
[INFO] Scanning for projects...
[INFO]
[INFO] ---------< com.logicbig.example:introduction-to-nested-tests >----------
[INFO] Building introduction-to-nested-tests 1.0-SNAPSHOT
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ introduction-to-nested-tests ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\nested-classes\junit-5-introduction-to-nested-tests\src\main\resources
[INFO]
[INFO] --- compiler:3.11.0:compile (default-compile) @ introduction-to-nested-tests ---
[INFO] No sources to compile
[INFO]
[INFO] --- resources:3.3.1:testResources (default-testResources) @ introduction-to-nested-tests ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\nested-classes\junit-5-introduction-to-nested-tests\src\test\resources
[INFO]
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ introduction-to-nested-tests ---
[INFO] Changes detected - recompiling the module! :source
[WARNING] File encoding has not been set, using platform encoding Cp1252, i.e. build is platform dependent!
[INFO] Compiling 1 source file with javac [debug target 17] to target\test-classes
[INFO]
[INFO] --- surefire:3.2.5:test (default-test) @ introduction-to-nested-tests ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.logicbig.example.IntroductionToNestedTests
[INFO] Running com.logicbig.example.IntroductionToNestedTests$ContextA
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.008 s -- in com.logicbig.example.IntroductionToNestedTests$ContextA
[INFO] Tests run: 0, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.061 s -- in com.logicbig.example.IntroductionToNestedTests
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.623 s
[INFO] Finished at: 2025-12-06T06:36:35+08:00
[INFO] ------------------------------------------------------------------------
The static nested classes
@Nested doesn't work on the static nested classes
package com.logicbig.example;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertTrue;
public class StaticNestedAnnotationTests {
@Test
void outerTest() {
assertTrue(true);
}
@Nested
static class MyNestedTests {
@Test
void nestedMethodTest() {
assertTrue(true);
}
}
}
mvn test -Dtest=StaticNestedAnnotationTests OutputD:\example-projects\junit-5\nested-classes\junit-5-introduction-to-nested-tests>mvn test -Dtest=StaticNestedAnnotationTests
[INFO] Scanning for projects...
[INFO]
[INFO] ---------< com.logicbig.example:introduction-to-nested-tests >----------
[INFO] Building introduction-to-nested-tests 1.0-SNAPSHOT
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ introduction-to-nested-tests ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\nested-classes\junit-5-introduction-to-nested-tests\src\main\resources
[INFO]
[INFO] --- compiler:3.11.0:compile (default-compile) @ introduction-to-nested-tests ---
[INFO] No sources to compile
[INFO]
[INFO] --- resources:3.3.1:testResources (default-testResources) @ introduction-to-nested-tests ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\nested-classes\junit-5-introduction-to-nested-tests\src\test\resources
[INFO]
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ introduction-to-nested-tests ---
[INFO] Nothing to compile - all classes are up to date
[INFO]
[INFO] --- surefire:3.2.5:test (default-test) @ introduction-to-nested-tests ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.logicbig.example.StaticNestedAnnotationTests
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.071 s -- in com.logicbig.example.StaticNestedAnnotationTests
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.740 s
[INFO] Finished at: 2025-12-06T08:44:00+08:00
[INFO] ------------------------------------------------------------------------
Dec 06, 2025 8:43:59 AM org.junit.platform.launcher.core.DiscoveryIssueNotifier logIssues
WARNING: TestEngine with ID 'junit-jupiter' encountered a non-critical issue during test discovery:
(1) [WARNING] @Nested class 'com.logicbig.example.StaticNestedAnnotationTests$MyNestedTests' must not be static. It will only be executed if discovered as a standalone test class. You should remove the annotation or make it non-static to resolve this warning.
Source: ClassSource [className = 'com.logicbig.example.StaticNestedAnnotationTests$MyNestedTests', filePosition = null]
at com.logicbig.example.StaticNestedAnnotationTests$MyNestedTests.<no-method>(SourceFile:0)
Dec 06, 2025 8:43:59 AM org.junit.platform.launcher.core.DiscoveryIssueNotifier logIssues
WARNING: TestEngine with ID 'junit-jupiter' encountered a non-critical issue during test discovery:
(1) [WARNING] @Nested class 'com.logicbig.example.StaticNestedAnnotationTests$MyNestedTests' must not be static. It will only be executed if discovered as a standalone test class. You should remove the annotation or make it non-static to resolve this warning.
Source: ClassSource [className = 'com.logicbig.example.StaticNestedAnnotationTests$MyNestedTests', filePosition = null]
at com.logicbig.example.StaticNestedAnnotationTests$MyNestedTests.<no-method>(SourceFile:0)
The inner classes without @Nested
Tests inside the inner classes will not be discovered by Jupiter engines even if they have methods with @Test annotation.
package com.logicbig.example;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertTrue;
public class WithoutNestedAnnotationTests {
@Test
void outerTest() {
assertTrue(true);
}
// @Nested
class MyNestedTests {
@Test
void nestedMethodTest() {
assertTrue(true);
}
}
}
mvn test -Dtest=WithoutNestedAnnotationTests OutputD:\example-projects\junit-5\nested-classes\junit-5-introduction-to-nested-tests>mvn test -Dtest=WithoutNestedAnnotationTests
[INFO] Scanning for projects...
[INFO]
[INFO] ---------< com.logicbig.example:introduction-to-nested-tests >----------
[INFO] Building introduction-to-nested-tests 1.0-SNAPSHOT
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ introduction-to-nested-tests ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\nested-classes\junit-5-introduction-to-nested-tests\src\main\resources
[INFO]
[INFO] --- compiler:3.11.0:compile (default-compile) @ introduction-to-nested-tests ---
[INFO] No sources to compile
[INFO]
[INFO] --- resources:3.3.1:testResources (default-testResources) @ introduction-to-nested-tests ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\nested-classes\junit-5-introduction-to-nested-tests\src\test\resources
[INFO]
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ introduction-to-nested-tests ---
[INFO] Nothing to compile - all classes are up to date
[INFO]
[INFO] --- surefire:3.2.5:test (default-test) @ introduction-to-nested-tests ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.logicbig.example.WithoutNestedAnnotationTests
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.078 s -- in com.logicbig.example.WithoutNestedAnnotationTests
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.941 s
[INFO] Finished at: 2025-12-06T08:46:28+08:00
[INFO] ------------------------------------------------------------------------
Dec 06, 2025 8:46:27 AM org.junit.platform.launcher.core.DiscoveryIssueNotifier logIssues
WARNING: TestEngine with ID 'junit-jupiter' encountered a non-critical issue during test discovery:
(1) [WARNING] Inner class 'com.logicbig.example.WithoutNestedAnnotationTests$MyNestedTests' looks like it was intended to be a test class but will not be executed. It must be static or annotated with @Nested.
Source: ClassSource [className = 'com.logicbig.example.WithoutNestedAnnotationTests$MyNestedTests', filePosition = null]
at com.logicbig.example.WithoutNestedAnnotationTests$MyNestedTests.<no-method>(SourceFile:0)
Dec 06, 2025 8:46:27 AM org.junit.platform.launcher.core.DiscoveryIssueNotifier logIssues
WARNING: TestEngine with ID 'junit-jupiter' encountered a non-critical issue during test discovery:
(1) [WARNING] Inner class 'com.logicbig.example.WithoutNestedAnnotationTests$MyNestedTests' looks like it was intended to be a test class but will not be executed. It must be static or annotated with @Nested.
Source: ClassSource [className = 'com.logicbig.example.WithoutNestedAnnotationTests$MyNestedTests', filePosition = null]
at com.logicbig.example.WithoutNestedAnnotationTests$MyNestedTests.<no-method>(SourceFile:0)
Example ProjectDependencies and Technologies Used: - junit-jupiter-engine 6.0.1 (Module "junit-jupiter-engine" of JUnit)
Version Compatibility: 5.0.0 - 6.0.1 Version compatibilities of junit-jupiter-engine with this example:
- 5.0.0
- 5.0.1
- 5.0.2
- 5.0.3
- 5.1.0
- 5.1.1
- 5.2.0
- 5.3.0
- 5.3.1
- 5.3.2
- 5.4.0
- 5.4.1
- 5.4.2
- 5.5.0
- 5.5.1
- 5.5.2
- 5.6.0
- 5.6.1
- 5.6.2
- 5.6.3
- 5.7.0
- 5.7.1
- 5.7.2
- 5.8.0
- 5.8.1
- 5.8.2
- 5.9.0
- 5.9.1
- 5.9.2
- 5.9.3
- 5.10.0
- 5.10.1
- 5.10.2
- 5.10.3
- 5.10.4
- 5.10.5
- 5.11.0
- 5.11.1
- 5.11.2
- 5.11.3
- 5.11.4
- 5.12.0
- 5.12.1
- 5.12.2
- 5.13.0
- 5.13.1
- 5.13.2
- 5.13.3
- 5.13.4
- 5.14.0
- 5.14.1
- 6.0.0
- 6.0.1
Versions in green have been tested.
- JDK 17
- Maven 3.9.11
|
