Support @⁠MockitoSpyBean at the type level on test classes

Prior to this commit, @⁠MockitoSpyBean could only be declared on fields
within test classes, which prevented developers from being able to
easily reuse spy configuration across a test suite.

With this commit, @⁠MockitoSpyBean is now supported at the type level
on test classes, their superclasses, and interfaces implemented by
those classes. @⁠MockitoSpyBean is also supported on enclosing classes
for @⁠Nested test classes, their superclasses, and interfaces
implemented by those classes, while honoring @⁠NestedTestConfiguration
semantics.

In addition, @⁠MockitoSpyBean:

- has a new `types` attribute that can be used to declare the type or
  types to spy when @⁠MockitoSpyBean is declared at the type level

- can be declared as a repeatable annotation at the type level

- can be declared as a meta-annotation on a custom composed annotation
  which can be reused across a test suite (see the @⁠SharedSpies
  example in the reference manual)

To support these new features, this commit also includes the following
changes.

- MockitoSpyBeanOverrideProcessor has been revised to support
  @⁠MockitoSpyBean at the type level.

- The "Bean Overriding in Tests" and "@⁠MockitoBean and
  @⁠MockitoSpyBean" sections of the reference manual have been fully
  revised.

See gh-34408
Closes gh-33925

Author: sbrannen

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

@@ -1,34 +1,60 @@
 [[spring-testing-annotation-beanoverriding-mockitobean]]
 = `@MockitoBean` and `@MockitoSpyBean`
 
-`@MockitoBean` and `@MockitoSpyBean` are used on non-static fields in test classes to
-override beans in the test's `ApplicationContext` with a Mockito _mock_ or _spy_,
-respectively. In the latter case, an early instance of the original bean is captured and
-wrapped by the spy.
+`@MockitoBean` and `@MockitoSpyBean` can be used in test classes to override a bean in
+the test's `ApplicationContext` with a Mockito _mock_ or _spy_, respectively. In the
+latter case, an early instance of the original bean is captured and wrapped by the spy.
+
+The annotations can be applied in the following ways.
+
+* On a non-static field in a test class or any of its superclasses.
+* On a non-static field in an enclosing class for a `@Nested` test class or in any class
+  in the type hierarchy or enclosing class hierarchy above the `@Nested` test class.
+* At the type level on a test class or any superclass or implemented interface in the
+  type hierarchy above the test class.
+* At the type level on an enclosing class for a `@Nested` test class or on any class or
+  interface in the type hierarchy or enclosing class hierarchy above the `@Nested` test
+  class.
+
+When `@MockitoBean` or `@MockitoSpyBean` is declared on a field, the bean to mock or spy
+is inferred from the type of the annotated field. If multiple candidates exist in the
+`ApplicationContext`, a `@Qualifier` annotation can be declared on the field to help
+disambiguate. In the absence of a `@Qualifier` annotation, the name of the annotated
+field will be used as a _fallback qualifier_. Alternatively, you can explicitly specify a
+bean name to mock or spy by setting the `value` or `name` attribute in the annotation.
+
+When `@MockitoBean` or `@MockitoSpyBean` is declared at the type level, the type of bean
+(or beans) to mock or spy must be supplied via the `types` attribute in the annotation –
+for example, `@MockitoBean(types = {OrderService.class, UserService.class})`. If multiple
+candidates exist in the `ApplicationContext`, you can explicitly specify a bean name to
+mock or spy by setting the `name` attribute. Note, however, that the `types` attribute
+must contain a single type if an explicit bean `name` is configured – for example,
+`@MockitoBean(name = "ps1", types = PrintingService.class)`.
 
-By default, the annotated field's type is used to search for candidate beans to override.
-If multiple candidates match, `@Qualifier` can be provided to narrow the candidate to
-override. Alternatively, a candidate whose bean name matches the name of the field will
-match.
+To support reuse of mock configuration, `@MockitoBean` and `@MockitoSpyBean` may be used
+as meta-annotations to create custom _composed annotations_ – for example, to define
+common mock or spy configuration in a single annotation that can be reused across a test
+suite. `@MockitoBean` and `@MockitoSpyBean` can also be used as repeatable annotations at
+the type level — for example, to mock or spy several beans by name.
 
 [WARNING]
 ====
-Qualifiers, including the name of the field, are used to determine if a separate
+Qualifiers, including the name of a field, are used to determine if a separate
 `ApplicationContext` needs to be created. If you are using this feature to mock or spy
-the same bean in several test classes, make sure to name the field consistently to avoid
+the same bean in several test classes, make sure to name the fields consistently to avoid
 creating unnecessary contexts.
 ====
 
 Each annotation also defines Mockito-specific attributes to fine-tune the mocking behavior.
 
 The `@MockitoBean` annotation uses the `REPLACE_OR_CREATE`
-xref:testing/testcontext-framework/bean-overriding.adoc#testcontext-bean-overriding-custom[strategy for test bean overriding].
-If no existing bean matches, a new bean is created on the fly. However, you can switch to
-the `REPLACE` strategy by setting the `enforceOverride` attribute to `true`. See the
-following section for an example.
+xref:testing/testcontext-framework/bean-overriding.adoc#testcontext-bean-overriding-strategy[strategy for bean overrides].
+If a corresponding bean does not exist, a new bean will be created. However, you can
+switch to the `REPLACE` strategy by setting the `enforceOverride` attribute to `true` –
+for example, `@MockitoBean(enforceOverride = true)`.
 
 The `@MockitoSpyBean` annotation uses the `WRAP`
-xref:testing/testcontext-framework/bean-overriding.adoc#testcontext-bean-overriding-custom[strategy],
+xref:testing/testcontext-framework/bean-overriding.adoc#testcontext-bean-overriding-strategy[strategy],
 and the original instance is wrapped in a Mockito spy. This strategy requires that
 exactly one candidate bean exists.
 
@@ -56,15 +82,8 @@ or `private` depending on the needs or coding practices of the project.
 [[spring-testing-annotation-beanoverriding-mockitobean-examples]]
 == `@MockitoBean` Examples
 
-When using `@MockitoBean`, a new bean will be created if a corresponding bean does not
-exist. However, if you would like for the test to fail when a corresponding bean does not
-exist, you can set the `enforceOverride` attribute to `true` – for example,
-`@MockitoBean(enforceOverride = true)`.
-
-To use a by-name override rather than a by-type override, specify the `name` (or `value`)
-attribute of the annotation.
-
-The following example shows how to use the default behavior of the `@MockitoBean` annotation:
+The following example shows how to use the default behavior of the `@MockitoBean`
+annotation.
 
 [tabs]
 ======
@@ -81,7 +100,7 @@ Java::
 		// tests...
 	}
 ----
-<1> Replace the bean with type `CustomService` with a Mockito `mock`.
+<1> Replace the bean with type `CustomService` with a Mockito mock.
 ======
 
 In the example above, we are creating a mock for `CustomService`. If more than one bean
@@ -90,7 +109,8 @@ will fail, and you will need to provide a qualifier of some sort to identify whi
 `CustomService` beans you want to override. If no such bean exists, a bean will be
 created with an auto-generated bean name.
 
-The following example uses a by-name lookup, rather than a by-type lookup:
+The following example uses a by-name lookup, rather than a by-type lookup. If no bean
+named `service` exists, one is created.
 
 [tabs]
 ======
@@ -108,32 +128,9 @@ Java::
 
 	}
 ----
-<1> Replace the bean named `service` with a Mockito `mock`.
+<1> Replace the bean named `service` with a Mockito mock.
 ======
 
-If no bean named `service` exists, one is created.
-
-`@MockitoBean` can also be used at the type level:
-
-- on a test class or any superclass or implemented interface in the type hierarchy above
-  the test class
-- on an enclosing class for a `@Nested` test class or on any class or interface in the
-  type hierarchy or enclosing class hierarchy above the `@Nested` test class
-
-When `@MockitoBean` is declared at the type level, the type of bean (or beans) to mock
-must be supplied via the `types` attribute – for example,
-`@MockitoBean(types = {OrderService.class, UserService.class})`. If multiple candidates
-exist in the application context, you can explicitly specify a bean name to mock by
-setting the `name` attribute. Note, however, that the `types` attribute must contain a
-single type if an explicit bean `name` is configured – for example,
-`@MockitoBean(name = "ps1", types = PrintingService.class)`.
-
-To support reuse of mock configuration, `@MockitoBean` may be used as a meta-annotation
-to create custom _composed annotations_ — for example, to define common mock
-configuration in a single annotation that can be reused across a test suite.
-`@MockitoBean` can also be used as a repeatable annotation at the type level — for
-example, to mock several beans by name.
-
 The following `@SharedMocks` annotation registers two mocks by-type and one mock by-name.
 
 [tabs]
@@ -191,7 +188,7 @@ APIs.
 == `@MockitoSpyBean` Examples
 
 The following example shows how to use the default behavior of the `@MockitoSpyBean`
-annotation:
+annotation.
 
 [tabs]
 ======
@@ -208,15 +205,15 @@ Java::
 		// tests...
 	}
 ----
-<1> Wrap the bean with type `CustomService` with a Mockito `spy`.
+<1> Wrap the bean with type `CustomService` with a Mockito spy.
 ======
 
 In the example above, we are wrapping the bean with type `CustomService`. If more than
 one bean of that type exists, the bean named `customService` is considered. Otherwise,
 the test will fail, and you will need to provide a qualifier of some sort to identify
 which of the `CustomService` beans you want to spy.
 
-The following example uses a by-name lookup, rather than a by-type lookup:
+The following example uses a by-name lookup, rather than a by-type lookup.
 
 [tabs]
 ======
@@ -233,5 +230,58 @@ Java::
 		// tests...
 	}
 ----
-<1> Wrap the bean named `service` with a Mockito `spy`.
+<1> Wrap the bean named `service` with a Mockito spy.
+======
+
+The following `@SharedSpies` annotation registers two spies by-type and one spy by-name.
+
+[tabs]
+======
+Java::
++
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+	@Target(ElementType.TYPE)
+	@Retention(RetentionPolicy.RUNTIME)
+	@MockitoSpyBean(types = {OrderService.class, UserService.class}) // <1>
+	@MockitoSpyBean(name = "ps1", types = PrintingService.class) // <2>
+	public @interface SharedSpies {
+	}
+----
+<1> Register `OrderService` and `UserService` spies by-type.
+<2> Register `PrintingService` spy by-name.
+======
+
+The following demonstrates how `@SharedSpies` can be used on a test class.
+
+[tabs]
+======
+Java::
++
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+	@SpringJUnitConfig(TestConfig.class)
+	@SharedSpies // <1>
+	class BeanOverrideTests {
+
+		@Autowired OrderService orderService; // <2>
+
+		@Autowired UserService userService; // <2>
+
+		@Autowired PrintingService ps1; // <2>
+
+		// Inject other components that rely on the spies.
+
+		@Test
+		void testThatDependsOnMocks() {
+			// ...
+		}
+	}
+----
+<1> Register common spies via the custom `@SharedSpies` annotation.
+<2> Optionally inject spies to _stub_ or _verify_ them.
 ======
+
+TIP: The spies can also be injected into `@Configuration` classes or other test-related
+components in the `ApplicationContext` in order to configure them with Mockito's stubbing
+APIs.

framework-docs/modules/ROOT/pages/testing/testcontext-framework/bean-overriding.adoc

@@ -2,8 +2,8 @@
 = Bean Overriding in Tests
 
 Bean overriding in tests refers to the ability to override specific beans in the
-`ApplicationContext` for a test class, by annotating one or more non-static fields in the
-test class.
+`ApplicationContext` for a test class, by annotating the test class or one or more
+non-static fields in the test class.
 
 NOTE: This feature is intended as a less risky alternative to the practice of registering
 a bean via `@Bean` with the `DefaultListableBeanFactory`
@@ -42,15 +42,16 @@ The `spring-test` module registers implementations of the latter two
 {spring-framework-code}/spring-test/src/main/resources/META-INF/spring.factories[`META-INF/spring.factories`
 properties file].
 
-The bean overriding infrastructure searches in test classes for any non-static field that
-is meta-annotated with `@BeanOverride` and instantiates the corresponding
-`BeanOverrideProcessor` which is responsible for creating an appropriate
-`BeanOverrideHandler`.
+The bean overriding infrastructure searches for annotations on test classes as well as
+annotations on non-static fields in test classes that are meta-annotated with
+`@BeanOverride` and instantiates the corresponding `BeanOverrideProcessor` which is
+responsible for creating an appropriate `BeanOverrideHandler`.
 
 The internal `BeanOverrideBeanFactoryPostProcessor` then uses bean override handlers to
 alter the test's `ApplicationContext` by creating, replacing, or wrapping beans as
 defined by the corresponding `BeanOverrideStrategy`:
 
+[[testcontext-bean-overriding-strategy]]
 `REPLACE`::
   Replaces the bean. Throws an exception if a corresponding bean does not exist.
 `REPLACE_OR_CREATE`::

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

@@ -31,9 +31,9 @@
 
 /**
  * {@code @MockitoBean} is an annotation that can be used in test classes to
- * override beans in a test's
+ * override a bean in the test's
  * {@link org.springframework.context.ApplicationContext ApplicationContext}
- * using Mockito mocks.
+ * with a Mockito mock.
  *
  * <p>{@code @MockitoBean} can be applied in the following ways.
  * <ul>
@@ -49,18 +49,19 @@
  * </ul>
  *
  * <p>When {@code @MockitoBean} is declared on a field, the bean to mock is inferred
- * from the type of the annotated field. If multiple candidates exist, a
- * {@code @Qualifier} annotation can be declared on the field to help disambiguate.
- * In the absence of a {@code @Qualifier} annotation, the name of the annotated
- * field will be used as a fallback qualifier. Alternatively, you can explicitly
- * specify a bean name to mock by setting the {@link #value() value} or
- * {@link #name() name} attribute.
+ * from the type of the annotated field. If multiple candidates exist in the
+ * {@code ApplicationContext}, a {@code @Qualifier} annotation can be declared
+ * on the field to help disambiguate. In the absence of a {@code @Qualifier}
+ * annotation, the name of the annotated field will be used as a <em>fallback
+ * qualifier</em>. Alternatively, you can explicitly specify a bean name to mock
+ * by setting the {@link #value() value} or {@link #name() name} attribute.
  *
  * <p>When {@code @MockitoBean} is declared at the type level, the type of bean
- * to mock must be supplied via the {@link #types() types} attribute. If multiple
- * candidates exist, you can explicitly specify a bean name to mock by setting the
- * {@link #name() name} attribute. Note, however, that the {@code types} attribute
- * must contain a single type if an explicit bean {@code name} is configured.
+ * (or beans) to mock must be supplied via the {@link #types() types} attribute.
+ * If multiple candidates exist in the {@code ApplicationContext}, you can
+ * explicitly specify a bean name to mock by setting the {@link #name() name}
+ * attribute. Note, however, that the {@code types} attribute must contain a
+ * single type if an explicit bean {@code name} is configured.
  *
  * <p>A bean will be created if a corresponding bean does not exist. However, if
  * you would like for the test to fail when a corresponding bean does not exist,
@@ -111,7 +112,7 @@
 public @interface MockitoBean {
 
 	/**
-	 * Alias for {@link #name()}.
+	 * Alias for {@link #name() name}.
 	 * <p>Intended to be used when no other attributes are needed &mdash; for
 	 * example, {@code @MockitoBean("customBeanName")}.
 	 * @see #name()
@@ -136,7 +137,7 @@
 	 * <p>Each type specified will result in a mock being created and registered
 	 * with the {@code ApplicationContext}.
 	 * <p>Types must be omitted when the annotation is used on a field.
-	 * <p>When {@code @MockitoBean} also defines a {@link #name}, this attribute
+	 * <p>When {@code @MockitoBean} also defines a {@link #name name}, this attribute
 	 * can only contain a single value.
 	 * @return the types to mock
 	 * @since 6.2.2

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

@@ -45,8 +45,10 @@ public AbstractMockitoBeanOverrideHandler createHandler(Annotation overrideAnnot
 					"The @MockitoBean 'types' attribute must be omitted when declared on a field");
 			return new MockitoBeanOverrideHandler(field, ResolvableType.forField(field, testClass), mockitoBean);
 		}
-		else if (overrideAnnotation instanceof MockitoSpyBean spyBean) {
-			return new MockitoSpyBeanOverrideHandler(field, ResolvableType.forField(field, testClass), spyBean);
+		else if (overrideAnnotation instanceof MockitoSpyBean mockitoSpyBean) {
+			Assert.state(mockitoSpyBean.types().length == 0,
+					"The @MockitoSpyBean 'types' attribute must be omitted when declared on a field");
+			return new MockitoSpyBeanOverrideHandler(field, ResolvableType.forField(field, testClass), mockitoSpyBean);
 		}
 		throw new IllegalStateException("""
 				Invalid annotation passed to MockitoBeanOverrideProcessor: \
@@ -56,21 +58,34 @@ else if (overrideAnnotation instanceof MockitoSpyBean spyBean) {
 
 	@Override
 	public List<BeanOverrideHandler> createHandlers(Annotation overrideAnnotation, Class<?> testClass) {
-		if (!(overrideAnnotation instanceof MockitoBean mockitoBean)) {
-			throw new IllegalStateException("""
-					Invalid annotation passed to MockitoBeanOverrideProcessor: \
-					expected @MockitoBean on test class """ + testClass.getName());
+		if (overrideAnnotation instanceof MockitoBean mockitoBean) {
+			Class<?>[] types = mockitoBean.types();
+			Assert.state(types.length > 0,
+					"The @MockitoBean 'types' attribute must not be empty when declared on a class");
+			Assert.state(mockitoBean.name().isEmpty() || types.length == 1,
+					"The @MockitoBean 'name' attribute cannot be used when mocking multiple types");
+			List<BeanOverrideHandler> handlers = new ArrayList<>();
+			for (Class<?> type : types) {
+				handlers.add(new MockitoBeanOverrideHandler(ResolvableType.forClass(type), mockitoBean));
+			}
+			return handlers;
 		}
-		Class<?>[] types = mockitoBean.types();
-		Assert.state(types.length > 0,
-				"The @MockitoBean 'types' attribute must not be empty when declared on a class");
-		Assert.state(mockitoBean.name().isEmpty() || types.length == 1,
-				"The @MockitoBean 'name' attribute cannot be used when mocking multiple types");
-		List<BeanOverrideHandler> handlers = new ArrayList<>();
-		for (Class<?> type : types) {
-			handlers.add(new MockitoBeanOverrideHandler(ResolvableType.forClass(type), mockitoBean));
+		else if (overrideAnnotation instanceof MockitoSpyBean mockitoSpyBean) {
+			Class<?>[] types = mockitoSpyBean.types();
+			Assert.state(types.length > 0,
+					"The @MockitoSpyBean 'types' attribute must not be empty when declared on a class");
+			Assert.state(mockitoSpyBean.name().isEmpty() || types.length == 1,
+					"The @MockitoSpyBean 'name' attribute cannot be used when mocking multiple types");
+			List<BeanOverrideHandler> handlers = new ArrayList<>();
+			for (Class<?> type : types) {
+				handlers.add(new MockitoSpyBeanOverrideHandler(ResolvableType.forClass(type), mockitoSpyBean));
+			}
+			return handlers;
 		}
-		return handlers;
+		throw new IllegalStateException("""
+				Invalid annotation passed to MockitoBeanOverrideProcessor: \
+				expected either @MockitoBean or @MockitoSpyBean on test class %s"""
+					.formatted(testClass.getName()));
 	}
 
 }