Controller Testing

Controller testing in Spring Boot focuses on verifying that your REST APIs and web endpoints work correctly. It ensures that URLs, request mappings, HTTP methods, status codes, headers, and JSON responses behave exactly as expected—without testing the entire application stack.

Spring Boot provides powerful testing tools like @WebMvcTest, MockMvc, and Mockito to make controller testing fast, isolated, and reliable.

What is Controller Testing?

Controller Testing in Spring Boot is used to test REST APIs or web controllers without running the full application.

It ensures that your HTTP endpoints return the correct status codes, responses, and JSON data.

? Controller testing focuses only on the web layer, not business logic or database.

Why Controller Testing is Important

Controller testing helps you:

Validate REST API behavior
Verify correct HTTP methods (GET, POST, PUT, DELETE)
Ensure proper status codes and response headers
Validate JSON request and response structure
Test input validation and exception handling
Catch bugs early without starting the full application

Controller tests are much faster than integration tests and are ideal for API-first development.

Tools Used for Controller Testing

Spring Boot provides powerful tools for controller testing:

@WebMvcTest – Loads only controller-related beans
MockMvc – Simulates HTTP requests
@MockBean – Mocks service layer dependencies
Jackson ObjectMapper – Converts objects to JSON

Best Annotation for Controller Testing

`@WebMvcTest`

@WebMvcTest is the best and most recommended annotation for controller testing in Spring Boot. It is designed specifically to test REST controllers and web endpoints in isolation.

What @WebMvcTest Does

@WebMvcTest loads only the web layer of the application.

Included Components

Controllers
Filters
Jackson JSON configuration
Spring MVC infrastructure

Excluded Components

Service layer
Repository layer
Database configuration

Because unnecessary layers are excluded, controller tests become lightweight, fast, and highly focused.

MockMvc – Core Tool for Controller Testing

MockMvc is the heart of controller testing. It allows you to simulate HTTP requests and validate responses without starting a real server.

What You Can Do with MockMvc

Simulate HTTP requests:
- GET
- POST
- PUT
- DELETE
Test @RequestMapping and endpoint URLs
Validate:
- HTTP status codes
- Response headers
- JSON response body
Test request and response flow end-to-end at the controller level

Basic Controller Test Example

Controller testing ensures that your REST API endpoints behave correctly.

It checks whether the controller:

Receives the correct HTTP request
Calls the service layer properly
Returns the correct HTTP status and response body

Sample Controller

@RestController
@RequestMapping("/users")
publicclassUserController {

privatefinal UserService userService;

publicUserController(UserService userService) {
this.userService = userService;
    }

@GetMapping("/{id}")
public UsergetUser(@PathVariable Long id) {
return userService.getUserById(id);
    }
}

Controller Test Using @WebMvcTest

@WebMvcTest(UserController.class)
classUserControllerTest {

@Autowired
private MockMvc mockMvc;

@MockBean
private UserService userService;

@Test
voidtestGetUserById()throws Exception {

Useruser=newUser(1L,"Alice");
        Mockito.when(userService.getUserById(1L)).thenReturn(user);

        mockMvc.perform(get("/users/1"))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$.name").value("Alice"));
    }
}

Why `@MockBean` Is Used in Controller Tests

@MockBean replaces the real service bean with a mocked version.

Benefits

No database interaction
Tests remain isolated
Predictable and controlled responses
Faster execution

In controller testing, services should always be mocked.

Testing POST Requests with MockMvc

Example: Creating a user (common in Todo or E-Commerce APIs)

@Test
voidtestCreateUser()throws Exception {

Useruser=newUser(1L,"John");

    Mockito.when(userService.createUser(Mockito.any()))
           .thenReturn(user);

    mockMvc.perform(post("/users")
            .contentType(MediaType.APPLICATION_JSON)
            .content("{\\"name\\":\\"John\\"}"))
           .andExpect(status().isOk())
           .andExpect(jsonPath("$.name").value("John"));
}

Testing PUT and DELETE Requests

In addition to GET and POST requests, it’s important to test update and delete operations in your APIs to ensure data can be modified or removed correctly.

PUT – Update Resource

Tests the API’s ability to update an existing resource and ensures the correct HTTP 200 OK status is returned.

mockMvc.perform(put("/users/1")
        .contentType(MediaType.APPLICATION_JSON)
        .content("{\\"name\\":\\"Updated Name\\"}"))
       .andExpect(status().isOk());

DELETE – Remove Resource

Verifies that the API successfully deletes a resource and returns the correct HTTP 204 No Content response.

mockMvc.perform(delete("/users/1"))
       .andExpect(status().isNoContent());

Testing Validation Errors

Controller tests should verify how your API handles invalid input. This ensures that:

Bean validation rules are applied
Clients receive meaningful error responses
The API behaves predictably for bad requests

Example: Testing a POST Request with Invalid Data

@Test
voidtestValidationError()throws Exception {

    mockMvc.perform(post("/users")
            .contentType(MediaType.APPLICATION_JSON)
            .content("{\\"name\\":\\"\\"}"))
           .andExpect(status().isBadRequest());
}

Testing Response Headers

When testing controllers, it’s important to not only check status codes and response body, but also HTTP headers. Headers can contain important metadata such as Content-Type, Location, caching info, or custom headers.

mockMvc.perform(get("/users/1"))
       .andExpect(status().isOk())
       .andExpect(header().exists("Content-Type"));

Testing Specific Header Values

You can also check the exact value of a header:

mockMvc.perform(get("/users/1"))
       .andExpect(status().isOk())
       .andExpect(header().string("Content-Type","application/json"));

.header().string() verifies the header value matches exactly.
Useful for APIs that return custom headers like X-Rate-Limit or Location.

Testing Secured Controllers

For Spring Security–protected endpoints, use @WithMockUser.

@WithMockUser(roles = "ADMIN")
@Test
voidtestAdminAccess()throws Exception {
    mockMvc.perform(get("/admin/users"))
           .andExpect(status().isOk());
}

This allows you to:

Test role-based access
Validate security rules
Avoid real authentication

When NOT to Use `@WebMvcTest`

Avoid @WebMvcTest when:

You need database access
You want to test service + repository interaction
You are doing end-to-end testing

? Use @SpringBootTest in these cases.