Improve diagnostics when a Bean Override cannot be selected by type

Close spring-projectsGH-34004

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

@@ -67,6 +67,9 @@ class BeanOverrideBeanFactoryPostProcessor implements BeanFactoryPostProcessor,
 
 	private static final BeanNameGenerator beanNameGenerator = DefaultBeanNameGenerator.INSTANCE;
 
+	private static final String unableToOverrideByTypeDiagnosticsMessage = " If the bean is defined from a @Bean method,"
+			+ " please make sure the return type is the most specific type (recommended) or type can be assigned to %s.";
+
 	private final Set<BeanOverrideHandler> beanOverrideHandlers;
 
 	private final BeanOverrideRegistry beanOverrideRegistry;
@@ -154,7 +157,9 @@ else if (requireExistingBean) {
 						Unable to replace bean: there is no bean with name '%s' and type %s \
 						(as required by field '%s.%s')."""
 							.formatted(beanName, handler.getBeanType(),
-								field.getDeclaringClass().getSimpleName(), field.getName()));
+								field.getDeclaringClass().getSimpleName(), field.getName())
+								+ unableToOverrideByTypeDiagnosticsMessage.formatted(handler.getBeanType())
+				);
 			}
 		}
 
@@ -242,6 +247,7 @@ private void wrapBean(ConfigurableListableBeanFactory beanFactory, BeanOverrideH
 					if (candidateCount == 0) {
 						message += "there are no beans of type %s (as required by field '%s.%s')."
 								.formatted(beanType, field.getDeclaringClass().getSimpleName(), field.getName());
+						message += unableToOverrideByTypeDiagnosticsMessage.formatted(beanType);
 					}
 					else {
 						message += "found %d beans of type %s (as required by field '%s.%s'): %s"
@@ -285,7 +291,9 @@ else if (candidateCount == 0) {
 			if (requireExistingBean) {
 				throw new IllegalStateException(
 						"Unable to override bean: there are no beans of type %s (as required by field '%s.%s')."
-							.formatted(beanType, field.getDeclaringClass().getSimpleName(), field.getName()));
+							.formatted(beanType, field.getDeclaringClass().getSimpleName(), field.getName())
+							+ unableToOverrideByTypeDiagnosticsMessage.formatted(beanType)
+				);
 			}
 			return null;
 		}

spring-test/src/test/java/org/springframework/test/context/bean/override/BeanOverrideBeanFactoryPostProcessorTests.java

@@ -85,7 +85,7 @@ void replaceBeanByNameWithoutMatchingBeanDefinitionFails() {
 
 		assertThatIllegalStateException()
 				.isThrownBy(context::refresh)
-				.withMessage("""
+				.withMessageStartingWith("""
 						Unable to replace bean: there is no bean with name 'descriptionBean' \
 						and type java.lang.String (as required by field 'ByNameTestCase.description').""");
 	}
@@ -97,7 +97,7 @@ void replaceBeanByNameWithMatchingBeanDefinitionAndWrongTypeFails() {
 
 		assertThatIllegalStateException()
 				.isThrownBy(context::refresh)
-				.withMessage("""
+				.withMessageStartingWith("""
 						Unable to replace bean: there is no bean with name 'descriptionBean' \
 						and type java.lang.String (as required by field 'ByNameTestCase.description').""");
 	}
@@ -144,7 +144,7 @@ void replaceBeanByTypeWithoutMatchingBeanFails() {
 
 		assertThatIllegalStateException()
 				.isThrownBy(context::refresh)
-				.withMessage("""
+				.withMessageStartingWith("""
 						Unable to override bean: there are no beans of type java.lang.Integer \
 						(as required by field 'ByTypeTestCase.counter').""");
 	}

spring-test/src/test/java/org/springframework/test/context/bean/override/convention/TestBeanTests.java

@@ -39,7 +39,7 @@ void cannotOverrideBeanByNameWithNoSuchBeanName() {
 		BeanOverrideContextCustomizerTestUtils.customizeApplicationContext(FailureByNameLookup.class, context);
 		assertThatIllegalStateException()
 				.isThrownBy(context::refresh)
-				.withMessage("""
+				.withMessageStartingWith("""
 						Unable to replace bean: there is no bean with name 'beanToOverride' \
 						and type java.lang.String (as required by field 'FailureByNameLookup.example').""");
 	}
@@ -51,7 +51,7 @@ void cannotOverrideBeanByNameWithBeanOfWrongType() {
 		BeanOverrideContextCustomizerTestUtils.customizeApplicationContext(FailureByNameLookup.class, context);
 		assertThatIllegalStateException()
 				.isThrownBy(context::refresh)
-				.withMessage("""
+				.withMessageStartingWith("""
 						Unable to replace bean: there is no bean with name 'beanToOverride' \
 						and type java.lang.String (as required by field 'FailureByNameLookup.example').""");
 	}
@@ -62,7 +62,7 @@ void cannotOverrideBeanByTypeWithNoSuchBeanType() {
 		BeanOverrideContextCustomizerTestUtils.customizeApplicationContext(FailureByTypeLookup.class, context);
 		assertThatIllegalStateException()
 				.isThrownBy(context::refresh)
-				.withMessage("""
+				.withMessageStartingWith("""
 						Unable to override bean: there are no beans of \
 						type %s (as required by field '%s.example').""".formatted(
 						String.class.getName(), FailureByTypeLookup.class.getSimpleName()));

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

@@ -40,7 +40,7 @@ void cannotOverrideBeanByNameWithNoSuchBeanName() {
 		BeanOverrideContextCustomizerTestUtils.customizeApplicationContext(FailureByNameLookup.class, context);
 		assertThatIllegalStateException()
 				.isThrownBy(context::refresh)
-				.withMessage("""
+				.withMessageStartingWith("""
 						Unable to replace bean: there is no bean with name 'beanToOverride' \
 						and type java.lang.String (as required by field 'FailureByNameLookup.example').""");
 	}
@@ -52,7 +52,7 @@ void cannotOverrideBeanByNameWithBeanOfWrongType() {
 		BeanOverrideContextCustomizerTestUtils.customizeApplicationContext(FailureByNameLookup.class, context);
 		assertThatIllegalStateException()
 				.isThrownBy(context::refresh)
-				.withMessage("""
+				.withMessageStartingWith("""
 						Unable to replace bean: there is no bean with name 'beanToOverride' \
 						and type java.lang.String (as required by field 'FailureByNameLookup.example').""");
 	}
@@ -63,7 +63,7 @@ void cannotOverrideBeanByTypeWithNoSuchBeanType() {
 		BeanOverrideContextCustomizerTestUtils.customizeApplicationContext(FailureByTypeLookup.class, context);
 		assertThatIllegalStateException()
 				.isThrownBy(context::refresh)
-				.withMessage("""
+				.withMessageStartingWith("""
 						Unable to override bean: there are no beans of \
 						type java.lang.String (as required by field 'FailureByTypeLookup.example').""");
 	}

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

@@ -50,7 +50,7 @@ void contextCustomizerCannotBeCreatedWithNoSuchBeanType() {
 		BeanOverrideContextCustomizerTestUtils.customizeApplicationContext(ByTypeSingleLookup.class, context);
 		assertThatIllegalStateException()
 				.isThrownBy(context::refresh)
-				.withMessage("""
+				.withMessageStartingWith("""
 						Unable to select a bean to wrap: there are no beans of type java.lang.String \
 						(as required by field 'ByTypeSingleLookup.example').""");
 	}