An alternative approach is to unit test by manually instantiating the Controller and mocking out any required dependencies. While such a test will run much faster than a full integration test, its of limited value. The problem is that by manually instantiating the Controller we're bypassing Springs Dispatcher Servlet, and as a result missing out on core features like
- request URL mapping
- request deserialization
- response serialization
- exception translation
What we'd really like is the best of both worlds. The ability to test a fully functional REST controller but without the overhead of deploying the entire application to a server.
Introducing MockMvcThankfully that's exactly what MockMvc allows us to do. It stands up the Dispatcher Servlet and all required MVC components, allowing us to test an endpoint in a proper web environment, but without the overhead of running a server.
MockMvc provides a fluent API, allowing you to write tests that are self descriptive. This is a great feature as your tests will pretty much read like English, making life easier for developers coming behind you.
Defining a ControllerBefore we can put MockMvc through its paces we need a REST endpoint to test. The AccountController defined below exposes 2 endpoints, one to create an Account and one to retrieve an Account.
- createAccount - calls an AccountService to create the Account, then returns the Account along with a HTTP header specifying its location for future retrieval. The AccountService will be mocked using Mockito so that we can keep our test focus solely on the web layer.
- retrieveAccount - takes an account Id from the URL and performs some simple validation to ensure the value is greater than 9999. If the validation fails a custom InvalidAccountRequestExcption is thrown. This exception is caught and translated by an exception handler we'll define later. Next the mock AccountService is called to retrieve the specified Account, before returning it to the client.
Exception HandlerThe custom runtime exceptions thrown in getAccount are intercepted and mapped to appropriate HTTP response codes using the exception handler defined below.
MockMVC SetupThe @SpringBootTest annotation is used to specify the application configuration to load prior to running the tests. We could have referenced a test specific configuration here, but given our simple project setup its fine to use the main Application config class.
The injected WebApplicationContext is a sub component of Springs main application context and encapsulates Springs configuration for web related components such as the controller and exception handler we defined earlier.
The @MockBean annotation tells Spring to create a mock instance of AccountService and add it to the application context so that it gets injected into the AccountController. We have a handle on it in the test so that we can define its behaviour prior to running each test.
The setup method uses the statically imported webAppContextSetup method from MockMvcBuilders and the injected WebApplicationContext to build a MockMvc instance.
Create Account TestNow that we've created the MockMvc instance, its time to put it to work with a test for the create account endpoint.
On line 4 we use mockito to define the expected behaviour of the mock AccountService which was injected into the AccountController. We tell the mock that upon receiving any Account instance it should return a 12345.
Lines 6 to 9 uses mockMvc to define a HTTP POST request to the URI /api/account. The request content type is JSON and the request body contains a JSON definition of the Account to be created. Finally an accept header is set to tell the server that the client expects a JSON response.
Lines 10 to 15 use statically imported methods from MockMvcResultMatchers to perform assertions on the response. We begin by checking that the response code returned is HTTP 200 'Created' and that the content type is indeed JSON. We then check for the existence of a HTTP header 'Location' that contains the request URL for retrieving the created account. The final 3 lines use jsonPath to check that the JSON response is as expected. JsonPath is like an JSON equivalent to XPath that allows you to query JSON using path expressions. For more information take a look at their documentation.
Retrieve Account TestThe retrieve account test follows a similar format to that described above.
We begin by creating an Account object and use it to define the behaviour of the mock AccountService. The MockMvc instance is used to perform a HTTP GET request that expects a JSON response. We check the response for a HTTP 200 'OK' response code, a JSON content type and a JSON response body containing the requested account.
Retrieve Account Error Test
This test configures the mock AccountService to return null when called. This demonstrates the power of @MockBean and its ability to register a mock object with the application context, and in turn have that mock injected into the AccountController. We're able to easily test non happy path logic in our controller and ensure that throwing an AccountNotFoundException results in a HTTP 404 response to the client.
Wrapping UpIn this post you saw how MockMvc allows you to thoroughly test spring web controllers. MockMvc strikes a great balance between full integration tests and relatively low value unit tests. You get the benefit of testing a fully functional web layer without the overhead of deploying to a server.
I'm not suggesting MockMvc as an alternative to full integration tests, but rather something to compliment them. I usually write a low number of pure integration tests that focus on the happy path. MockMvc tests are faster than integration tests so are ideal when you want more granular web layer tests that will run quickly.
The sample code for this post is available on Github so feel free to pull it and have a play around. If you have any comments or questions please leave a note below.