@SpringJUnitWebConfig is a composed annotation introduced in Spring 5 that combines @ExtendWith(SpringExtension.class), @ContextConfiguration, and @WebAppConfiguration into a single, concise declaration. It is specifically designed to streamline the setup of Spring MVC integration tests using JUnit 5+
Before this annotation existed, developers had to stack three separate annotations on every test class that needed a full web application context. @SpringJUnitWebConfig removes that boilerplate, making test classes cleaner and easier to read while retaining the full power of the Spring TestContext Framework.
Why Use @SpringJUnitWebConfig?
When writing Spring MVC integration tests, you typically need a WebApplicationContext to instantiate MockMvc. Historically this required combining three annotations manually. @SpringJUnitWebConfig acts as a meta-annotation that packages all three together. Key use cases include:
- Testing Spring MVC controllers end-to-end without deploying to a server.
- Verifying request mappings, view resolution, and response payloads in isolation.
- Reducing annotation clutter on test classes in large projects.
Definition of SpringJUnitWebConfigVersion: 7.0.6 package org.springframework.test.context.junit.jupiter.web;
@ExtendWith(SpringExtension.class)
@ContextConfiguration
@WebAppConfiguration
@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface SpringJUnitWebConfig {
@AliasFor(annotation = ContextConfiguration.class, attribute = "classes")
Class<?>[] value() default {}; 1
@AliasFor(annotation = ContextConfiguration.class)
Class<?>[] classes() default {}; 2
@AliasFor(annotation = ContextConfiguration.class)
String[] locations() default {}; 3
@AliasFor(annotation = ContextConfiguration.class)
Class<? extends ApplicationContextInitializer<?>>[] initializers()
default {}; 4
@AliasFor(annotation = ContextConfiguration.class)
boolean inheritLocations() default true; 5
@AliasFor(annotation = ContextConfiguration.class)
boolean inheritInitializers() default true; 6
@AliasFor(annotation = ContextConfiguration.class)
Class<? extends ContextLoader> loader()
default ContextLoader.class; 7
@AliasFor(annotation = ContextConfiguration.class)
String name() default ""; 8
@AliasFor(annotation = WebAppConfiguration.class, attribute = "value")
String resourcePath() default "src/main/webapp"; 9
}
Check out this tutorial to understand @ContextConfiguration annotation.
Example
The following example demonstrates a minimal Spring MVC controller and its corresponding integration test written with @SpringJUnitWebConfig.
package com.logicbig.example;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class GreetingController {
@GetMapping("/greet")
public String greet() {
return "Hello, World!";
}
}
package com.logicbig.example;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
@EnableWebMvc
@ComponentScan
public class WebConfig implements WebMvcConfigurer {
}
Integration Test
package com.logicbig.example;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.context.junit.jupiter.web.SpringJUnitWebConfig;
import org.springframework.test.web.servlet.assertj.MockMvcTester;
import org.springframework.web.context.WebApplicationContext;
import static org.assertj.core.api.Assertions.assertThat;
@SpringJUnitWebConfig(WebConfig.class)
public class GreetingControllerTest {
@Autowired
private WebApplicationContext wac;
private MockMvcTester mockMvc;
@BeforeEach
void setup() {
mockMvc = MockMvcTester.from(wac);
}
@Test
void testGreetEndpoint() {
assertThat(mockMvc.get().uri("/greet"))
.hasStatusOk()
.bodyText().isEqualTo("Hello, World!");
System.out.println("Greet test passed");
}
}
Output$ mvn clean test -Dtest="GreetingControllerTest"
[INFO] Scanning for projects...
[INFO]
[INFO] ---< com.logicbig.example:spring-mvc-testing-using-jUnit-web-config >---
[INFO] Building spring-mvc-testing-using-jUnit-web-config 1.0-SNAPSHOT
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- clean:3.2.0:clean (default-clean) @ spring-mvc-testing-using-jUnit-web-config ---
[INFO] Deleting D:\example-projects\spring-mvc-testing\spring-mvc-testing-using-jUnit-web-config\target
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ spring-mvc-testing-using-jUnit-web-config ---
[INFO] skip non existing resourceDirectory D:\example-projects\spring-mvc-testing\spring-mvc-testing-using-jUnit-web-config\src\main\resources
[INFO]
[INFO] --- compiler:3.15.0:compile (default-compile) @ spring-mvc-testing-using-jUnit-web-config ---
[INFO] Recompiling the module because of changed source code.
[INFO] Compiling 2 source files with javac [debug target 25] to target\classes
[INFO]
[INFO] --- resources:3.3.1:testResources (default-testResources) @ spring-mvc-testing-using-jUnit-web-config ---
[INFO] skip non existing resourceDirectory D:\example-projects\spring-mvc-testing\spring-mvc-testing-using-jUnit-web-config\src\test\resources
[INFO]
[INFO] --- compiler:3.15.0:testCompile (default-testCompile) @ spring-mvc-testing-using-jUnit-web-config ---
[INFO] Recompiling the module because of changed dependency.
[INFO] Compiling 2 source files with javac [debug target 25] to target\test-classes
[INFO]
[INFO] --- surefire:3.5.5:test (default-test) @ spring-mvc-testing-using-jUnit-web-config ---
[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] -------------------------------------------------------
[INFO] Running com.logicbig.example.GreetingControllerTest
Greet test passed
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.573 s -- in com.logicbig.example.GreetingControllerTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.535 s
[INFO] Finished at: 2026-03-24T08:59:23+08:00
[INFO] ------------------------------------------------------------------------
Mar 24, 2026 8:59:22 AM org.springframework.mock.web.MockServletContext log
INFO: Initializing Spring TestDispatcherServlet ''
Mar 24, 2026 8:59:22 AM org.springframework.test.web.servlet.TestDispatcherServlet initServletBean
INFO: Initializing Servlet ''
Mar 24, 2026 8:59:22 AM org.springframework.test.web.servlet.TestDispatcherServlet initServletBean
INFO: Completed initialization in 1 ms
Conclusion
The test output confirms that the MockMvc request to /greet receives an HTTP 200 status and the body Hello, World!, exactly as implemented in the controller. This validates that @SpringJUnitWebConfig correctly bootstraps a full WebApplicationContext without any XML or manual annotation stacking, keeping the test class minimal and focused.
Example ProjectDependencies and Technologies Used: - spring-webmvc 7.0.6 (Spring Web MVC)
Version Compatibility: 5.0.0.RELEASE - 7.0.6 Version compatibilities of spring-webmvc with this example: Versions in green have been tested.
- spring-test 7.0.6 (Spring TestContext Framework)
- junit-jupiter-engine 6.0.3 (Module "junit-jupiter-engine" of JUnit)
- jakarta.servlet-api 6.1.0 (Jakarta Servlet API documentation)
- hamcrest 3.0 (Core API and libraries of hamcrest matcher framework)
- assertj-core 3.26.3 (Rich and fluent assertions for testing in Java)
- JDK 25
- Maven 3.9.11
|
