Document how to discard response body with WebTestClient

This commit better documents the ways to discard the response body with
`WebTestClient`.

Closes gh-35953

Author: bclozel

framework-docs/modules/ROOT/pages/testing/resttestclient.adoc

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2025-present 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.docs.testing.resttestclient.assertj;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.http.MediaType;
+import org.springframework.test.web.servlet.client.ExchangeResult;
+import org.springframework.test.web.servlet.client.RestTestClient;
+import org.springframework.test.web.servlet.client.assertj.RestTestClientResponse;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+public class AssertJTests {
+
+	RestTestClient client;
+
+	@Test
+	void withSpec() {
+		// tag::withSpec[]
+		RestTestClient.ResponseSpec spec = client.get().uri("/persons").exchange();
+
+		RestTestClientResponse response = RestTestClientResponse.from(spec);
+		assertThat(response).hasStatusOk();
+		assertThat(response).hasContentTypeCompatibleWith(MediaType.TEXT_PLAIN);
+		// end::withSpec[]
+	}
+
+	@Test
+	void withResult() {
+		// tag::withResult[]
+		ExchangeResult result = client.get().uri("/persons").exchange().returnResult();
+
+		RestTestClientResponse response = RestTestClientResponse.from(result);
+		assertThat(response).hasStatusOk();
+		assertThat(response).hasContentTypeCompatibleWith(MediaType.TEXT_PLAIN);
+		// end::withResult[]
+	}
+
+}

framework-docs/src/main/java/org/springframework/docs/testing/resttestclient/assertj/AssertJTests.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2025-present 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.docs.testing.resttestclient.contextconfig;
+
+import org.junit.jupiter.api.BeforeEach;
+
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+import org.springframework.test.web.servlet.client.RestTestClient;
+import org.springframework.web.context.WebApplicationContext;
+
+
+@SpringJUnitConfig(WebConfig.class) // Specify the configuration to load
+public class RestClientContextTests {
+
+	RestTestClient client;
+
+	@BeforeEach
+	void setUp(WebApplicationContext context) {  // Inject the configuration
+		// Create the `RestTestClient`
+		client = RestTestClient.bindToApplicationContext(context).build();
+	}
+
+}

framework-docs/src/main/java/org/springframework/docs/testing/resttestclient/contextconfig/RestClientContextTests.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2025-present 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.docs.testing.resttestclient.contextconfig;
+
+public class WebConfig {
+}

framework-docs/src/main/java/org/springframework/docs/testing/resttestclient/contextconfig/WebConfig.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2025-present 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.docs.testing.resttestclient.json;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.test.web.servlet.client.RestTestClient;
+
+public class JsonTests {
+
+	RestTestClient client;
+
+	@Test
+	void jsonBody() {
+		// tag::jsonBody[]
+		client.get().uri("/persons/1")
+				.exchange()
+				.expectStatus().isOk()
+				.expectBody()
+				.json("{\"name\":\"Jane\"}");
+		// end::jsonBody[]
+	}
+
+	@Test
+	void jsonPath() {
+		// tag::jsonPath[]
+		client.get().uri("/persons")
+				.exchange()
+				.expectStatus().isOk()
+				.expectBody()
+				.jsonPath("$[0].name").isEqualTo("Jane")
+				.jsonPath("$[1].name").isEqualTo("Jason");
+		// end::jsonPath[]
+	}
+
+}

framework-docs/src/main/java/org/springframework/docs/testing/resttestclient/json/JsonTests.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2025-present 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.docs.testing.resttestclient.nocontent;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.test.web.servlet.client.RestTestClient;
+
+public class NoContentTests {
+
+
+	RestTestClient client;
+
+	@Test
+	void emptyBody() {
+		Person person = new Person("Jane");
+		// tag::emptyBody[]
+		client.post().uri("/persons")
+				.body(person)
+				.exchange()
+				.expectStatus().isCreated()
+				.expectBody().isEmpty();
+		// end::emptyBody[]
+	}
+
+	@Test
+	void ignoreBody() {
+		Person person = new Person("Jane");
+		// tag::ignoreBody[]
+		client.post().uri("/persons")
+				.body(person)
+				.exchange()
+				.expectStatus().isCreated()
+				.expectBody(Void.class);
+		// end::ignoreBody[]
+	}
+
+	record Person(String name) {
+
+	}
+
+}

framework-docs/src/main/java/org/springframework/docs/testing/resttestclient/nocontent/NoContentTests.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2025-present 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.docs.testing.resttestclient.workflow;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.MediaType;
+import org.springframework.test.web.servlet.client.EntityExchangeResult;
+import org.springframework.test.web.servlet.client.RestTestClient;
+
+public class RestClientWorkflowTests {
+
+	RestTestClient client;
+
+	@Test
+	void workflowTest() {
+		// tag::test[]
+		client.get().uri("/persons/1")
+				.accept(MediaType.APPLICATION_JSON)
+				.exchange()
+				.expectStatus().isOk()
+				.expectHeader().contentType(MediaType.APPLICATION_JSON)
+				.expectBody();
+		// end::test[]
+	}
+
+	@Test
+	void softAssertions() {
+		// tag::soft-assertions[]
+		client.get().uri("/persons/1")
+				.accept(MediaType.APPLICATION_JSON)
+				.exchange()
+				.expectAll(
+						spec -> spec.expectStatus().isOk(),
+						spec -> spec.expectHeader().contentType(MediaType.APPLICATION_JSON)
+				);
+		// end::soft-assertions[]
+	}
+
+	@Test
+	void consumeWith() {
+		// tag::consume[]
+		client.get().uri("/persons/1")
+				.exchange()
+				.expectStatus().isOk()
+				.expectBody(Person.class)
+				.consumeWith(result -> {
+					// custom assertions (for example, AssertJ)...
+				});
+		// end::consume[]
+	}
+
+	@Test
+	void returnResult() {
+		// tag::result[]
+		EntityExchangeResult<Person> result = client.get().uri("/persons/1")
+				.exchange()
+				.expectStatus().isOk()
+				.expectBody(Person.class)
+				.returnResult();
+
+		Person person = result.getResponseBody();
+		HttpHeaders requestHeaders = result.getRequestHeaders();
+		// end::result[]
+	}
+
+	record Person(String name) {
+
+	}
+}

framework-docs/src/main/java/org/springframework/docs/testing/resttestclient/workflow/RestClientWorkflowTests.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2025-present 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.docs.testing.resttestclient.assertj
+
+import org.assertj.core.api.Assertions
+import org.junit.jupiter.api.Test
+import org.springframework.http.MediaType
+import org.springframework.test.web.servlet.client.RestTestClient
+import org.springframework.test.web.servlet.client.assertj.RestTestClientResponse
+
+class AssertJTests {
+
+
+	lateinit var client: RestTestClient
+
+	@Test
+	fun withSpec() {
+		// tag::withSpec[]
+		val spec = client.get().uri("/persons").exchange()
+
+		val response = RestTestClientResponse.from(spec)
+		Assertions.assertThat(response).hasStatusOk()
+		Assertions.assertThat(response).hasContentTypeCompatibleWith(MediaType.TEXT_PLAIN)
+		// end::withSpec[]
+	}
+
+	@Test
+	fun withResult() {
+		// tag::withResult[]
+		val result = client.get().uri("/persons").exchange().returnResult()
+
+		val response = RestTestClientResponse.from(result)
+		Assertions.assertThat(response).hasStatusOk()
+		Assertions.assertThat(response).hasContentTypeCompatibleWith(MediaType.TEXT_PLAIN)
+		// end::withResult[]
+	}
+
+}

framework-docs/src/main/kotlin/org/springframework/docs/testing/resttestclient/assertj/AssertJTests.kt

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2025-present 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.docs.testing.resttestclient.contextconfig
+
+import org.junit.jupiter.api.BeforeEach
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig
+import org.springframework.test.web.servlet.client.RestTestClient
+import org.springframework.web.context.WebApplicationContext
+
+@SpringJUnitConfig(WebConfig::class) // Specify the configuration to load
+class RestClientContextTests {
+
+	lateinit var client: RestTestClient
+
+	@BeforeEach
+	fun setUp(context: WebApplicationContext) {  // Inject the configuration
+		// Create the `RestTestClient`
+		client = RestTestClient.bindToApplicationContext(context).build()
+	}
+}