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.

Controller Testing vs Integration Testing

Best Practices for Controller Testing

• Keep controller tests small and focused
• Mock all service dependencies
• Test:
  • HTTP methods
  • Status codes
  • Headers
  • JSON response body
• Cover success and failure scenarios
• Separate controller tests from integration tests

Conclusion

Controller testing in Spring Boot ensures that your REST APIs are correct, secure, and stable. By using:

• @WebMvcTest
• MockMvc
• @MockBean
• Mockito

you can confidently test request mappings, HTTP methods, headers, validation, and responses—without loading the full application