Document potential need to use Mockito.doXxx() to stub a @⁠MockitoSpyBean

Closes gh-35410

Author: sbrannen

framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-mockitobean.adoc

@@ -77,6 +77,17 @@ exactly one candidate bean exists.
 
 [TIP]
 ====
+As stated in the documentation for Mockito, there are times when using `Mockito.when()` is
+inappropriate for stubbing a spy – for example, if calling a real method on a spy results
+in undesired side effects.
+
+To avoid such undesired side effects, consider using
+`Mockito.doReturn(...).when(spy)...`, `Mockito.doThrow(...).when(spy)...`,
+`Mockito.doNothing().when(spy)...`, and similar methods.
+====
+
+[NOTE]
+====
 Only _singleton_ beans can be overridden. Any attempt to override a non-singleton bean
 will result in an exception.
 

spring-test/src/main/java/org/springframework/test/context/bean/override/mockito/MockitoSpyBean.java

@@ -67,6 +67,15 @@
  * {@link org.springframework.beans.factory.config.ConfigurableListableBeanFactory#registerResolvableDependency(Class, Object)
  * registered directly} as resolvable dependencies.
  *
+ * <p><strong>NOTE</strong>: As stated in the documentation for Mockito, there are
+ * times when using {@code Mockito.when()} is inappropriate for stubbing a spy
+ * &mdash; for example, if calling a real method on a spy results in undesired
+ * side effects. To avoid such undesired side effects, consider using
+ * {@link org.mockito.Mockito#doReturn(Object) Mockito.doReturn(...).when(spy)...},
+ * {@link org.mockito.Mockito#doThrow(Class) Mockito.doThrow(...).when(spy)...},
+ * {@link org.mockito.Mockito#doNothing() Mockito.doNothing().when(spy)...}, and
+ * similar methods.
+ *
  * <p><strong>WARNING</strong>: Using {@code @MockitoSpyBean} in conjunction with
  * {@code @ContextHierarchy} can lead to undesirable results since each
  * {@code @MockitoSpyBean} will be applied to all context hierarchy levels by default.