Deprecate TestRestTemplate

Closes gh-46632

documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/spring-boot-applications.adoc

@@ -340,7 +340,7 @@ include-code::MyJsonAssertJTests[tag=*]
 == Auto-configured Spring MVC Tests
 
 To test whether Spring MVC controllers are working as expected, use the javadoc:org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest[format=annotation] annotation from the `spring-boot-webmvc-test` module.
-javadoc:org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest[format=annotation] auto-configures the Spring MVC infrastructure and limits scanned beans to javadoc:org.springframework.stereotype.Controller[format=annotation],  javadoc:org.springframework.web.bind.annotation.ControllerAdvice[format=annotation], javadoc:org.springframework.boot.jackson.JacksonComponent[format=annotation], javadoc:org.springframework.boot.jackson2.JsonComponent[format=annotation] (deprecated), javadoc:org.springframework.core.convert.converter.Converter[], javadoc:org.springframework.core.convert.converter.GenericConverter[], javadoc:jakarta.servlet.Filter[], javadoc:org.springframework.web.servlet.HandlerInterceptor[], javadoc:org.springframework.web.servlet.config.annotation.WebMvcConfigurer[], javadoc:org.springframework.boot.webmvc.autoconfigure.WebMvcRegistrations[], and javadoc:org.springframework.web.method.support.HandlerMethodArgumentResolver[].
+javadoc:org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest[format=annotation] auto-configures the Spring MVC infrastructure and limits scanned beans to javadoc:org.springframework.stereotype.Controller[format=annotation], javadoc:org.springframework.web.bind.annotation.ControllerAdvice[format=annotation], javadoc:org.springframework.boot.jackson.JacksonComponent[format=annotation], javadoc:org.springframework.boot.jackson2.JsonComponent[format=annotation] (deprecated), javadoc:org.springframework.core.convert.converter.Converter[], javadoc:org.springframework.core.convert.converter.GenericConverter[], javadoc:jakarta.servlet.Filter[], javadoc:org.springframework.web.servlet.HandlerInterceptor[], javadoc:org.springframework.web.servlet.config.annotation.WebMvcConfigurer[], javadoc:org.springframework.boot.webmvc.autoconfigure.WebMvcRegistrations[], and javadoc:org.springframework.web.method.support.HandlerMethodArgumentResolver[].
 Regular javadoc:org.springframework.stereotype.Component[format=annotation] and javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation] beans are not scanned when the javadoc:org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest[format=annotation] annotation is used.
 javadoc:org.springframework.boot.context.properties.EnableConfigurationProperties[format=annotation] can be used to include javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation] beans.
 
@@ -353,14 +353,17 @@ Often, javadoc:org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest[for
 javadoc:org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest[format=annotation] also auto-configures javadoc:org.springframework.test.web.servlet.MockMvc[].
 Mock MVC offers a powerful way to quickly test MVC controllers without needing to start a full HTTP server.
 If AssertJ is available, the AssertJ support provided by javadoc:org.springframework.test.web.servlet.assertj.MockMvcTester[] is auto-configured as well.
+
+include-code::MyControllerTests[]
+
 If you'd like to use javadoc:org.springframework.test.web.servlet.client.RestTestClient[] in your tests, annotate your test class with javadoc:org.springframework.boot.resttestclient.autoconfigure.AutoConfigureRestTestClient[format=annotation].
 A `RestTestClient` that uses the Mock MVC infrastructure will then be auto-configured.
 
+include-code::MockTransportTests[]
+
 TIP: You can also auto-configure javadoc:org.springframework.test.web.servlet.MockMvc[] and javadoc:org.springframework.test.web.servlet.assertj.MockMvcTester[] in a non-`@WebMvcTest` (such as javadoc:org.springframework.boot.test.context.SpringBootTest[format=annotation]) by annotating it with javadoc:org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc[format=annotation].
 The following example uses javadoc:org.springframework.test.web.servlet.assertj.MockMvcTester[]:
 
-include-code::MyControllerTests[]
-
 TIP: If you need to configure elements of the auto-configuration (for example, when servlet filters should be applied) you can use attributes in the javadoc:org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc[format=annotation] annotation.
 
 If you use HtmlUnit and Selenium, auto-configuration also provides an HtmlUnit javadoc:org.springframework.web.reactive.function.client.WebClient[] bean and/or a Selenium javadoc:org.openqa.selenium.WebDriver[] bean.

documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/test-utilities.adoc

@@ -42,6 +42,9 @@ include-code::MyOutputCaptureTests[]
 [[testing.utilities.test-rest-template]]
 == TestRestTemplate
 
+WARNING: As of Spring Boot 4.2, `TestRestTemplate` is formally deprecated along `RestTemplate` itself in Spring Framework 7.1.
+Test suites should xref:reference:testing/spring-boot-applications.adoc#testing.spring-boot-applications.spring-mvc-tests[migrate to `RestTestClient`], which can bind itself against a live server or a mock transport.
+
 javadoc:org.springframework.boot.resttestclient.TestRestTemplate[] is a convenience alternative to Spring's javadoc:org.springframework.web.client.RestTemplate[] that is useful in integration tests.
 It's provided by the `spring-boot-resttestclient` module.
 A dependency on `spring-boot-restclient` is also required.

documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/testing/springbootapplications/springmvctests/MockTransportTests.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2012-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.boot.docs.testing.springbootapplications.springmvctests;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.restclient.test.autoconfigure.AutoConfigureRestClient;
+import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
+import org.springframework.http.MediaType;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.client.RestTestClient;
+
+import static org.mockito.BDDMockito.given;
+
+@WebMvcTest(UserVehicleController.class)
+@AutoConfigureRestClient
+class MockTransportTests {
+
+	@Autowired
+	private RestTestClient restClient;
+
+	@MockitoBean
+	private UserVehicleService userVehicleService;
+
+	@Test
+	void testExample() {
+		// @formatter:off
+		given(this.userVehicleService.getVehicleDetails("sboot"))
+			.willReturn(new VehicleDetails("Honda", "Civic"));
+		this.restClient.get().uri("/sboot/vehicle").accept(MediaType.TEXT_PLAIN)
+				.exchangeSuccessfully()
+				.expectBody(String.class)
+				.isEqualTo("Honda Civic");
+		// @formatter:on
+	}
+
+}

documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/testing/springbootapplications/withrunningserver/MyRandomPortTestRestTemplateTests.java

@@ -28,6 +28,7 @@ import static org.assertj.core.api.Assertions.assertThat;
 
 @SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
 @AutoConfigureTestRestTemplate
+@SuppressWarnings("removal")
 class MyRandomPortTestRestTemplateTests {
 
 	@Test

documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/testing/utilities/testresttemplate/MyTests.java

@@ -24,6 +24,7 @@ import org.springframework.http.ResponseEntity;
 
 import static org.assertj.core.api.Assertions.assertThat;
 
+@SuppressWarnings("removal")
 class MyTests {
 
 	private final TestRestTemplate template = new TestRestTemplate();

documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/testing/springbootapplications/springmvctests/MockTransportTests.kt

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2012-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.boot.docs.testing.springbootapplications.springmvctests
+
+import org.junit.jupiter.api.Test
+import org.mockito.BDDMockito.given
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.boot.resttestclient.autoconfigure.AutoConfigureRestTestClient
+import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest
+import org.springframework.http.MediaType
+import org.springframework.test.context.bean.override.mockito.MockitoBean
+import org.springframework.test.web.servlet.client.RestTestClient
+import org.springframework.test.web.servlet.client.expectBody
+
+@WebMvcTest(UserVehicleController::class)
+@AutoConfigureRestTestClient
+class MockTransportTests(@Autowired val restClient: RestTestClient) {
+
+	@MockitoBean
+	lateinit var userVehicleService: UserVehicleService
+
+	@Test
+	fun testExample() {
+		given(userVehicleService.getVehicleDetails("sboot"))
+				.willReturn(VehicleDetails("Honda", "Civic"))
+		restClient.get().uri("/sboot/vehicle").accept(MediaType.TEXT_PLAIN)
+			.exchangeSuccessfully().expectBody<String>().isEqualTo("Honda Civic")
+	}
+
+}
+

documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/testing/springbootapplications/withrunningserver/MyRandomPortTestRestTemplateTests.kt

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+@file:Suppress("DEPRECATION", "REMOVAL")
+
 package org.springframework.boot.docs.testing.springbootapplications.withrunningserver
 
 import org.assertj.core.api.Assertions.assertThat

documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/testing/utilities/testresttemplate/MySpringBootTests.kt

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-@file:Suppress("DEPRECATION")
+@file:Suppress("DEPRECATION", "REMOVAL")
 
 package org.springframework.boot.docs.testing.utilities.testresttemplate
 

documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/testing/utilities/testresttemplate/MyTests.kt

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+@file:Suppress("DEPRECATION", "REMOVAL")
+
 package org.springframework.boot.docs.testing.utilities.testresttemplate
 
 import org.assertj.core.api.Assertions.assertThat