`@LocalServerPort` fails to inject port when using inheritance and `@Nested` test classes

[fraj]

Versions

Version of Spring Boot: 4.0.0, after migration from 3.5.x

Context

I have a JUnit test class annotated with @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT). This class does not contain any tests itself. Instead, it inherits from an abstract class that implements test methods within an inner classes annotated with JUnit's @Nested. In the abstract parent class, I want to inject the value of the web server's port using @LocalServerPort on a local field.

Observed

A NumberFormatException occurs when I try to retrieve the port value as an int. When I retrieve it as a String, I obtain "${local.server.port}". This behavior only occurs when I use both class inheritance and a nested test class in the parent class. With nested test classes directly inside the @SpringBootTest class, the port value is OK. With test methods in an abstract parent class but without a nested class, the port value is OK. The configuration with both inheritance and nested test classes works with Spring Boot 3.5.

Expected

Have the port value correctly injected in the configuration with inheritance and nested test class.

Attachments

Simplified project to reproduce the issue:

issue-spring-boot-4.zip

[wilkinsona]

Thanks for the minimal sample. I think this is likely a duplicate of, or at least it's closely related to, #35880. As with that issue, if you add @SpringExtensionConfig(useTestClassScopedExtensionContext = true) to ChildTest the problem no longer occurs.

We'll transfer this to the Framework issue tracker so that the Framework team can investigate further alongside #35880 and #31456 which is also in a similar area.

[fraj]

Hi, Andy. Thank you for your quick response. Indead, I could test this solution in my full project and it works. I'll adopt it as a turnaround for now. Thank you, Sam, for having a look at it. Let me know if I can be of any help.

[sbrannen]

I was able to reproduce the reported behavior without Spring Boot in the picture, and I will use these classes for further discussions.

abstract class AbstractTests {

	@Value("${test.port:-1}")
	int port;

//	@BeforeEach
//	void setup(@Value("${test.port:-1}") int port) {
//		this.port = port;
//	}

	@Nested
	class NestedTests {

		@Test
		void nestedTest() {
			assertThat(port).isEqualTo(9999);
		}
	}

}

@ExtendWith(SpringExtension.class)
@TestPropertySource(properties = "test.port = 9999")
// @SpringExtensionConfig(useTestClassScopedExtensionContext = true)
// @TestInstance(Lifecycle.PER_CLASS)
class ChildTests extends AbstractTests {
}

[sbrannen]

I apologize in advance for posting such a long winded response, but I've been putting quite a bit of thought into this topic lately, and I wanted to capture those thoughts somewhere online so that I can refer back to them (and perhaps convert them into some form of official documentation at some point).

---

The change in behavior is in fact due to the switch to a test-method scoped ExtensionContext by default in Spring Framework 7.0.

From the class-level Javadoc for SpringExtension:

As of Spring Framework 7.0, the SpringExtension is configured to use a test-method scoped ExtensionContext, which enables consistent dependency injection into fields and constructors from the ApplicationContext for the current test method in a @Nested test class hierarchy. However, if a third-party TestExecutionListener is not compatible with the semantics associated with a test-method scoped extension context — or if a developer wishes to switch to test-class scoped semantics — the SpringExtension can be configured to use a test-class scoped extension context by annotating a top-level test class with @SpringExtensionConfig(useTestClassScopedExtensionContext = true). Note, however, that the SpringExtension will always use a test-class scoped ExtensionContext if your top-level test class is configured to use JUnit Jupiter’s @TestInstance(Lifecycle.PER_CLASS) semantics, in which case there is no need to declare @SpringExtensionConfig(useTestClassScopedExtensionContext = true).

As @wilkinsona already mentioned, annotating ChildTests with @SpringExtensionConfig(useTestClassScopedExtensionContext = true) restores the behavior to that prior to 7.0.

And as you can read in the above Javadoc, annotating ChildTests with @TestInstance(Lifecycle.PER_CLASS) instead of @SpringExtensionConfig results in the same effect.

Each of the above options forces the SpringExtension to use a test-class scoped ExtensionContext. Thus, when ChildTests is executed, dependency injection for the AbstractTests.port field is performed based on the ExtensionContext for ChildTests (the current test class) which is annotated with Spring annotations that configure the ApplicationContext. Consequently, that ApplicationContext has the test.port set to 999, and the nestedTest() test passes.

On the flip side, if the SpringExtension uses a test-method scoped ExtensionContext when ChildTests is executed, dependency injection for the AbstractTests.port field is performed based on the ExtensionContext for AbstractTests.NestedTests.nestedTest() (the current test method). In that scenario, the SpringExtension and related infrastructure search for Spring annotations on NestedTests and its enclosing class AbstractTests, neither of which is annotated with Spring annotations that configure the ApplicationContext. Consequently, dependency injection is performed from an ApplicationContext which does not have the test.port property set in its environment, and the nestedTest() test fails since the default value -1 is used.

That can be rather confusing or surprising on its own, but what is perhaps more surprising is why JUnit Jupiter even uses the SpringExtension in the latter scenario and why Spring simultaneously fails to find the Spring-related annotations.

In this particular scenario:

• When JUnit Jupiter executes ChildTests, it knows that NestedTests.nestedTest() is running within an enclosing instance of ChildTests.
• Consequently, since JUnit Jupiter manages a hierarchy of ExtensionContext instances which inherit extensions registered from parent contexts, the ExtensionContext for nestedTest() sees the SpringExtension registered in the grandparent ExtensionContext for ChildTests.
• However, as alluded to above, Spring's annotation search algorithms are only presented NestedTests as a starting point for finding annotations, and since NestedTests.class.getEnclosingClass() returns AbstractTests (the static enclosing type), the SpringExtension and related infrastructure are not able to find annotations on ChildTests (the runtime enclosing type).

This effectively boils down to an age old discrepancy between Spring and JUnit Jupiter: static vs. runtime enclosing types.

In other words, JUnit can see @ExtendWith(SpringExtension.class) on ChildTests (the runtime enclosing type), but Spring's testing infrastructure cannot see @TestPropertySource on AbstractTests (the static enclosing type), because it's actually only declared on ChildTests (the runtime enclosing type).

Since a picture is worth a thousand words, for a test-method scoped ExtensionContext in this scenario...

JUnit Jupiter sees:

--------------
| ChildTests |
--------------
      ^
      |
---------------
| NestedTests |
---------------

Whereas Spring sees:

-----------------
| AbstractTests |
-----------------
        ^
        |
 ---------------
 | NestedTests |
 ---------------

In summary, when a test-method scoped ExtensionContext is used with a mixture of type hierarchies and @Nested class hierarchies, where @Nested classes are inherited and not all levels of the type hierarchy declare Spring-related annotations, you can encounter scenarios where the SpringExtension simply cannot work.

See also: #35880 (comment)

In light of the above, I am closing this as a duplicate of:

• Provide guidance on using @Nested within test classes with complex inheritance and annotation arrangements #28466

In particular, see #28466 (comment).