unit-test-controller-layer_skill

Overview

This skill provides practical patterns for unit testing Spring REST controllers using MockMvc and @WebMvcTest. It focuses on isolating the web layer by mocking service dependencies to validate request/response mapping, validation, headers, content negotiation, and exception handling. Use it to build fast, focused controller tests without running a full integration context.

How this skill works

The patterns show a standalone MockMvc setup (MockMvcBuilders.standaloneSetup) or lightweight @WebMvcTest configuration, with all injected services mocked via Mockito. Tests perform HTTP requests (GET/POST/PUT/PATCH/DELETE) against controller endpoints and assert status codes, response bodies using JsonPath, headers, and validation error payloads. Error scenarios are simulated by configuring mocked services to throw exceptions.

When to use it

• Verifying request/response mapping and JSON output for a controller
• Testing request parameter binding, path variables, and query filters
• Validating input constraints and asserting 400 validation responses
• Confirming exception handling and mapping to appropriate HTTP statuses
• Testing content negotiation and response/request headers in isolation

Best practices

• Use standalone MockMvc for single-controller tests to keep tests fast
• Mock all service and repository dependencies; controllers should only handle HTTP concerns
• Test both happy paths and error paths (404, 400, 401/403, 500) for each endpoint
• Assert JSON responses with JsonPath and verify response headers explicitly
• Keep each test focused on one behavior and verify mock interactions

Example use cases

• Unit test GET /api/users to assert JSON array structure and that service.getAllUsers() is called
• POST /api/users validation test that sends invalid JSON and expects 400 with errors array
• Simulate service throwing UserNotFoundException and assert controller returns 404 with error message
• PUT /api/users/{id} test that verifies update returns 200 and the updated fields
• Test Authorization header handling by asserting endpoints return 401 without a token and 200 with a valid header