WebAppConfiguration in Spring Tests

1. Overview

In this article, we’ll explore the @WebAppConfiguration annotation in Spring, why we need it in our integration tests and also how can we configure it so that these tests actually bootstrap a WebApplicationContext.

2. @WebAppConfiguration

Simply put, this is a class-level annotation used to create a web version of the application context in the Spring Framework.

It’s used to denote that the ApplicationContext which is bootstrapped for the test should be an instance of WebApplicationContext.

A quick note about usage – we’ll usually find this annotation in integration tests because the WebApplicationContext is used to build a MockMvc object. You can find more information about integration testing with Spring here.

3. Loading a WebApplicationContext

Starting with Spring 3.2, there is now support for loading a WebApplicationContext in integration tests:

@WebAppConfiguration
@ContextConfiguration(classes = WebConfig.class)
public class EmployeeControllerTest {
    ...
}

This instructs the TestContext framework that a WebApplicationContext should be loaded for the test.

And, in the background a MockServletContext is created and supplied to our test’s WebApplicationContext by the TestContext framework.

3.1. Configuration Options

By default, the base resource path for the WebApplicationContext will be set to “file:src/main/webapp”, which is the default location for the root of the WAR in a Maven Project.

However, we can override this by simple providing an alternate path to the @WebAppConfiguration annotation:

@WebAppConfiguration("src/test/webapp")

We can also reference a base resource path from the classpath instead of the file system:

@WebAppConfiguration("classpath:test-web-resources")

3.2. Caching

Once the WebApplicationContext is loaded it will be cached and reused for all subsequent tests that declare the same unique context configuration within the same test suite.

For further details on caching, you can consult the Context caching section of the reference manual.

4. Using @WebAppConfiguration in Tests

Now that we understand why do we need to add the @WebAppConfiguration annotation in our test classes, let’s see what happens if we miss adding it when we are using a WebApplicationContext.

@RunWith(SpringJUnit4ClassRunner.class)
// @WebAppConfiguration omitted on purpose
@ContextConfiguration(classes = WebConfig.class)
public class EmployeeTest {

    @Autowired
    private WebApplicationContext webAppContext;
    private MockMvc mockMvc;

    @Before
    public void setup() {
        MockitoAnnotations.initMocks(this);
        mockMvc = MockMvcBuilders.webAppContextSetup(webAppContext).build();
    }
    
    ...
}

Notice that we commented out the annotation to simulate the scenario in which we forget to add it. Here it’s easy to see why the test will fail when we run the JUnit test:  we are trying to autowire the WebApplicationContext in a class where we haven’t set one.

A more typical example however is a test that uses a web-enabled Spring configuration; that’s actually enough to make the test break.

Let’s have a look:

@RunWith(SpringJUnit4ClassRunner.class)
// @WebAppConfiguration omitted on purpose
@ContextConfiguration(classes = WebConfig.class)
public class EmployeeTestWithoutMockMvc {

    @Autowired
    private EmployeeController employeeController;

    ...
}

Even though the above example isn’t autowiring a WebApplicationContext it will still fail because it’s trying to use a web-enabled configuration – WebConfig:

@Configuration
@EnableWebMvc
@ComponentScan("com.baeldung.web")
public class WebConfig extends WebMvcConfigurerAdapter {
    ...
}

The annotation @EnableWebMvc is the culprit here – that will basically require a web enabled Spring context, and without it – we’ll see the test fail:

Caused by: org.springframework.beans.factory.NoSuchBeanDefinitionException: 
  No qualifying bean of type [javax.servlet.ServletContext] found for dependency: 
    expected at least 1 bean which qualifies as autowire candidate for this dependency. 

Dependency annotations: 
  {@org.springframework.beans.factory.annotation.Autowired(required=true)}
    at o.s.b.f.s.DefaultListableBeanFactory
      .raiseNoSuchBeanDefinitionException(DefaultListableBeanFactory.java:1373)
    at o.s.b.f.s.DefaultListableBeanFactory
      .doResolveDependency(DefaultListableBeanFactory.java:1119)
    at o.s.b.f.s.DefaultListableBeanFactory
      .resolveDependency(DefaultListableBeanFactory.java:1014)
    at o.s.b.f.a.AutowiredAnnotationBeanPostProcessor$AutowiredFieldElement
      .inject(AutowiredAnnotationBeanPostProcessor.java:545)
    ... 43 more

So that’s the problem that we’re easily fixing by adding the @WebAppConfiguration annotation to our tests.

5. Conclusion

In this article we showed how we can let the TestContext framework to load a WebApplicationContext into our integration tests just by adding the annotation.

Finally, we looked in the examples that even though if we add the @ContextConfiguration to the test, this won’t be able to work unless we add the @WebAppConfiguration annotation.

The implementation of the examples in this article are available in our repository on GitHub.