From b019ebee6e0c7b6d120817863f56a82689763bf5 Mon Sep 17 00:00:00 2001
From: Sam Brannen <104798+sbrannen@users.noreply.github.com>
Date: Tue, 4 Nov 2025 13:42:22 +0100
Subject: [PATCH] =?UTF-8?q?Document=20that=20@=E2=81=A0MockitoSpyBean=20ca?=
 =?UTF-8?q?nnot=20spy=20on=20a=20scoped=20proxy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

See gh-35722
---
 .../integration-spring/annotation-mockitobean.adoc          | 4 ++++
 .../test/context/bean/override/mockito/MockitoSpyBean.java  | 6 ++++++
 2 files changed, 10 insertions(+)

diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-mockitobean.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-mockitobean.adoc
index 9b4a0b4cf30..2b072e8b0e5 100644
--- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-mockitobean.adoc
+++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-mockitobean.adoc
@@ -102,6 +102,10 @@ will be replaced with a singleton mock of the type of object created by the `Fac
 
 Similarly, when using `@MockitoSpyBean` to create a spy for a `FactoryBean`, a spy will
 be created for the object created by the `FactoryBean`, not for the `FactoryBean` itself.
+
+Furthermore, `@MockitoSpyBean` cannot be used to spy on a scoped proxy — for example, a
+bean annotated with `@Scope(proxyMode = ScopedProxyMode.TARGET_CLASS)`. Any attempt to do
+so will fail with an exception.
 ====
 
 [NOTE]
diff --git a/spring-test/src/main/java/org/springframework/test/context/bean/override/mockito/MockitoSpyBean.java b/spring-test/src/main/java/org/springframework/test/context/bean/override/mockito/MockitoSpyBean.java
index db885b12591..7ad92818a36 100644
--- a/spring-test/src/main/java/org/springframework/test/context/bean/override/mockito/MockitoSpyBean.java
+++ b/spring-test/src/main/java/org/springframework/test/context/bean/override/mockito/MockitoSpyBean.java
@@ -94,6 +94,12 @@ import org.springframework.test.context.bean.override.BeanOverride;
  * be created for the object created by the {@code FactoryBean}, not for the
  * {@code FactoryBean} itself.
  *
+ * <p><strong>WARNING</strong>: {@code @MockitoSpyBean} cannot be used to spy on
+ * a scoped proxy &mdash; for example, a bean annotated with
+ * {@link org.springframework.context.annotation.Scope
+ * &#64;Scope(proxyMode = ScopedProxyMode.TARGET_CLASS)}. Any attempt to do so will
+ * fail with an exception.
+ *
  * <p>There are no restrictions on the visibility of a {@code @MockitoSpyBean} field.
  * Such fields can therefore be {@code public}, {@code protected}, package-private
  * (default visibility), or {@code private} depending on the needs or coding