Course topics

By WebNest Studio Engineering Team

Spring Boot Tutorial

Web Layer Tests with @WebMvcTest

A controller does more than call a service: it maps URLs and HTTP methods, binds path variables and JSON bodies, runs validation, converts exceptions to status codes, and serialises responses. None of that is exercised by a unit test that calls the controller method directly.

@WebMvcTest starts a slice of the application containing only the web layer — controllers, @ControllerAdvice, Jackson, validation, filters and security configuration — and gives you MockMvc to send requests without a real server. This lesson uses Spring Boot 4's test starters and the AssertJ-based MockMvcTester.

Dependencies in Spring Boot 4

Spring Boot 4 splits test support by technology. Add spring-boot-starter-webmvc-test (test scope) for MVC slice tests; it includes the general test starter. The annotation now lives in org.springframework.boot.webmvc.test.autoconfigure. Services and other dependencies of the controller are replaced with @MockitoBean — Spring Boot's old @MockBean was removed in version 4.

What the Slice Includes

@WebMvcTest(ProductController.class) loads that controller plus web infrastructure: @ControllerAdvice, @JsonComponent/@JacksonComponent, converters, filters, WebMvcConfigurer beans and Spring Security configuration. It does not load @Service, @Repository or other components, so startup is fast and failures point at the web layer.

MockMvc vs MockMvcTester

The classic MockMvc API uses static builders and andExpect(...) matchers. MockMvcTester (Spring Framework 6.2+) wraps it with fluent AssertJ assertions: assertThat(mvc.get().uri("/api/products/1")).hasStatusOk().bodyJson().... Spring Boot auto-configures both in @WebMvcTest when AssertJ is present. New tests should prefer MockMvcTester.

What to Test

For each endpoint, cover: the happy path status and JSON shape; validation failures (400 with a ProblemDetail body); not-found and conflict mappings from your exception handler; and security rules (see the Security testing lesson). Check the response JSON with JSON paths or by comparing with an expected JSON document — this catches accidental field renames that would break API clients.

Examples

Test dependency

Java
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc-test</artifactId>
    <scope>test</scope>
</dependency>
Output
(Brings JUnit, Mockito, AssertJ, Spring Test, MockMvc and the @WebMvcTest slice.)

The controller under test

Java
@RestController
@RequestMapping("/api/products")
public class ProductController {

    private final ProductService service;

    public ProductController(ProductService service) {
        this.service = service;
    }

    @GetMapping("/{id}")
    public ProductDto get(@PathVariable Long id) {
        return service.find(id).orElseThrow(() -> new ProductNotFoundException(id));
    }

    @PostMapping
    public ResponseEntity<ProductDto> create(@Valid @RequestBody CreateProductRequest req) {
        ProductDto created = service.create(req);
        return ResponseEntity.created(URI.create("/api/products/" + created.id())).body(created);
    }
}

public record CreateProductRequest(@NotBlank String name, @Positive BigDecimal price) {}
public record ProductDto(Long id, String name, BigDecimal price) {}
Output
(ProductNotFoundException is mapped to 404 by a @RestControllerAdvice returning ProblemDetail.)

Slice tests with MockMvcTester and @MockitoBean

Java
@WebMvcTest(ProductController.class)
class ProductControllerTest {

    @Autowired MockMvcTester mvc;
    @MockitoBean ProductService service;

    @Test
    void returnsProductAsJson() {
        when(service.find(1L)).thenReturn(Optional.of(new ProductDto(1L, "Hoodie", new BigDecimal("1299.00"))));

        assertThat(mvc.get().uri("/api/products/1"))
            .hasStatusOk()
            .bodyJson()
            .isLenientlyEqualTo("""
                {"id": 1, "name": "Hoodie", "price": 1299.00}
                """);
    }

    @Test
    void returns404ProblemDetailForUnknownProduct() {
        when(service.find(99L)).thenReturn(Optional.empty());

        assertThat(mvc.get().uri("/api/products/99"))
            .hasStatus(HttpStatus.NOT_FOUND)
            .bodyJson()
            .extractingPath("$.title").isEqualTo("Product not found");
    }

    @Test
    void createsProductAndReturnsLocation() {
        when(service.create(any())).thenReturn(new ProductDto(7L, "Cap", new BigDecimal("499")));

        assertThat(mvc.post().uri("/api/products")
                .contentType(MediaType.APPLICATION_JSON)
                .content("""
                    {"name": "Cap", "price": 499}
                    """))
            .hasStatus(HttpStatus.CREATED)
            .hasHeader("Location", "/api/products/7");
    }

    @Test
    void rejectsInvalidRequestBody() {
        assertThat(mvc.post().uri("/api/products")
                .contentType(MediaType.APPLICATION_JSON)
                .content("""
                    {"name": "", "price": -5}
                    """))
            .hasStatus(HttpStatus.BAD_REQUEST);
        verifyNoInteractions(service);
    }
}
Output
ProductControllerTest
  ✔ returnsProductAsJson()
  ✔ returns404ProblemDetailForUnknownProduct()
  ✔ createsProductAndReturnsLocation()
  ✔ rejectsInvalidRequestBody()
Tests run: 4 (context started in 0.9 s — only the web layer)

The same style with classic MockMvc (still common in existing code)

Java
@WebMvcTest(ProductController.class)
class ProductControllerClassicTest {

    @Autowired MockMvc mockMvc;
    @MockitoBean ProductService service;

    @Test
    void returnsProduct() throws Exception {
        when(service.find(1L)).thenReturn(Optional.of(new ProductDto(1L, "Hoodie", new BigDecimal("1299.00"))));

        mockMvc.perform(get("/api/products/1").accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.name").value("Hoodie"))
            .andExpect(jsonPath("$.price").value(1299.00))
            .andDo(print());
    }
}
Output
MockHttpServletResponse:
           Status = 200
     Content type = application/json
             Body = {"id":1,"name":"Hoodie","price":1299.00}

Common Mistakes

  • Using @SpringBootTest for every controller test, making the suite slow and failures hard to locate.
  • Still using @MockBean from Spring Boot 3 examples; it was removed in Spring Boot 4 — use @MockitoBean.
  • Forgetting that @WebMvcTest loads your SecurityFilterChain, then being surprised by 401/403 responses — test security explicitly with @WithMockUser.
  • Only asserting the status code, missing broken JSON field names that clients depend on.
  • Mocking the controller itself or calling its methods directly, bypassing binding, validation and exception handling.

Exercise

Using the lesson's Test dependency example, create a small implementation or design sketch that demonstrates @WebMvcTest loads only the web layer; dependencies are replaced with @MockitoBean.. Add a test case or scenario that would catch Using @SpringBootTest for every controller test, making the suite slow and failures hard to locate., and describe the expected result.

Show hints
  • Start with Dependencies in Spring Boot 4 and compare your approach with Test dependency. Identify the decision or behavior the lesson recommends.
  • Walk through your scenario step by step. Confirm that it follows @WebMvcTest loads only the web layer; dependencies are replaced with @MockitoBean. and that it would catch the failure described by Using @SpringBootTest for every controller test, making the suite slow and failures hard to locate..

Quick quiz

1. Which choice is a mistake to avoid in Web Layer Tests with @WebMvcTest?

  • A. @WebMvcTest loads only the web layer; dependencies are replaced with @MockitoBean.
  • B. Using @SpringBootTest for every controller test, making the suite slow and failures hard to locate.
  • C. Still using @MockBean from Spring Boot 3 examples; it was removed in Spring Boot 4 — use @MockitoBean.
Show answer

B. Avoid this approach: Using @SpringBootTest for every controller test, making the suite slow and failures hard to locate. The lesson recommends: @WebMvcTest loads only the web layer; dependencies are replaced with @MockitoBean.

Interview questions

How would you apply the guidance in Dependencies in Spring Boot 4 to a real task, and what failure would you guard against?

Show answer

@WebMvcTest loads only the web layer; dependencies are replaced with @MockitoBean. Apply this in Dependencies in Spring Boot 4; the example Test dependency shows one way to do it. Avoid Using @SpringBootTest for every controller test, making the suite slow and failures hard to locate. and explain how your implementation or design prevents that failure.

Key Points to Remember

  • @WebMvcTest loads only the web layer; dependencies are replaced with @MockitoBean.
  • Spring Boot 4 uses spring-boot-starter-webmvc-test for MVC slice tests.
  • MockMvcTester provides fluent AssertJ assertions for status, headers and JSON.
  • Test happy paths, validation errors, error mappings and security for every endpoint.
  • Compare JSON bodies to catch accidental API contract changes.

Practice in the playground

Write and run your own code for this topic, or start from the exercise or an example. Runs plain Java 17. Frameworks such as Spring, and databases, are not available here. Your code for each topic is kept in this browser.

Run the examples

Change an input, predict the result, then compare it with the output. Explain why the result changes.

These examples need a JDK project with their libraries on your computer, so they can be copied but not run here. Codelab runs Python, FastAPI backends with SQLite, plain Java 17 and HTML/CSS/JavaScript.

WebNest Studio

Written by

WebNest Studio Engineering Team

Practical lessons from developers working with Java, Python, React, databases and production systems.

Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering