Add support for fluent preparation of the request in MockMvcTester

See gh-32913

Author: snicoll

spring-test/src/main/java/org/springframework/test/web/servlet/assertj/MockMvcTester.java

@@ -23,13 +23,18 @@
 import java.util.function.Function;
 import java.util.stream.StreamSupport;
 
+import org.assertj.core.api.AssertProvider;
+
+import org.springframework.http.HttpMethod;
 import org.springframework.http.MediaType;
 import org.springframework.http.converter.GenericHttpMessageConverter;
 import org.springframework.http.converter.HttpMessageConverter;
 import org.springframework.lang.Nullable;
+import org.springframework.mock.web.MockHttpServletRequest;
 import org.springframework.test.web.servlet.MockMvc;
 import org.springframework.test.web.servlet.MvcResult;
 import org.springframework.test.web.servlet.RequestBuilder;
+import org.springframework.test.web.servlet.request.AbstractMockHttpServletRequestBuilder;
 import org.springframework.test.web.servlet.request.MockMvcRequestBuilders;
 import org.springframework.test.web.servlet.setup.DefaultMockMvcBuilder;
 import org.springframework.test.web.servlet.setup.MockMvcBuilders;
@@ -58,11 +63,25 @@
  * MockMvcTester mvc = MockMvcTester.of(new PersonController());
  * </code></pre>
  *
- * <p>Once a tester instance is available, you can perform requests in a similar
- * fashion as with {@link MockMvc}, and wrapping the result in
- * {@code assertThat()} provides access to assertions. For instance:
+ * <p>Simple, single-statement assertions can be done wrapping the request
+ * builder in {@code assertThat()} provides access to assertions. For instance:
  * <pre><code class="java">
  * // perform a GET on /hi and assert the response body is equal to Hello
+ * assertThat(mvc.get().uri("/hi")).hasStatusOk().hasBodyTextEqualTo("Hello");
+ * </code></pre>
+ *
+ *<p>For more complex scenarios the {@linkplain MvcTestResult result} of the
+ * exchange can be assigned in a variable to run multiple assertions:
+ * <pre><code class="java">
+ * // 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();
+ * </code></pre>
+ *
+ * <p>You can also perform requests using the static builders approach that
+ * {@link MockMvc} uses. For instance:<pre><code class="java">
+ * // perform a GET on /hi and assert the response body is equal to Hello
  * assertThat(mvc.perform(get("/hi")))
  *         .hasStatusOk().hasBodyTextEqualTo("Hello");
  * </code></pre>
@@ -74,12 +93,11 @@
  * which allows you to assert that a request failed unexpectedly:
  * <pre><code class="java">
  * // perform a GET on /boom and assert the message for the the unresolved exception
- * assertThat(mvc.perform(get("/boom")))
- *         .hasUnresolvedException())
+ * assertThat(mvc.get().uri("/boom")).hasUnresolvedException())
  *         .withMessage("Test exception");
  * </code></pre>
  *
- * <p>{@link MockMvcTester} can be configured with a list of
+ * <p>{@code MockMvcTester} can be configured with a list of
  * {@linkplain HttpMessageConverter message converters} to allow the response
  * body to be deserialized, rather than asserting on the raw values.
  *
@@ -104,18 +122,17 @@ private MockMvcTester(MockMvc mockMvc, @Nullable GenericHttpMessageConverter<Obj
 	}
 
 	/**
-	 * Create a {@link MockMvcTester} instance that delegates to the given
-	 * {@link MockMvc} instance.
+	 * Create an instance that delegates to the given {@link MockMvc} instance.
 	 * @param mockMvc the MockMvc instance to delegate calls to
 	 */
 	public static MockMvcTester create(MockMvc mockMvc) {
 		return new MockMvcTester(mockMvc, null);
 	}
 
 	/**
-	 * Create an {@link MockMvcTester} instance using the given, fully
-	 * initialized (i.e., <em>refreshed</em>) {@link WebApplicationContext}. The
-	 * given {@code customizations} are applied to the {@link DefaultMockMvcBuilder}
+	 * Create an instance using the given, fully initialized (i.e.,
+	 * <em>refreshed</em>) {@link WebApplicationContext}. The given
+	 * {@code customizations} are applied to the {@link DefaultMockMvcBuilder}
 	 * that ultimately creates the underlying {@link MockMvc} instance.
 	 * <p>If no further customization of the underlying {@link MockMvc} instance
 	 * is required, use {@link #from(WebApplicationContext)}.
@@ -134,8 +151,8 @@ public static MockMvcTester from(WebApplicationContext applicationContext,
 	}
 
 	/**
-	 * Shortcut to create an {@link MockMvcTester} instance using the given,
-	 * fully initialized (i.e., <em>refreshed</em>) {@link WebApplicationContext}.
+	 * Shortcut to create an instance using the given fully initialized (i.e.,
+	 * <em>refreshed</em>) {@link WebApplicationContext}.
 	 * <p>Consider using {@link #from(WebApplicationContext, Function)} if
 	 * further customization of the underlying {@link MockMvc} instance is
 	 * required.
@@ -148,9 +165,8 @@ public static MockMvcTester from(WebApplicationContext applicationContext) {
 	}
 
 	/**
-	 * Create an {@link MockMvcTester} instance by registering one or more
-	 * {@code @Controller} instances and configuring Spring MVC infrastructure
-	 * programmatically.
+	 * Create an instance by registering one or more {@code @Controller} instances
+	 * and configuring Spring MVC infrastructure programmatically.
 	 * <p>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.
@@ -170,8 +186,8 @@ public static MockMvcTester of(Collection<?> controllers,
 	}
 
 	/**
-	 * Shortcut to create an {@link MockMvcTester} instance by registering one
-	 * or more {@code @Controller} instances.
+	 * Shortcut to create an instance by registering one or more {@code @Controller}
+	 * instances.
 	 * <p>The minimum infrastructure required by the
 	 * {@link org.springframework.web.servlet.DispatcherServlet DispatcherServlet}
 	 * to serve requests with annotated controllers is created. Consider using
@@ -187,8 +203,8 @@ public static MockMvcTester of(Object... controllers) {
 	}
 
 	/**
-	 * Return a new {@link MockMvcTester} instance using the specified
-	 * {@linkplain HttpMessageConverter message converters}.
+	 * Return a new instance using the specified {@linkplain HttpMessageConverter
+	 * message converters}.
 	 * <p>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.
@@ -200,8 +216,105 @@ public MockMvcTester withHttpMessageConverters(Iterable<HttpMessageConverter<?>>
 	}
 
 	/**
-	 * Perform a request and return a {@link MvcTestResult result} that can be
-	 * used with standard {@link org.assertj.core.api.Assertions AssertJ} assertions.
+	 * Prepare an HTTP GET request.
+	 * <p>The returned builder can be wrapped in {@code assertThat} to enable
+	 * assertions on the result. For multi-statements assertions, use
+	 * {@linkplain MockMvcRequestBuilder#exchange() exchange} to assign the
+	 * result.
+	 * @return a request builder for specifying the target URI
+	 */
+	public MockMvcRequestBuilder get() {
+		return method(HttpMethod.GET);
+	}
+
+	/**
+	 * Prepare an HTTP HEAD request.
+	 * <p>The returned builder can be wrapped in {@code assertThat} to enable
+	 * assertions on the result. For multi-statements assertions, use
+	 * {@linkplain MockMvcRequestBuilder#exchange() exchange} to assign the
+	 * result.
+	 * @return a request builder for specifying the target URI
+	 */
+	public MockMvcRequestBuilder head() {
+		return method(HttpMethod.HEAD);
+	}
+
+	/**
+	 * Prepare an HTTP POST request.
+	 * <p>The returned builder can be wrapped in {@code assertThat} to enable
+	 * assertions on the result. For multi-statements assertions, use
+	 * {@linkplain MockMvcRequestBuilder#exchange() exchange} to assign the
+	 * result.
+	 * @return a request builder for specifying the target URI
+	 */
+	public MockMvcRequestBuilder post() {
+		return method(HttpMethod.POST);
+	}
+
+	/**
+	 * Prepare an HTTP PUT request.
+	 * <p>The returned builder can be wrapped in {@code assertThat} to enable
+	 * assertions on the result. For multi-statements assertions, use
+	 * {@linkplain MockMvcRequestBuilder#exchange() exchange} to assign the
+	 * result.
+	 * @return a request builder for specifying the target URI
+	 */
+	public MockMvcRequestBuilder put() {
+		return method(HttpMethod.PUT);
+	}
+
+	/**
+	 * Prepare an HTTP PATCH request.
+	 * <p>The returned builder can be wrapped in {@code assertThat} to enable
+	 * assertions on the result. For multi-statements assertions, use
+	 * {@linkplain MockMvcRequestBuilder#exchange() exchange} to assign the
+	 * result.
+	 * @return a request builder for specifying the target URI
+	 */
+	public MockMvcRequestBuilder patch() {
+		return method(HttpMethod.PATCH);
+	}
+
+	/**
+	 * Prepare an HTTP DELETE request.
+	 * <p>The returned builder can be wrapped in {@code assertThat} to enable
+	 * assertions on the result. For multi-statements assertions, use
+	 * {@linkplain MockMvcRequestBuilder#exchange() exchange} to assign the
+	 * result.
+	 * @return a request builder for specifying the target URI
+	 */
+	public MockMvcRequestBuilder delete() {
+		return method(HttpMethod.DELETE);
+	}
+
+	/**
+	 * Prepare an HTTP OPTIONS request.
+	 * <p>The returned builder can be wrapped in {@code assertThat} to enable
+	 * assertions on the result. For multi-statements assertions, use
+	 * {@linkplain MockMvcRequestBuilder#exchange() exchange} to assign the
+	 * result.
+	 * @return a request builder for specifying the target URI
+	 */
+	public MockMvcRequestBuilder options() {
+		return method(HttpMethod.OPTIONS);
+	}
+
+	/**
+	 * Prepare a request for the specified {@code HttpMethod}.
+	 * <p>The returned builder can be wrapped in {@code assertThat} to enable
+	 * assertions on the result. For multi-statements assertions, use
+	 * {@linkplain MockMvcRequestBuilder#exchange() exchange} to assign the
+	 * result.
+	 * @return a request builder for specifying the target URI
+	 */
+	public MockMvcRequestBuilder method(HttpMethod method) {
+		return new MockMvcRequestBuilder(method);
+	}
+
+	/**
+	 * Perform a request using {@link MockMvcRequestBuilders} and return a
+	 * {@link MvcTestResult result} that can be used with standard
+	 * {@link org.assertj.core.api.Assertions AssertJ} assertions.
 	 * <p>Use static methods of {@link MockMvcRequestBuilders} to prepare the
 	 * request, wrapping the invocation in {@code assertThat}. The following
 	 * asserts that a {@linkplain MockMvcRequestBuilders#get(URI) GET} request
@@ -226,6 +339,8 @@ public MockMvcTester withHttpMessageConverters(Iterable<HttpMessageConverter<?>>
 	 * {@link org.springframework.test.web.servlet.request.MockMvcRequestBuilders}
 	 * @return an {@link MvcTestResult} to be wrapped in {@code assertThat}
 	 * @see MockMvc#perform(RequestBuilder)
+	 * @see #get()
+	 * @see #post()
 	 */
 	public MvcTestResult perform(RequestBuilder requestBuilder) {
 		Object result = getMvcResultOrFailure(requestBuilder);
@@ -259,4 +374,25 @@ private GenericHttpMessageConverter<Object> findJsonMessageConverter(
 				.findFirst().orElse(null);
 	}
 
+
+	/**
+	 * A builder for {@link MockHttpServletRequest} that supports AssertJ.
+	 */
+	public final class MockMvcRequestBuilder extends AbstractMockHttpServletRequestBuilder<MockMvcRequestBuilder>
+			implements AssertProvider<MvcTestResultAssert> {
+
+		private MockMvcRequestBuilder(HttpMethod httpMethod) {
+			super(httpMethod);
+		}
+
+		public MvcTestResult exchange() {
+			return perform(this);
+		}
+
+		@Override
+		public MvcTestResultAssert assertThat() {
+			return new MvcTestResultAssert(exchange(), MockMvcTester.this.jsonMessageConverter);
+		}
+	}
+
 }

spring-test/src/test/java/org/springframework/test/web/servlet/assertj/MockMvcTesterCompatibilityIntegrationTests.java

@@ -0,0 +1,94 @@
+/*
+ * Copyright 2002-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.test.web.servlet.assertj;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Import;
+import org.springframework.http.MediaType;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+import org.springframework.test.context.web.WebAppConfiguration;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.context.WebApplicationContext;
+import org.springframework.web.servlet.config.annotation.EnableWebMvc;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * Integration tests for {@link MockMvcTester} that use the methods that
+ * integrate with {@link MockMvc} way of building the requests and
+ * asserting the responses.
+ *
+ * @author Stephane Nicoll
+ */
+@SpringJUnitConfig
+@WebAppConfiguration
+class MockMvcTesterCompatibilityIntegrationTests {
+
+	private final MockMvcTester mvc;
+
+	MockMvcTesterCompatibilityIntegrationTests(@Autowired WebApplicationContext wac) {
+		this.mvc = MockMvcTester.from(wac);
+	}
+
+	@Test
+	void performGet() {
+		assertThat(this.mvc.perform(get("/greet"))).hasStatusOk();
+	}
+
+	@Test
+	void performGetWithInvalidMediaTypeAssertion() {
+		MvcTestResult result = this.mvc.perform(get("/greet"));
+		assertThatExceptionOfType(AssertionError.class)
+				.isThrownBy(() -> assertThat(result).hasContentTypeCompatibleWith(MediaType.APPLICATION_JSON))
+				.withMessageContaining("is compatible with 'application/json'");
+	}
+
+	@Test
+	void assertHttpStatusCode() {
+		assertThat(this.mvc.get().uri("/greet")).matches(status().isOk());
+	}
+
+
+	@Configuration
+	@EnableWebMvc
+	@Import(TestController.class)
+	static class WebConfiguration {
+	}
+
+	@RestController
+	static class TestController {
+
+		@GetMapping(path = "/greet", produces = "text/plain")
+		String greet() {
+			return "hello";
+		}
+
+		@GetMapping(path = "/message", produces = MediaType.APPLICATION_JSON_VALUE)
+		String message() {
+			return "{\"message\": \"hello\"}";
+		}
+	}
+
+}