Testing REST APIs with MockMvc and REST Assured

1. Web Layer Testing with MockMvc

In the previous lesson, we briefly touched on test slices with @WebMvcTest. This annotation is the key to testing your controller layer in isolation. When you use @WebMvcTest, Spring Boot only configures the web layer (controllers, ControllerAdvice, JSON converters, etc.) and does not load your service or repository beans. This makes for a fast and focused test.

To interact with this mock web environment, we use MockMvc. It allows you to perform HTTP requests and assert responses without needing to start a full HTTP server.

As you saw, the process involves a few key components:

• @WebMvcTest(VehicleController.class): Tells Spring to only configure the VehicleController and related web infrastructure.
• @Autowired private MockMvc mockMvc;: Injects the main entry point for server-side Spring MVC test support.
• @MockBean private VehicleServiceImpl vehicleService;: Since @WebMvcTest doesn't load @Service beans, we must provide a mock implementation for any dependencies the controller has.

Let's look at a typical test using MockMvc's fluent API:

@WebMvcTest(VehicleController.class)
public class VehicleControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private VehicleService vehicleService;

    @Autowired
    private ObjectMapper objectMapper; // For converting objects to JSON strings

    @Test
    void whenPostVehicle_thenCreateVehicle() throws Exception {
        // Arrange
        Vehicle vehicle = new Vehicle("VIN123", "Toyota");
        // Mock the service layer's behavior
        when(vehicleService.createVehicle(any(Vehicle.class))).thenReturn(vehicle);

        // Act & Assert
        mockMvc.perform(post("/api/vehicles")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(vehicle)))
                .andExpect(status().isCreated())
                .andExpect(jsonPath("$.vin", is("VIN123")))
                .andExpect(jsonPath("$.make", is("Toyota")));
                
        // Verify that the service method was called
        verify(vehicleService).createVehicle(any(Vehicle.class));
    }
}

In this test, mockMvc.perform(...) sends the request. The andExpect(...) methods then assert the response status and content using JsonPath expressions (e.g., $.vin) to inspect the JSON body. This is a powerful way to verify API contracts.

2. Simplified API Testing with REST Assured

While MockMvc is powerful and built-in, its syntax can be verbose. REST Assured is a popular alternative that offers a highly readable, BDD-style (Behavior-Driven Development) fluent API. Its given-when-then structure makes tests easier to read and write.

The great thing about REST Assured is that it can be used in two ways:

1. As a more readable wrapper around MockMvc for fast slice tests.
2. As a client to test a fully running application for true integration tests.

Let's explore both, using a more detailed guide.

Approach A: REST Assured with MockMvc

You can combine the readability of REST Assured with the speed of MockMvc. This is often the sweet spot for controller testing.

Here is the equivalent of our previous test, now using RestAssuredMockMvc:

@WebMvcTest(BookController.class)
public class BookControllerRestAssuredTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private BookService bookService;
    
    @BeforeEach
    void setUp() {
        // Bind REST Assured to the MockMvc instance
        RestAssuredMockMvc.mockMvc(mockMvc);
    }

    @Test
    void shouldCreateNewBook() {
        // Arrange
        when(bookService.createNewBook(any(BookRequest.class))).thenReturn(42L);
        BookRequest bookRequest = new BookRequest("Effective Java", "978-0134685991", "Joshua Bloch");

        // Act & Assert
        given()
            .contentType("application/json")
            .body(bookRequest)
        .when()
            .post("/api/books")
        .then()
            .statusCode(201)
            .header("Location", containsString("/api/books/42"));
    }
}

Notice how the given() block sets up the request, when() executes it, and then() makes assertions. Many developers find this syntax more natural and readable than the MockMvc builder chain.

Approach B: REST Assured with a Live Server

For a full integration test, you can use REST Assured to make real HTTP calls to your application running on a random port. This validates the entire stack, from the HTTP server down to the database (which could be a real one managed by Testcontainers!).

This approach provides the highest level of confidence but is also the slowest, as it requires starting the full application context.

Testing Secured Endpoints

In a real-world application, many endpoints are secured. A key skill for a senior engineer is knowing how to test these. Spring Security's test support integrates seamlessly with both MockMvc and REST Assured.

Using @WithMockUser is particularly clean for setting up the security context for a test method:

@Test
@WithMockUser(username = "duke", roles = {"ADMIN"})
void shouldAllowBookCreationForAdminUsers() {
    given()
        // ... request setup
    .when()
        .post("/api/books")
    .then()
        .statusCode(201);
}

@Test
@WithMockUser(username = "charlie", roles = {"USER"})
void shouldBlockBookCreationForNonAdminUsers() {
    given()
        // ... request setup
    .when()
        .post("/api/books")
    .then()
        .statusCode(403); // Forbidden
}

Conclusion

You now have a solid understanding of two primary approaches for testing REST APIs in Spring Boot. Knowing the strengths and weaknesses of both MockMvc and REST Assured allows you to write effective, readable, and maintainable tests, a hallmark of a senior developer.

Key Takeaways:

• MockMvc is Spring's native solution for testing the web layer in isolation (@WebMvcTest) without a running server. It's fast and requires no extra dependencies.
• REST Assured offers a highly readable given-when-then DSL for API testing. It improves test clarity and can be used for both mock-based and live-server tests.
• RestAssuredMockMvc provides the best of both worlds: the readable syntax of REST Assured combined with the speed of MockMvc.
• Testing secured endpoints is straightforward using annotations like @WithMockUser, which integrates with Spring Security's test support.

Preview of the Next Lesson:
We've now completed our deep dive into the practical aspects of building and testing a Spring Boot application. We've covered testing from the unit level all the way to the API contract. In our next lesson, we will shift gears from implementation details to high-level architecture. We'll tackle our first system design challenge: "Outline a high-level architecture for a system design prompt (e.g., TinyURL), defining service boundaries and core components." This will prepare you for the system design portion of your interviews.