Class MockMvcTester
MockMvcTester
provides support for testing Spring MVC applications
with MockMvc
for server request handling using
AssertJ.
A tester instance can be created from a WebApplicationContext
:
// Create an instance with default settings
MockMvcTester mvc = MockMvcTester.from(applicationContext);
// Create an instance with a custom Filter
MockMvcTester mvc = MockMvcTester.from(applicationContext,
builder -> builder.addFilters(filter).build());
A tester can be created in standalone mode by providing the controller instances to include:
// Create an instance for PersonController
MockMvcTester mvc = MockMvcTester.of(new PersonController());
Simple, single-statement assertions can be done wrapping the request
builder in assertThat()
provides access to assertions. For instance:
// perform a GET on /hi and assert the response body is equal to Hello
assertThat(mvc.get().uri("/hi")).hasStatusOk().hasBodyTextEqualTo("Hello");
For more complex scenarios the result of the exchange can be assigned in a variable to run multiple assertions:
// perform a POST on /save and assert the response body is empty
MvcTestResult result = mvc.post().uri("/save").exchange();
assertThat(result).hasStatus(HttpStatus.CREATED);
assertThat(result).body().isEmpty();
If the request is processing asynchronously, exchange
waits for
its completion, either using the
default
timeout or a given one. If you prefer to get the result of an
asynchronous request immediately, use asyncExchange
:
// perform a POST on /save and assert an asynchronous request has started
assertThat(mvc.post().uri("/save").asyncExchange()).request().hasAsyncStarted();
You can also perform requests using the static builders approach that
MockMvc
uses. For instance:
// perform a GET on /hi and assert the response body is equal to Hello
assertThat(mvc.perform(get("/hi")))
.hasStatusOk().hasBodyTextEqualTo("Hello");
Use this approach if you have a custom RequestBuilder
implementation
that you'd like to integrate here. This approach is also invoking MockMvc
without any additional processing of asynchronous requests.
One main difference between MockMvc
and MockMvcTester
is
that an unresolved exception is not thrown directly when using
MockMvcTester
. Rather an MvcTestResult
is available with an
unresolved exception.
Both resolved and unresolved exceptions are considered a failure that can
be asserted as follows:
// perform a GET on /boom and assert the message for the exception
assertThat(mvc.get().uri("/boom")).hasFailed()
.failure().hasMessage("Test exception");
Any attempt to access the result with an unresolved exception will
throw an AssertionError
:
// throw an AssertionError with an unresolved exception
assertThat(mvc.get().uri("/boom")).hasStatus5xxServerError();
MockMvcTester
can be configured with a list of
message converters to allow the response
body to be deserialized, rather than asserting on the raw values.
- Since:
- 6.2
- Author:
- Stephane Nicoll, Brian Clozel
-
Nested Class Summary
Modifier and TypeClassDescriptionfinal class
A builder forMockMultipartHttpServletRequest
that supports AssertJ.final class
A builder forMockHttpServletRequest
that supports AssertJ. -
Method Summary
Modifier and TypeMethodDescriptionstatic MockMvcTester
Create an instance that delegates to the givenMockMvc
instance.delete()
Prepare an HTTP DELETE request.static MockMvcTester
from
(WebApplicationContext applicationContext) Shortcut to create an instance using the given fully initialized (i.e., refreshed)WebApplicationContext
.static MockMvcTester
from
(WebApplicationContext applicationContext, Function<DefaultMockMvcBuilder, MockMvc> customizations) Create an instance using the given, fully initialized (i.e., refreshed)WebApplicationContext
.get()
Prepare an HTTP GET request.head()
Prepare an HTTP HEAD request.method
(HttpMethod method) Prepare a request for the specifiedHttpMethod
.static MockMvcTester
Shortcut to create an instance by registering one or more@Controller
instances.static MockMvcTester
of
(Collection<?> controllers, Function<StandaloneMockMvcBuilder, MockMvc> customizations) Create an instance by registering one or more@Controller
instances and configuring Spring MVC infrastructure programmatically.options()
Prepare an HTTP OPTIONS request.patch()
Prepare an HTTP PATCH request.perform
(RequestBuilder requestBuilder) Perform a request using the givenRequestBuilder
and return aresult
that can be used with standardAssertJ
assertions.post()
Prepare an HTTP POST request.put()
Prepare an HTTP PUT request.withHttpMessageConverters
(Iterable<HttpMessageConverter<?>> httpMessageConverters) Return a new instance using the specified message converters.
-
Method Details
-
create
Create an instance that delegates to the givenMockMvc
instance.- Parameters:
mockMvc
- the MockMvc instance to delegate calls to
-
from
public static MockMvcTester from(WebApplicationContext applicationContext, Function<DefaultMockMvcBuilder, MockMvc> customizations) Create an instance using the given, fully initialized (i.e., refreshed)WebApplicationContext
. The givencustomizations
are applied to theDefaultMockMvcBuilder
that ultimately creates the underlyingMockMvc
instance.If no further customization of the underlying
MockMvc
instance is required, usefrom(WebApplicationContext)
.- Parameters:
applicationContext
- the application context to detect the Spring MVC infrastructure and application controllers fromcustomizations
- a function that creates aMockMvc
instance based on aDefaultMockMvcBuilder
- See Also:
-
from
Shortcut to create an instance using the given fully initialized (i.e., refreshed)WebApplicationContext
.Consider using
from(WebApplicationContext, Function)
if further customization of the underlyingMockMvc
instance is required.- Parameters:
applicationContext
- the application context to detect the Spring MVC infrastructure and application controllers from- See Also:
-
of
public static MockMvcTester of(Collection<?> controllers, Function<StandaloneMockMvcBuilder, MockMvc> customizations) Create an instance by registering one or more@Controller
instances and configuring Spring MVC infrastructure programmatically.This allows full control over the instantiation and initialization of controllers and their dependencies, similar to plain unit tests while also making it possible to test one controller at a time.
- Parameters:
controllers
- one or more@Controller
instances or@Controller
types to test; a type (Class
) will be turned into an instancecustomizations
- a function that creates aMockMvc
instance based on aStandaloneMockMvcBuilder
, typically to configure the Spring MVC infrastructure- See Also:
-
of
Shortcut to create an instance by registering one or more@Controller
instances.The minimum infrastructure required by the
DispatcherServlet
to serve requests with annotated controllers is created. Consider usingof(Collection, Function)
if additional configuration of the MVC infrastructure is required.- Parameters:
controllers
- one or more@Controller
instances or@Controller
types to test; a type (Class
) will be turned into an instance- See Also:
-
withHttpMessageConverters
public MockMvcTester withHttpMessageConverters(Iterable<HttpMessageConverter<?>> httpMessageConverters) Return a new instance using the specified message converters.If none are specified, only basic assertions on the response body can be performed. Consider registering a suitable JSON converter for asserting against JSON data structures.
- Parameters:
httpMessageConverters
- the message converters to use- Returns:
- a new instance using the specified converters
-
get
Prepare an HTTP GET request.The returned builder can be wrapped in
assertThat
to enable assertions on the result. For multi-statements assertions, useexchange()
to assign the result. To control the time to wait for asynchronous request to complete on a per-request basis, useexchange(Duration)
.- Returns:
- a request builder for specifying the target URI
-
head
Prepare an HTTP HEAD request.The returned builder can be wrapped in
assertThat
to enable assertions on the result. For multi-statements assertions, useexchange()
to assign the result. To control the time to wait for asynchronous request to complete on a per-request basis, useexchange(Duration)
.- Returns:
- a request builder for specifying the target URI
-
post
Prepare an HTTP POST request.The returned builder can be wrapped in
assertThat
to enable assertions on the result. For multi-statements assertions, useexchange()
to assign the result. To control the time to wait for asynchronous request to complete on a per-request basis, useexchange(Duration)
.- Returns:
- a request builder for specifying the target URI
-
put
Prepare an HTTP PUT request.The returned builder can be wrapped in
assertThat
to enable assertions on the result. For multi-statements assertions, useexchange()
to assign the result. To control the time to wait for asynchronous request to complete on a per-request basis, useexchange(Duration)
.- Returns:
- a request builder for specifying the target URI
-
patch
Prepare an HTTP PATCH request.The returned builder can be wrapped in
assertThat
to enable assertions on the result. For multi-statements assertions, useexchange()
to assign the result. To control the time to wait for asynchronous request to complete on a per-request basis, useexchange(Duration)
.- Returns:
- a request builder for specifying the target URI
-
delete
Prepare an HTTP DELETE request.The returned builder can be wrapped in
assertThat
to enable assertions on the result. For multi-statements assertions, useexchange()
to assign the result. To control the time to wait for asynchronous request to complete on a per-request basis, useexchange(Duration)
.- Returns:
- a request builder for specifying the target URI
-
options
Prepare an HTTP OPTIONS request.The returned builder can be wrapped in
assertThat
to enable assertions on the result. For multi-statements assertions, useexchange()
to assign the result. To control the time to wait for asynchronous request to complete on a per-request basis, useexchange(Duration)
.- Returns:
- a request builder for specifying the target URI
-
method
Prepare a request for the specifiedHttpMethod
.The returned builder can be wrapped in
assertThat
to enable assertions on the result. For multi-statements assertions, useexchange()
to assign the result. To control the time to wait for asynchronous request to complete on a per-request basis, useexchange(Duration)
.- Returns:
- a request builder for specifying the target URI
-
perform
Perform a request using the givenRequestBuilder
and return aresult
that can be used with standardAssertJ
assertions.Use only this method if you need to provide a custom
RequestBuilder
. For regular cases, users should initiate the configuration of the request using one of the methods available on this instance, e.g.get()
for HTTP GET.Contrary to
MockMvc.perform(RequestBuilder)
, this does not throw an exception if the request fails with an unresolved exception. Rather, the result provides the exception, if any. Assuming that aPOST
request against/boom
throws anIllegalStateException
, the following asserts that the invocation has indeed failed with the expected error message:assertThat(mvc.post().uri("/boom"))) .failure().isInstanceOf(IllegalStateException.class) .hasMessage("Expected");
- Parameters:
requestBuilder
- used to prepare the request to execute- Returns:
- an
MvcTestResult
to be wrapped inassertThat
- See Also:
-