Deprecate Hamcrest use in WebTestClient

rstoyanchev · rstoyanchev · commit 0319fe92114d · 2025-10-29T09:50:36.000Z
Closes gh-35703
diff --git a/spring-test/src/main/java/org/springframework/test/web/reactive/server/CookieAssertions.java b/spring-test/src/main/java/org/springframework/test/web/reactive/server/CookieAssertions.java
@@ -16,6 +16,8 @@
 
 package org.springframework.test.web.reactive.server;
 
+import java.util.function.Consumer;
+
 import org.hamcrest.Matcher;
 
 import org.springframework.http.ResponseCookie;
@@ -53,7 +55,9 @@ protected void assertWithDiagnostics(Runnable assertion) {
 	/**
 	 * Assert the value of the response cookie with the given name with a Hamcrest
 	 * {@link Matcher}.
+	 * @deprecated in favor of {@link Consumer}-based variants
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public WebTestClient.ResponseSpec value(String name, Matcher<? super String> matcher) {
 		String value = getCookie(name).getValue();
 		assertWithDiagnostics(() -> {
@@ -66,7 +70,9 @@ public WebTestClient.ResponseSpec value(String name, Matcher<? super String> mat
 
 	/**
 	 * Assert a cookie's "Max-Age" attribute with a Hamcrest {@link Matcher}.
+	 * @deprecated in favor of {@link Consumer}-based variants
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public WebTestClient.ResponseSpec maxAge(String name, Matcher<? super Long> matcher) {
 		long maxAge = getCookie(name).getMaxAge().getSeconds();
 		assertWithDiagnostics(() -> {
@@ -78,7 +84,9 @@ public WebTestClient.ResponseSpec maxAge(String name, Matcher<? super Long> matc
 
 	/**
 	 * Assert a cookie's "Path" attribute with a Hamcrest {@link Matcher}.
+	 * @deprecated in favor of {@link Consumer}-based variants
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public WebTestClient.ResponseSpec path(String name, Matcher<? super String> matcher) {
 		String path = getCookie(name).getPath();
 		assertWithDiagnostics(() -> {
@@ -90,7 +98,9 @@ public WebTestClient.ResponseSpec path(String name, Matcher<? super String> matc
 
 	/**
 	 * Assert a cookie's "Domain" attribute with a Hamcrest {@link Matcher}.
+	 * @deprecated in favor of {@link Consumer}-based variants
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public WebTestClient.ResponseSpec domain(String name, Matcher<? super String> matcher) {
 		String domain = getCookie(name).getDomain();
 		assertWithDiagnostics(() -> {
diff --git a/spring-test/src/main/java/org/springframework/test/web/reactive/server/DefaultWebTestClient.java b/spring-test/src/main/java/org/springframework/test/web/reactive/server/DefaultWebTestClient.java
@@ -34,6 +34,7 @@
 import com.jayway.jsonpath.spi.mapper.MappingProvider;
 import org.hamcrest.Matcher;
 import org.hamcrest.MatcherAssert;
+import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.Nullable;
 import org.reactivestreams.Publisher;
 import reactor.core.publisher.Flux;
@@ -584,14 +585,15 @@ public <T extends S> T isEqualTo(@Nullable B expected) {
 			return self();
 		}
 
+		@SuppressWarnings("removal")
 		@Override
 		public <T extends S> T value(Matcher<? super @Nullable B> matcher) {
 			this.result.assertWithDiagnostics(() -> MatcherAssert.assertThat(this.result.getResponseBody(), matcher));
 			return self();
 		}
 
 		@Override
-		@SuppressWarnings("NullAway") // https://github.com/uber/NullAway/issues/1129
+		@SuppressWarnings({"NullAway", "removal"}) // https://github.com/uber/NullAway/issues/1129
 		public <T extends S, R> T value(Function<@Nullable B, @Nullable R> bodyMapper, Matcher<? super @Nullable R> matcher) {
 			this.result.assertWithDiagnostics(() -> {
 				B body = this.result.getResponseBody();
@@ -606,6 +608,15 @@ public <T extends S> T value(Consumer<@Nullable B> consumer) {
 			return self();
 		}
 
+		@Override
+		public <T extends S, R> T value(@NonNull Function<@Nullable B, @Nullable R> bodyMapper, Consumer<? super R> consumer) {
+			this.result.assertWithDiagnostics(() -> {
+				B body = this.result.getResponseBody();
+				consumer.accept(bodyMapper.apply(body));
+			});
+			return self();
+		}
+
 		@Override
 		public <T extends S> T consumeWith(Consumer<EntityExchangeResult<B>> consumer) {
 			this.result.assertWithDiagnostics(() -> consumer.accept(this.result));
diff --git a/spring-test/src/main/java/org/springframework/test/web/reactive/server/HeaderAssertions.java b/spring-test/src/main/java/org/springframework/test/web/reactive/server/HeaderAssertions.java
@@ -17,6 +17,7 @@
 package org.springframework.test.web.reactive.server;
 
 import java.util.List;
+import java.util.function.Consumer;
 
 import org.hamcrest.Matcher;
 
@@ -59,7 +60,9 @@ protected void assertWithDiagnostics(Runnable assertion) {
 	 * Assert the first value of the response header with a Hamcrest {@link Matcher}.
 	 * @param name the header name
 	 * @param matcher the matcher to use
+	 * @deprecated in favor of {@link Consumer}-based variants
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public WebTestClient.ResponseSpec value(String name, Matcher<? super String> matcher) {
 		String value = getResponseHeaders().getFirst(name);
 		assertWithDiagnostics(() -> {
@@ -73,7 +76,9 @@ public WebTestClient.ResponseSpec value(String name, Matcher<? super String> mat
 	 * Assert all values of the response header with a Hamcrest {@link Matcher}.
 	 * @param name the header name
 	 * @param matcher the matcher to use
+	 * @deprecated in favor of {@link Consumer}-based variants
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public WebTestClient.ResponseSpec values(String name, Matcher<? super Iterable<String>> matcher) {
 		List<String> values = getResponseHeaders().get(name);
 		assertWithDiagnostics(() -> {
@@ -83,5 +88,4 @@ public WebTestClient.ResponseSpec values(String name, Matcher<? super Iterable<S
 		return getResponseSpec();
 	}
 
-
 }
diff --git a/spring-test/src/main/java/org/springframework/test/web/reactive/server/JsonPathAssertions.java b/spring-test/src/main/java/org/springframework/test/web/reactive/server/JsonPathAssertions.java
@@ -16,6 +16,8 @@
 
 package org.springframework.test.web.reactive.server;
 
+import java.util.function.Consumer;
+
 import com.jayway.jsonpath.Configuration;
 import org.hamcrest.Matcher;
 import org.jspecify.annotations.Nullable;
@@ -45,26 +47,31 @@ public class JsonPathAssertions extends AbstractJsonPathAssertions<WebTestClient
 	}
 
 
-
 	/**
 	 * Delegates to {@link JsonPathExpectationsHelper#assertValue(String, Matcher)}.
+	 * @deprecated in favor of {@link Consumer}-based variants
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public <T> WebTestClient.BodyContentSpec value(Matcher<? super T> matcher) {
 		getPathHelper().assertValue(getContent(), matcher);
 		return getBodySpec();
 	}
 
 	/**
 	 * Delegates to {@link JsonPathExpectationsHelper#assertValue(String, Matcher, Class)}.
+	 * @deprecated in favor of {@link Consumer}-based variants
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public <T> WebTestClient.BodyContentSpec value(Class<T> targetType, Matcher<? super T> matcher) {
 		getPathHelper().assertValue(getContent(), matcher, targetType);
 		return getBodySpec();
 	}
 
 	/**
 	 * Delegates to {@link JsonPathExpectationsHelper#assertValue(String, Matcher, ParameterizedTypeReference)}.
+	 * @deprecated in favor of {@link Consumer}-based variants
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public <T> WebTestClient.BodyContentSpec value(ParameterizedTypeReference<T> targetType, Matcher<? super T> matcher) {
 		getPathHelper().assertValue(getContent(), matcher, targetType);
 		return getBodySpec();
diff --git a/spring-test/src/main/java/org/springframework/test/web/reactive/server/StatusAssertions.java b/spring-test/src/main/java/org/springframework/test/web/reactive/server/StatusAssertions.java
@@ -16,6 +16,8 @@
 
 package org.springframework.test.web.reactive.server;
 
+import java.util.function.Consumer;
+
 import org.hamcrest.Matcher;
 import org.hamcrest.MatcherAssert;
 
@@ -51,7 +53,9 @@ protected void assertWithDiagnostics(Runnable assertion) {
 	/**
 	 * Match the response status value with a Hamcrest matcher.
 	 * @param matcher the matcher to use
+	 * @deprecated in favor of {@link Consumer}-based variants
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public WebTestClient.ResponseSpec value(Matcher<? super Integer> matcher) {
 		int actual = getStatus().value();
 		assertWithDiagnostics(() -> MatcherAssert.assertThat("Response status", actual, matcher));
diff --git a/spring-test/src/main/java/org/springframework/test/web/reactive/server/WebTestClient.java b/spring-test/src/main/java/org/springframework/test/web/reactive/server/WebTestClient.java
@@ -957,15 +957,19 @@ interface BodySpec<B, S extends BodySpec<B, S>> {
 		/**
 		 * Assert the extracted body with a {@link Matcher}.
 		 * @since 5.1
+		 * @deprecated in favor of {@link Consumer}-based variants
 		 */
+		@Deprecated(since = "7.0", forRemoval = true)
 		@NullUnmarked // To avoid a "Cannot attach type annotations" error when org.hamcrest.Matcher is not in the classpath
 		<T extends S> T value(Matcher<? super B> matcher);
 
 		/**
 		 * Transform the extracted the body with a function, for example, extracting a
 		 * property, and assert the mapped value with a {@link Matcher}.
 		 * @since 5.1
+		 * @deprecated in favor of {@link Consumer}-based variants
 		 */
+		@Deprecated(since = "7.0", forRemoval = true)
 		@NullUnmarked // To avoid a "Cannot attach type annotations" error when org.hamcrest.Matcher is not in the classpath
 		<T extends S, R> T value(@NonNull Function<@Nullable B, @Nullable R> bodyMapper, Matcher<? super R> matcher);
 
@@ -975,6 +979,13 @@ interface BodySpec<B, S extends BodySpec<B, S>> {
 		 */
 		<T extends S> T value(Consumer<@Nullable B> consumer);
 
+		/**
+		 * Transform the extracted the body with a function, for example, extracting a
+		 * property, and assert the mapped value with a {@link Consumer}.
+		 * @since 7.0
+		 */
+		<T extends S, R> T value(@NonNull Function<@Nullable B, @Nullable R> bodyMapper, Consumer<? super R> consumer);
+
 		/**
 		 * Assert the exchange result with the given {@link Consumer}.
 		 */
diff --git a/spring-test/src/main/java/org/springframework/test/web/reactive/server/XpathAssertions.java b/spring-test/src/main/java/org/springframework/test/web/reactive/server/XpathAssertions.java
@@ -18,6 +18,7 @@
 
 import java.util.Map;
 import java.util.Optional;
+import java.util.function.Consumer;
 
 import org.hamcrest.Matcher;
 import org.jspecify.annotations.Nullable;
@@ -60,21 +61,27 @@ protected byte[] getContent() {
 
 	/**
 	 * Delegates to {@link XpathExpectationsHelper#assertString(byte[], String, Matcher)}.
+	 * @deprecated in favor of {@link Consumer}-based variants
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public WebTestClient.BodyContentSpec string(Matcher<? super String> matcher){
 		return assertWith(() -> getXpathHelper().assertString(getContent(), getCharset(), matcher));
 	}
 
 	/**
 	 * Delegates to {@link XpathExpectationsHelper#assertNumber(byte[], String, Matcher)}.
+	 * @deprecated in favor of {@link Consumer}-based variants
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public WebTestClient.BodyContentSpec number(Matcher<? super Double> matcher){
 		return assertWith(() -> getXpathHelper().assertNumber(getContent(), getCharset(), matcher));
 	}
 
 	/**
 	 * Delegates to {@link XpathExpectationsHelper#assertNodeCount(byte[], String, Matcher)}.
+	 * @deprecated in favor of {@link Consumer}-based variants
 	 */
+	@Deprecated(since = "7.0", forRemoval = true)
 	public WebTestClient.BodyContentSpec nodeCount(Matcher<? super Integer> matcher){
 		return assertWith(() -> getXpathHelper().assertNodeCount(getContent(), getCharset(), matcher));
 	}
diff --git a/spring-test/src/test/java/org/springframework/test/web/reactive/server/samples/JsonContentTests.java b/spring-test/src/test/java/org/springframework/test/web/reactive/server/samples/JsonContentTests.java
@@ -18,6 +18,7 @@
 
 import java.net.URI;
 
+import org.hamcrest.MatcherAssert;
 import org.junit.jupiter.api.Test;
 import reactor.core.publisher.Flux;
 
@@ -113,7 +114,7 @@ void jsonPathMatches() {
 				.exchange()
 				.expectStatus().isOk()
 				.expectBody()
-				.jsonPath("$.firstName").value(containsString("oh"));
+				.jsonPath("$.firstName").value(String.class, v -> MatcherAssert.assertThat(v, containsString("oh")));
 	}
 
 	@Test
diff --git a/spring-test/src/test/java/org/springframework/test/web/reactive/server/samples/ResponseEntityTests.java b/spring-test/src/test/java/org/springframework/test/web/reactive/server/samples/ResponseEntityTests.java
@@ -22,6 +22,7 @@
 import java.util.List;
 import java.util.Map;
 
+import org.hamcrest.MatcherAssert;
 import org.junit.jupiter.api.Test;
 import reactor.core.publisher.Flux;
 import reactor.test.StepVerifier;
@@ -72,7 +73,7 @@ void entityMatcher() {
 				.exchange()
 				.expectStatus().isOk()
 				.expectHeader().contentType(MediaType.APPLICATION_JSON)
-				.expectBody(Person.class).value(Person::getName, startsWith("Joh"));
+				.expectBody(Person.class).value(Person::getName, v -> MatcherAssert.assertThat(v, startsWith("Joh")));
 	}
 
 	@Test
diff --git a/spring-test/src/test/java/org/springframework/test/web/reactive/server/samples/XmlContentTests.java b/spring-test/src/test/java/org/springframework/test/web/reactive/server/samples/XmlContentTests.java
@@ -25,6 +25,7 @@
 import jakarta.xml.bind.annotation.XmlAccessorType;
 import jakarta.xml.bind.annotation.XmlElement;
 import jakarta.xml.bind.annotation.XmlRootElement;
+import org.hamcrest.MatcherAssert;
 import org.junit.jupiter.api.Test;
 
 import org.springframework.http.HttpHeaders;
@@ -93,7 +94,7 @@ void xpathMatches() {
 				.exchange()
 				.expectStatus().isOk()
 				.expectBody()
-				.xpath("//person/name").string(startsWith("J"));
+				.xpath("//person/name").string(v -> MatcherAssert.assertThat(v, startsWith("J")));
 	}
 
 	@Test
diff --git a/spring-test/src/test/java/org/springframework/test/web/servlet/samples/client/context/WebAppResourceTests.java b/spring-test/src/test/java/org/springframework/test/web/servlet/samples/client/context/WebAppResourceTests.java
@@ -16,6 +16,7 @@
 
 package org.springframework.test.web.servlet.samples.client.context;
 
+import org.hamcrest.MatcherAssert;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
@@ -70,7 +71,7 @@ public void resourceRequest() {
 				.exchange()
 				.expectStatus().isOk()
 				.expectHeader().contentType("text/javascript")
-				.expectBody(String.class).value(containsString("Spring={};"));
+				.expectBody(String.class).value(v -> MatcherAssert.assertThat(v, containsString("Spring={};")));
 	}
 
 	// Forwarded to the "default" servlet via <mvc:default-servlet-handler/>
diff --git a/spring-test/src/test/java/org/springframework/test/web/servlet/samples/client/standalone/RouterFunctionTests.java b/spring-test/src/test/java/org/springframework/test/web/servlet/samples/client/standalone/RouterFunctionTests.java
@@ -19,6 +19,7 @@
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Consumer;
 
+import org.hamcrest.MatcherAssert;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
 import reactor.core.publisher.Mono;
@@ -46,8 +47,8 @@ public class RouterFunctionTests {
 	void json() {
 		execute("/person/Lee", body -> body.jsonPath("$.name").isEqualTo("Lee")
 				.jsonPath("$.age").isEqualTo(42)
-				.jsonPath("$.age").value(equalTo(42))
-				.jsonPath("$.age").value(Float.class, equalTo(42.0f)));
+				.jsonPath("$.age").value(v -> MatcherAssert.assertThat(v, equalTo(42)))
+				.jsonPath("$.age").value(Float.class, v -> MatcherAssert.assertThat(v, equalTo(42.0f))));
 	}
 
 	@Test
diff --git a/spring-test/src/test/java/org/springframework/test/web/servlet/samples/client/standalone/resultmatches/ContentAssertionTests.java b/spring-test/src/test/java/org/springframework/test/web/servlet/samples/client/standalone/resultmatches/ContentAssertionTests.java
@@ -16,6 +16,7 @@
 
 package org.springframework.test.web.servlet.samples.client.standalone.resultmatches;
 
+import org.hamcrest.MatcherAssert;
 import org.junit.jupiter.api.Test;
 
 import org.springframework.http.MediaType;
@@ -77,11 +78,12 @@ void contentAsString() {
 		testClient.get().uri("/handle").accept(TEXT_PLAIN)
 				.exchange()
 				.expectStatus().isOk()
-				.expectBody(String.class).value(equalTo("Hello world!"));
+				.expectBody(String.class).value(v -> MatcherAssert.assertThat(v, equalTo("Hello world!")));
 		testClient.get().uri("/handleUtf8")
 				.exchange()
 				.expectStatus().isOk()
-				.expectBody(String.class).value(equalTo("\u3053\u3093\u306b\u3061\u306f\u4e16\u754c\uff01"));
+				.expectBody(String.class).value(v ->
+						MatcherAssert.assertThat(v, equalTo("\u3053\u3093\u306b\u3061\u306f\u4e16\u754c\uff01")));
 	}
 
 	@Test
@@ -104,7 +106,7 @@ void contentStringMatcher() {
 		testClient.get().uri("/handle").accept(TEXT_PLAIN)
 				.exchange()
 				.expectStatus().isOk()
-				.expectBody(String.class).value(containsString("world"));
+				.expectBody(String.class).value(v -> MatcherAssert.assertThat(v, containsString("world")));
 	}
 
 	@Test
@@ -113,7 +115,7 @@ void characterEncoding() {
 				.exchange()
 				.expectStatus().isOk()
 				.expectHeader().contentType("text/plain;charset=ISO-8859-1")
-				.expectBody(String.class).value(containsString("world"));
+				.expectBody(String.class).value(v -> MatcherAssert.assertThat(v, containsString("world")));
 
 		testClient.get().uri("/handleUtf8")
 				.exchange()
diff --git a/spring-test/src/test/java/org/springframework/test/web/servlet/samples/client/standalone/resultmatches/JsonPathAssertionTests.java b/spring-test/src/test/java/org/springframework/test/web/servlet/samples/client/standalone/resultmatches/JsonPathAssertionTests.java
diff --git a/spring-test/src/test/java/org/springframework/test/web/servlet/samples/client/standalone/resultmatches/XpathAssertionTests.java b/spring-test/src/test/java/org/springframework/test/web/servlet/samples/client/standalone/resultmatches/XpathAssertionTests.java
