Introduction

These two annotations are related, but they are not interchangeable. @AutoConfigureWebMvc imports typical Spring MVC test auto-configuration, while @AutoConfigureMockMvc specifically adds and configures the MockMvc testing facility. In practice, most developers use @WebMvcTest or @SpringBootTest plus @AutoConfigureMockMvc, and rarely apply @AutoConfigureWebMvc directly.

What @AutoConfigureWebMvc Does

@AutoConfigureWebMvc is about bringing in Spring MVC test auto-configuration for a typical MVC test setup. Conceptually, it focuses on the MVC infrastructure itself:

• handler mappings
• argument resolvers
• converters
• controller-related MVC configuration

It is a lower-level test auto-configuration hook. Spring Boot itself even hints that most users should prefer @WebMvcTest instead of using it directly.

So when you see @AutoConfigureWebMvc, think:

Set up MVC test infrastructure

not:

Give me a MockMvc bean automatically for every scenario

What @AutoConfigureMockMvc Does

@AutoConfigureMockMvc is more specific. It enables and configures MockMvc, which is the API for sending mock HTTP requests into the Spring MVC layer without starting a real HTTP server.

Example:

1import org.junit.jupiter.api.Test;
2import org.springframework.beans.factory.annotation.Autowired;
3import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
4import org.springframework.boot.test.context.SpringBootTest;
5import org.springframework.test.web.servlet.MockMvc;
6
7import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
8import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
9
10@SpringBootTest
11@AutoConfigureMockMvc
12class UserControllerTest {
13
14    @Autowired
15    MockMvc mockMvc;
16
17    @Test
18    void shouldReturnOk() throws Exception {
19        mockMvc.perform(get("/users"))
20               .andExpect(status().isOk());
21    }
22}

This is the common full-application test style when you want a real Spring Boot application context but still want to drive it through MockMvc.

How They Relate

A useful mental model is:

• '@AutoConfigureWebMvc: configure MVC test infrastructure'
• '@AutoConfigureMockMvc: configure the MockMvc testing client on top of that ecosystem'

They are related because MockMvc depends on MVC infrastructure, but they are not the same layer of concern.

That is also why Spring Boot’s MockMvc auto-configuration is described as coming after Web MVC auto-configuration.

What Most People Should Use Instead

In everyday Spring Boot testing, these are the more common choices:

1. @WebMvcTest
2. @SpringBootTest plus @AutoConfigureMockMvc

@WebMvcTest is designed for focused MVC-slice tests and already auto-configures MockMvc.

1import org.junit.jupiter.api.Test;
2import org.springframework.beans.factory.annotation.Autowired;
3import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
4import org.springframework.test.web.servlet.MockMvc;
5
6import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
7import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
8
9@WebMvcTest
10class UserControllerSliceTest {
11
12    @Autowired
13    MockMvc mockMvc;
14
15    @Test
16    void shouldReturnOk() throws Exception {
17        mockMvc.perform(get("/users"))
18               .andExpect(status().isOk());
19    }
20}

That is why @AutoConfigureWebMvc is relatively uncommon in hand-written tests. Higher-level annotations usually give a better fit.

When @AutoConfigureMockMvc Is the Right Tool

Use @AutoConfigureMockMvc when:

• you want a full application context with @SpringBootTest
• you want to test through MVC without starting a real HTTP server
• you want to customize MockMvc behavior such as filter registration or printing

It is not limited to controller-slice tests.

When @AutoConfigureWebMvc Is Relevant

@AutoConfigureWebMvc matters mostly when you are composing your own test setup at a lower level and want MVC test auto-configuration imports without necessarily using the higher-level convenience annotations.

That is a more specialized use case. Most project code does not need to reach for it directly because @WebMvcTest or other test annotations already include the intended behavior more clearly.

Common Pitfalls

One common mistake is assuming @AutoConfigureWebMvc and @AutoConfigureMockMvc are alternative names for the same thing. They are not.

Another issue is adding @AutoConfigureMockMvc to a test that already uses @WebMvcTest without understanding that MockMvc is already part of the usual @WebMvcTest story.

Developers also sometimes use @SpringBootTest alone and then wonder why there is no MockMvc bean available. That is exactly the case where @AutoConfigureMockMvc is useful.

Finally, avoid using lower-level annotations directly when a higher-level slice annotation expresses the test’s intent more clearly. Test configuration should communicate scope, not just mechanics.

Summary

• '@AutoConfigureWebMvc imports typical Spring MVC test auto-configuration.'
• '@AutoConfigureMockMvc specifically enables and configures MockMvc.'
• Most controller-slice tests should use @WebMvcTest, which usually already gives you MockMvc.
• For full application tests with mock HTTP requests, use @SpringBootTest plus @AutoConfigureMockMvc.
• '@AutoConfigureWebMvc is more of a lower-level building block than an everyday annotation for most tests.'