The fluent API in the example from the preceding section requires a few static imports, such as MockMvcRequestBuilders.*, MockMvcResultMatchers.*, and MockMvcBuilders.*. An easy way to find these classes is to search for types that match MockMvc*. If you use Eclipse or the Eclipse-based Spring Tool Suite, be sure to add them as “favorite static members” in the Eclipse preferences under Java → Editor → Content Assist → Favorites. Doing so lets you use content assist after typing the first character of the static method name. Other IDEs (such as IntelliJ) may not require any additional configuration. Check the support for code completion on static members.

You have two main options for creating an instance of MockMvc. The first is to load Spring MVC configuration through the TestContext framework, which loads the Spring configuration and injects a WebApplicationContext into the test to use to build a MockMvc instance. The following example shows how to do so:

Your second option is to manually create a controller instance without loading Spring configuration. Instead, basic default configuration, roughly comparable to that of the MVC JavaConfig or the MVC namespace, is automatically created. You can customize it to a degree. The following example shows how to do so:

Which setup option should you use?

The webAppContextSetup loads your actual Spring MVC configuration, resulting in a more complete integration test. Since the TestContext framework caches the loaded Spring configuration, it helps keep tests running fast, even as you introduce more tests in your test suite. Furthermore, you can inject mock services into controllers through Spring configuration to remain focused on testing the web layer. The following example declares a mock service with Mockito:

You can then inject the mock service into the test to set up and verify your expectations, as the following example shows:

The standaloneSetup, on the other hand, is a little closer to a unit test. It tests one controller at a time. You can manually inject the controller with mock dependencies, and it does not involve loading Spring configuration. Such tests are more focused on style and make it easier to see which controller is being tested, whether any specific Spring MVC configuration is required to work, and so on. The standaloneSetup is also a very convenient way to write ad-hoc tests to verify specific behavior or to debug an issue.

As with most “integration versus unit testing” debates, there is no right or wrong answer. However, using the standaloneSetup does imply the need for additional webAppContextSetup tests in order to verify your Spring MVC configuration. Alternatively, you can write all your tests with webAppContextSetup, in order to always test against your actual Spring MVC configuration.

No matter which MockMvc builder you use, all MockMvcBuilder implementations provide some common and very useful features. For example, you can declare an Accept header for all requests and expect a status of 200 as well as a Content-Type header in all responses, as follows:

In addition, third-party frameworks (and applications) can pre-package setup instructions, such as those in a MockMvcConfigurer. The Spring Framework has one such built-in implementation that helps to save and re-use the HTTP session across requests. You can use it as follows:

See the javadoc for ConfigurableMockMvcBuilder for a list of all MockMvc builder features or use the IDE to explore the available options.

You can perform requests that use any HTTP method, as the following example shows:

You can also perform file upload requests that internally use MockMultipartHttpServletRequest so that there is no actual parsing of a multipart request. Rather, you have to set it up to be similar to the following example:

You can specify query parameters in URI template style, as the following example shows:

You can also add Servlet request parameters that represent either query or form parameters, as the following example shows:

If application code relies on Servlet request parameters and does not check the query string explicitly (as is most often the case), it does not matter which option you use. Keep in mind, however, that query parameters provided with the URI template are decoded while request parameters provided through the param(…​) method are expected to already be decoded.

In most cases, it is preferable to leave the context path and the Servlet path out of the request URI. If you must test with the full request URI, be sure to set the contextPath and servletPath accordingly so that request mappings work, as the following example shows:

In the preceding example, it would be cumbersome to set the contextPath and servletPath with every performed request. Instead, you can set up default request properties, as the following example shows:

The preceding properties affect every request performed through the MockMvc instance. If the same property is also specified on a given request, it overrides the default value. That is why the HTTP method and URI in the default request do not matter, since they must be specified on every request.

You can define expectations by appending one or more .andExpect(..) calls after performing a request, as the following example shows:

MockMvcResultMatchers.* provides a number of expectations, some of which are further nested with more detailed expectations.

Expectations fall in two general categories. The first category of assertions verifies properties of the response (for example, the response status, headers, and content). These are the most important results to assert.

The second category of assertions goes beyond the response. These assertions let you inspect Spring MVC specific aspects, such as which controller method processed the request, whether an exception was raised and handled, what the content of the model is, what view was selected, what flash attributes were added, and so on. They also let you inspect Servlet specific aspects, such as request and session attributes.

The following test asserts that binding or validation failed:

Many times, when writing tests, it is useful to dump the results of the performed request. You can do so as follows, where print() is a static import from MockMvcResultHandlers:

As long as request processing does not cause an unhandled exception, the print() method prints all the available result data to System.out. There is also a log() method and two additional variants of the print() method, one that accepts an OutputStream and one that accepts a Writer. For example, invoking print(System.err) prints the result data to System.err, while invoking print(myWriter) prints the result data to a custom writer. If you want to have the result data logged instead of printed, you can invoke the log() method, which logs the result data as a single DEBUG message under the org.springframework.test.web.servlet.result logging category.

In some cases, you may want to get direct access to the result and verify something that cannot be verified otherwise. This can be achieved by appending .andReturn() after all other expectations, as the following example shows:

If all tests repeat the same expectations, you can set up common expectations once when building the MockMvc instance, as the following example shows:

Note that common expectations are always applied and cannot be overridden without creating a separate MockMvc instance.

When a JSON response content contains hypermedia links created with Spring HATEOAS, you can verify the resulting links by using JsonPath expressions, as the following example shows:

When XML response content contains hypermedia links created with Spring HATEOAS, you can verify the resulting links by using XPath expressions:

Servlet 3.0 asynchronous requests, supported in Spring MVC, work by exiting the Servlet container thread and allowing the application to compute the response asynchronously, after which an async dispatch is made to complete processing on a Servlet container thread.

In Spring MVC Test, async requests can be tested by asserting the produced async value first, then manually performing the async dispatch, and finally verifying the response. Below is an example test for controller methods that return DeferredResult, Callable, or reactive type such as Reactor Mono:

There are no options built into Spring MVC Test for container-less testing of streaming responses. Applications that make use of Spring MVC streaming options can use the WebTestClient to perform end-to-end, integration tests against a running server. This is also supported in Spring Boot where you can test a running server with WebTestClient. One extra advantage is the ability to use the StepVerifier from project Reactor that allows declaring expectations on a stream of data.

When setting up a MockMvc instance, you can register one or more Servlet Filter instances, as the following example shows:

Registered filters are invoked through the MockFilterChain from spring-test, and the last filter delegates to the DispatcherServlet.

Spring MVC Test is built on Servlet API mock implementations from the spring-test module and does not rely on a running container. Therefore, there are some differences when compared to full end-to-end integration tests with an actual client and a live server running.

The easiest way to think about this is by starting with a blank MockHttpServletRequest. Whatever you add to it is what the request becomes. Things that may catch you by surprise are that there is no context path by default; no jsessionid cookie; no forwarding, error, or async dispatches; and, therefore, no actual JSP rendering. Instead, “forwarded” and “redirected” URLs are saved in the MockHttpServletResponse and can be asserted with expectations.

This means that, if you use JSPs, you can verify the JSP page to which the request was forwarded, but no HTML is rendered. In other words, the JSP is not invoked. Note, however, that all other rendering technologies that do not rely on forwarding, such as Thymeleaf and Freemarker, render HTML to the response body as expected. The same is true for rendering JSON, XML, and other formats through @ResponseBody methods.

Alternatively, you may consider the full end-to-end integration testing support from Spring Boot with @SpringBootTest. See the Spring Boot Reference Guide.

There are pros and cons for each approach. The options provided in Spring MVC Test are different stops on the scale from classic unit testing to full integration testing. To be certain, none of the options in Spring MVC Test fall under the category of classic unit testing, but they are a little closer to it. For example, you can isolate the web layer by injecting mocked services into controllers, in which case you are testing the web layer only through the DispatcherServlet but with actual Spring configuration, as you might test the data access layer in isolation from the layers above it. Also, you can use the stand-alone setup, focusing on one controller at a time and manually providing the configuration required to make it work.

Another important distinction when using Spring MVC Test is that, conceptually, such tests are the server-side, so you can check what handler was used, if an exception was handled with a HandlerExceptionResolver, what the content of the model is, what binding errors there were, and other details. That means that it is easier to write expectations, since the server is not a black box, as it is when testing it through an actual HTTP client. This is generally an advantage of classic unit testing: It is easier to write, reason about, and debug but does not replace the need for full integration tests. At the same time, it is important not to lose sight of the fact that the response is the most important thing to check. In short, there is room here for multiple styles and strategies of testing even within the same project.

The framework’s own tests include many sample tests intended to show how to use Spring MVC Test. You can browse these examples for further ideas. Also, the spring-mvc-showcase project has full test coverage based on Spring MVC Test.

The most obvious question that comes to mind is “Why do I need this?” The answer is best found by exploring a very basic sample application. Assume you have a Spring MVC web application that supports CRUD operations on a Message object. The application also supports paging through all messages. How would you go about testing it?

With Spring MVC Test, we can easily test if we are able to create a Message, as follows:

What if we want to test the form view that lets us create the message? For example, assume our form looks like the following snippet:

How do we ensure that our form produce the correct request to create a new message? A naive attempt might resemble the following:

This test has some obvious drawbacks. If we update our controller to use the parameter message instead of text, our form test continues to pass, even though the HTML form is out of synch with the controller. To resolve this we can combine our two tests, as follows:

This would reduce the risk of our test incorrectly passing, but there are still some problems:

The overall problem is that testing a web page does not involve a single interaction. Instead, it is a combination of how the user interacts with a web page and how that web page interacts with other resources. For example, the result of a form view is used as the input to a user for creating a message. In addition, our form view can potentially use additional resources that impact the behavior of the page, such as JavaScript validation.

This section describes how to integrate MockMvc and HtmlUnit. Use this option if you want to use the raw HtmlUnit libraries.

In the previous sections, we have seen how to use MockMvc in conjunction with the raw HtmlUnit APIs. In this section, we use additional abstractions within the Selenium WebDriver to make things even easier.

In the previous section, we saw how to use MockMvc with WebDriver. In this section, we use Geb to make our tests even Groovy-er.

As with server-side tests, the fluent API for client-side tests requires a few static imports. Those are easy to find by searching for MockRest*. Eclipse users should add MockRestRequestMatchers.* and MockRestResponseCreators.* as “favorite static members” in the Eclipse preferences under Java → Editor → Content Assist → Favorites. That allows using content assist after typing the first character of the static method name. Other IDEs (such IntelliJ) may not require any additional configuration. Check for the support for code completion on static members.

Spring MVC Test’s own tests include example tests of client-side REST tests.