The @NestedTestConfiguration annotation is a JUnit 5 specific feature in the Spring TestContext framework. It determines whether a nested test class inherits configuration from its enclosing class.
Java source and doc
Definition of NestedTestConfigurationVersion: 7.0.3 package org.springframework.test.context;
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface NestedTestConfiguration {
EnclosingConfiguration value(); 1
enum EnclosingConfiguration { 2
INHERIT, 3
OVERRIDE 4
}
}
Why @NestedTestConfiguration is needed
With JUnit 5 nested tests, Spring must decide how application context configuration should be applied to nested test classes.
Specifically, Spring needs to determine whether configuration classes declared in an outer test class should automatically apply to inner (@Nested) test classes, or whether those nested classes should be treated as isolated test contexts.
The @NestedTestConfiguration annotation defines this rule explicitly.
The Two Supported Modes
@NestedTestConfiguration(EnclosingConfiguration.XXX)
1. INHERIT (Default)
EnclosingConfiguration.INHERIT
- Nested test classes inherit configuration classes from enclosing test classes.
- Configuration classes are merged.
- A single hierarchical application context definition is created.
This is the default behavior.
2. OVERRIDE
EnclosingConfiguration.OVERRIDE
- Nested test classes ignore configuration from enclosing test classes.
- Only configuration declared directly on the nested test class is used.
- Each nested test class can define an independent
ApplicationContext.
Example
In the following example, the nested class successfully autowires a bean from the outer class configuration because inheritance is enabled.
package com.logicbig.example;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.NestedTestConfiguration;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.springframework.test.context.NestedTestConfiguration.EnclosingConfiguration.INHERIT;
import static org.springframework.test.context.NestedTestConfiguration.EnclosingConfiguration.OVERRIDE;
@ExtendWith(SpringExtension.class)
@ContextConfiguration(classes = NestedConfigTest.Config.class)
// This tells all @Nested classes to inherit this context
@NestedTestConfiguration(INHERIT)
public class NestedConfigTest {
@Configuration
static class Config {
@Bean
public String parentBean() {
return "Parent Context";
}
}
@Autowired
private String parentBean;
@Test
void outerTest() {
assertNotNull(parentBean);
System.out.println("Outer: " + parentBean);
}
@Nested
class InnerTest {
@Test
void innerTest() {
// This works because of @NestedTestConfiguration(INHERIT)
assertNotNull(parentBean);
System.out.println("Inner: " + parentBean);
}
}
}
Output$ mvn test -Dtest="com.logicbig.example.NestedConfigTest"
[INFO] Scanning for projects...
[INFO]
[INFO] -----------< com.logicbig.example:nested-test-configuration >-----------
[INFO] Building nested-test-configuration 1.0-SNAPSHOT
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ nested-test-configuration ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\spring-core-testing\nested-test-configuration\src\main\resources
[INFO]
[INFO] --- compiler:3.11.0:compile (default-compile) @ nested-test-configuration ---
[INFO] No sources to compile
[INFO]
[INFO] --- resources:3.3.1:testResources (default-testResources) @ nested-test-configuration ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\spring-core-testing\nested-test-configuration\src\test\resources
[INFO]
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ nested-test-configuration ---
[INFO] Changes detected - recompiling the module! :source
[WARNING] File encoding has not been set, using platform encoding UTF-8, i.e. build is platform dependent!
[INFO] Compiling 2 source files with javac [debug target 25] to target\test-classes
[INFO]
[INFO] --- surefire:3.5.4:test (default-test) @ nested-test-configuration ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[WARNING] file.encoding cannot be set as system property, use <argLine>-Dfile.encoding=...</argLine> instead
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
Outer: Parent Context
Inner: Parent Context
[INFO] +--com.logicbig.example.NestedConfigTest - 0.030 ss
[INFO] | +-- [OK] outerTest - 0.040 ss
[INFO] | '-- [OK] innerTest - 0.005 ss
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.475 s
[INFO] Finished at: 2026-02-04T13:02:51+08:00
[INFO] ------------------------------------------------------------------------
Using EnclosingConfiguration.OVERRIDE
package com.logicbig.example;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.NestedTestConfiguration;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.springframework.test.context.NestedTestConfiguration.EnclosingConfiguration.INHERIT;
import static org.springframework.test.context.NestedTestConfiguration.EnclosingConfiguration.OVERRIDE;
@ExtendWith(SpringExtension.class)
@ContextConfiguration(classes = NestedConfigTest2.Config.class)
// This tells all @Nested classes to override this context
@NestedTestConfiguration(OVERRIDE)
public class NestedConfigTest2 {
@Configuration
static class Config {
@Bean
public String parentBean() {
return "Parent Context";
}
}
@Autowired
private String parentBean;
@Test
void outerTest() {
assertNotNull(parentBean);
System.out.println("Outer: " + parentBean);
}
@Nested
class InnerTest {
@Configuration
static class Config {
@Bean
public String parentBean() {
return "Parent Context2";
}
}
@Test
void innerTest() {
// This works because of @NestedTestConfiguration(INHERIT)
assertNotNull(parentBean);
System.out.println("Inner: " + parentBean);
}
}
}
Output$ mvn test -Dtest="com.logicbig.example.NestedConfigTest2"
[INFO] Scanning for projects...
[INFO]
[INFO] -----------< com.logicbig.example:nested-test-configuration >-----------
[INFO] Building nested-test-configuration 1.0-SNAPSHOT
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ nested-test-configuration ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\spring-core-testing\nested-test-configuration\src\main\resources
[INFO]
[INFO] --- compiler:3.11.0:compile (default-compile) @ nested-test-configuration ---
[INFO] No sources to compile
[INFO]
[INFO] --- resources:3.3.1:testResources (default-testResources) @ nested-test-configuration ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\spring-core-testing\nested-test-configuration\src\test\resources
[INFO]
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ nested-test-configuration ---
[INFO] Nothing to compile - all classes are up to date
[INFO]
[INFO] --- surefire:3.5.4:test (default-test) @ nested-test-configuration ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[WARNING] file.encoding cannot be set as system property, use <argLine>-Dfile.encoding=...</argLine> instead
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
Outer: Parent Context
Inner: Parent Context2
[INFO] +--com.logicbig.example.NestedConfigTest2 - 0.043 ss
[INFO] | +-- [OK] outerTest - 0.036 ss
[INFO] | '-- [OK] innerTest - 0.004 ss
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.571 s
[INFO] Finished at: 2026-02-04T13:03:01+08:00
[INFO] ------------------------------------------------------------------------
Conclusion
The output of the first example shows that the 'parentBean' is available in both the outer and inner test methods. This proves that @NestedTestConfiguration(INHERIT) allows the Spring context to permeate into inner classes, significantly reducing boilerplate code for complex test suites.
The output of the second example demonstrates the effect of @NestedTestConfiguration(OVERRIDE). While the outer class initializes with "Parent Context", the InnerTest ignores the enclosing class's configuration entirely and utilizes its own static Config class to produce "Parent Context2". This confirms that the OVERRIDE mode successfully breaks the default inheritance, providing a completely isolated ApplicationContext for the nested test suite.
Example ProjectDependencies and Technologies Used: - spring-context 7.0.3 (Spring Context)
Version Compatibility: 5.3.0 - 7.0.3 Version compatibilities of spring-context with this example: Versions in green have been tested.
- spring-test 7.0.3 (Spring TestContext Framework)
- junit-jupiter-engine 6.0.2 (Module "junit-jupiter-engine" of JUnit)
- JDK 25
- Maven 3.9.11
|
