Prefer DynamicPropertyRegistar to DynamicPropertyRegistry

Closes gh-41996

Author: wilkinsona

spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/dev-services.adoc

@@ -364,9 +364,9 @@ TIP: You can use the Maven goal `spring-boot:test-run` or the Gradle task `bootT
 [[features.dev-services.testcontainers.at-development-time.dynamic-properties]]
 ==== Contributing Dynamic Properties at Development Time
 
-If you want to contribute dynamic properties at development time from your `Container` `@Bean` methods, you can do so by injecting a `DynamicPropertyRegistry`.
-This works in a similar way to the xref:testing/testcontainers.adoc#testing.testcontainers.dynamic-properties[`@DynamicPropertySource` annotation] that you can use in your tests.
-It allows you to add properties that will become available once your container has started.
+If you want to contribute dynamic properties at development time from your `Container` `@Bean` methods, define an additional `DynamicPropertyRegistrar` bean.
+The registrar should be defined using a `@Bean` method that injects the container from which the properties will be sourced as a parameter.
+This arrangement ensures that container has been started before the properties are used.
 
 A typical configuration would look like this:
 

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/devservices/testcontainers/atdevelopmenttime/dynamicproperties/MyContainersConfiguration.java

@@ -20,17 +20,22 @@
 
 import org.springframework.boot.test.context.TestConfiguration;
 import org.springframework.context.annotation.Bean;
-import org.springframework.test.context.DynamicPropertyRegistry;
+import org.springframework.test.context.DynamicPropertyRegistrar;
 
 @TestConfiguration(proxyBeanMethods = false)
 public class MyContainersConfiguration {
 
 	@Bean
-	public MongoDBContainer mongoDbContainer(DynamicPropertyRegistry properties) {
-		MongoDBContainer container = new MongoDBContainer("mongo:5.0");
-		properties.add("spring.data.mongodb.host", container::getHost);
-		properties.add("spring.data.mongodb.port", container::getFirstMappedPort);
-		return container;
+	public MongoDBContainer mongoDbContainer() {
+		return new MongoDBContainer("mongo:5.0");
+	}
+
+	@Bean
+	public DynamicPropertyRegistrar mongoDbProperties(MongoDBContainer container) {
+		return (properties) -> {
+			properties.add("spring.data.mongodb.host", container::getHost);
+			properties.add("spring.data.mongodb.port", container::getFirstMappedPort);
+		};
 	}
 
 }

spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/testcontainers/atdevelopmenttime/dynamicproperties/MyContainersConfiguration.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2023 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,18 +18,23 @@ package org.springframework.boot.docs.features.testcontainers.atdevelopmenttime.
 
 import org.springframework.boot.test.context.TestConfiguration
 import org.springframework.context.annotation.Bean
-import org.springframework.test.context.DynamicPropertyRegistry
+import org.springframework.test.context.DynamicPropertyRegistrar;
 import org.testcontainers.containers.MongoDBContainer
 
 @TestConfiguration(proxyBeanMethods = false)
 class MyContainersConfiguration {
 
 	@Bean
-	fun mongoDbContainer(properties: DynamicPropertyRegistry): MongoDBContainer {
-		var container = MongoDBContainer("mongo:5.0")
-		properties.add("spring.data.mongodb.host", container::getHost)
-		properties.add("spring.data.mongodb.port", container::getFirstMappedPort)
-		return container
+	fun mongoDbContainer(): MongoDBContainer {
+		return MongoDBContainer("mongo:5.0")
+	}
+	
+	@Bean
+	fun mongoDbProperties(container: MongoDBContainer): DynamicPropertyRegistrar {
+		return DynamicPropertyRegistrar { properties ->
+			properties.add("spring.data.mongodb.host") { container.host }
+			properties.add("spring.data.mongodb.port") { container.firstMappedPort }
+		}
 	}
 
 }

spring-boot-project/spring-boot-testcontainers/src/dockerTest/java/org/springframework/boot/testcontainers/ImportTestcontainersTests.java

@@ -103,7 +103,7 @@ void importWhenHasNonStaticContainerFieldThrowsException() {
 	void importWhenHasContainerDefinitionsWithDynamicPropertySource() {
 		this.applicationContext = new AnnotationConfigApplicationContext(
 				ContainerDefinitionsWithDynamicPropertySource.class);
-		assertThat(this.applicationContext.getEnvironment().containsProperty("container.port")).isTrue();
+		assertThat(this.applicationContext.getEnvironment().getProperty("container.port")).isNotNull();
 	}
 
 	@Test

spring-boot-project/spring-boot-testcontainers/src/dockerTest/java/org/springframework/boot/testcontainers/properties/TestcontainersPropertySourceAutoConfigurationTests.java

@@ -21,19 +21,22 @@
 
 import com.redis.testcontainers.RedisContainer;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
 
 import org.springframework.boot.autoconfigure.AutoConfigurations;
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.boot.test.context.runner.ApplicationContextRunner;
-import org.springframework.boot.testcontainers.lifecycle.BeforeTestcontainerUsedEvent;
 import org.springframework.boot.testcontainers.lifecycle.TestcontainersLifecycleApplicationContextInitializer;
 import org.springframework.boot.testsupport.container.DisabledIfDockerUnavailable;
 import org.springframework.boot.testsupport.container.TestImage;
+import org.springframework.boot.testsupport.system.CapturedOutput;
+import org.springframework.boot.testsupport.system.OutputCaptureExtension;
 import org.springframework.context.ApplicationEvent;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.context.annotation.Import;
+import org.springframework.test.context.DynamicPropertyRegistrar;
 import org.springframework.test.context.DynamicPropertyRegistry;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -42,27 +45,78 @@
  * Tests for {@link TestcontainersPropertySourceAutoConfiguration}.
  *
  * @author Phillip Webb
+ * @author Andy Wilkinson
  */
 @DisabledIfDockerUnavailable
+@ExtendWith(OutputCaptureExtension.class)
 class TestcontainersPropertySourceAutoConfigurationTests {
 
 	private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
 		.withInitializer(new TestcontainersLifecycleApplicationContextInitializer())
 		.withConfiguration(AutoConfigurations.of(TestcontainersPropertySourceAutoConfiguration.class));
 
 	@Test
-	void containerBeanMethodContributesProperties() {
-		List<ApplicationEvent> events = new ArrayList<>();
+	@SuppressWarnings("removal")
+	@Deprecated(since = "3.4.0", forRemoval = true)
+	void registeringADynamicPropertyFailsByDefault() {
 		this.contextRunner.withUserConfiguration(ContainerAndPropertiesConfiguration.class)
+			.run((context) -> assertThat(context).getFailure()
+				.rootCause()
+				.isInstanceOf(
+						org.springframework.boot.testcontainers.properties.TestcontainersPropertySource.DynamicPropertyRegistryInjectionException.class)
+				.hasMessageStartingWith(
+						"Support for injecting a DynamicPropertyRegistry into @Bean methods is deprecated"));
+	}
+
+	@Test
+	@SuppressWarnings("removal")
+	@Deprecated(since = "3.4.0", forRemoval = true)
+	void registeringADynamicPropertyCanLogAWarningAndContributeProperty(CapturedOutput output) {
+		List<ApplicationEvent> events = new ArrayList<>();
+		this.contextRunner.withPropertyValues("spring.testcontainers.dynamic-property-registry-injection=warn")
+			.withUserConfiguration(ContainerAndPropertiesConfiguration.class)
+			.withInitializer((context) -> context.addApplicationListener(events::add))
+			.run((context) -> {
+				TestBean testBean = context.getBean(TestBean.class);
+				RedisContainer redisContainer = context.getBean(RedisContainer.class);
+				assertThat(testBean.getUsingPort()).isEqualTo(redisContainer.getFirstMappedPort());
+				assertThat(events.stream()
+					.filter(org.springframework.boot.testcontainers.lifecycle.BeforeTestcontainerUsedEvent.class::isInstance))
+					.hasSize(1);
+				assertThat(output)
+					.contains("Support for injecting a DynamicPropertyRegistry into @Bean methods is deprecated");
+			});
+	}
+
+	@Test
+	@SuppressWarnings("removal")
+	@Deprecated(since = "3.4.0", forRemoval = true)
+	void registeringADynamicPropertyCanBePermittedAndContributeProperty(CapturedOutput output) {
+		List<ApplicationEvent> events = new ArrayList<>();
+		this.contextRunner.withPropertyValues("spring.testcontainers.dynamic-property-registry-injection=allow")
+			.withUserConfiguration(ContainerAndPropertiesConfiguration.class)
 			.withInitializer((context) -> context.addApplicationListener(events::add))
 			.run((context) -> {
 				TestBean testBean = context.getBean(TestBean.class);
 				RedisContainer redisContainer = context.getBean(RedisContainer.class);
 				assertThat(testBean.getUsingPort()).isEqualTo(redisContainer.getFirstMappedPort());
-				assertThat(events.stream().filter(BeforeTestcontainerUsedEvent.class::isInstance)).hasSize(1);
+				assertThat(events.stream()
+					.filter(org.springframework.boot.testcontainers.lifecycle.BeforeTestcontainerUsedEvent.class::isInstance))
+					.hasSize(1);
+				assertThat(output)
+					.doesNotContain("Support for injecting a DynamicPropertyRegistry into @Bean methods is deprecated");
 			});
 	}
 
+	@Test
+	void dynamicPropertyRegistrarBeanContributesProperties(CapturedOutput output) {
+		this.contextRunner.withUserConfiguration(ContainerAndPropertyRegistrarConfiguration.class).run((context) -> {
+			TestBean testBean = context.getBean(TestBean.class);
+			RedisContainer redisContainer = context.getBean(RedisContainer.class);
+			assertThat(testBean.getUsingPort()).isEqualTo(redisContainer.getFirstMappedPort());
+		});
+	}
+
 	@Configuration(proxyBeanMethods = false)
 	@EnableConfigurationProperties(ContainerProperties.class)
 	@Import(TestBean.class)
@@ -77,6 +131,23 @@ RedisContainer redisContainer(DynamicPropertyRegistry properties) {
 
 	}
 
+	@Configuration(proxyBeanMethods = false)
+	@EnableConfigurationProperties(ContainerProperties.class)
+	@Import(TestBean.class)
+	static class ContainerAndPropertyRegistrarConfiguration {
+
+		@Bean
+		RedisContainer redisContainer() {
+			return TestImage.container(RedisContainer.class);
+		}
+
+		@Bean
+		DynamicPropertyRegistrar redisProperties(RedisContainer container) {
+			return (registry) -> registry.add("container.port", container::getFirstMappedPort);
+		}
+
+	}
+
 	@ConfigurationProperties("container")
 	record ContainerProperties(int port) {
 	}

spring-boot-project/spring-boot-testcontainers/src/dockerTest/java/org/springframework/boot/testcontainers/properties/TestcontainersPropertySourceAutoConfigurationWithSpringBootTestIntegrationTest.java

@@ -18,26 +18,41 @@
 
 import org.junit.jupiter.api.Test;
 
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.SpringBootConfiguration;
 import org.springframework.boot.autoconfigure.ImportAutoConfiguration;
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.boot.test.context.TestConfiguration;
 import org.springframework.boot.testcontainers.properties.TestcontainersPropertySourceAutoConfigurationWithSpringBootTestIntegrationTest.TestConfig;
 import org.springframework.context.annotation.Bean;
+import org.springframework.core.env.Environment;
+import org.springframework.test.context.DynamicPropertyRegistrar;
 import org.springframework.test.context.DynamicPropertyRegistry;
 
+import static org.assertj.core.api.Assertions.assertThat;
+
 /**
  * Tests for {@link TestcontainersPropertySourceAutoConfiguration} when combined with
  * {@link SpringBootTest @SpringBootTest}.
  *
  * @author Phillip Webb
+ * @author Andy Wilkinson
  */
-@SpringBootTest(classes = TestConfig.class)
+@SpringBootTest(classes = TestConfig.class,
+		properties = "spring.testcontainers.dynamic-property-registry-injection=allow")
 class TestcontainersPropertySourceAutoConfigurationWithSpringBootTestIntegrationTest {
 
+	@Autowired
+	private Environment environment;
+
 	@Test
-	void injectsRegistry() {
+	void injectsRegistryIntoBeanMethod() {
+		assertThat(this.environment.getProperty("from.bean.method")).isEqualTo("one");
+	}
 
+	@Test
+	void callsRegistrars() {
+		assertThat(this.environment.getProperty("from.registrar")).isEqualTo("two");
 	}
 
 	@TestConfiguration
@@ -47,10 +62,15 @@ static class TestConfig {
 
 		@Bean
 		String example(DynamicPropertyRegistry registry) {
-			registry.add("test", () -> "test");
+			registry.add("from.bean.method", () -> "one");
 			return "Hello";
 		}
 
+		@Bean
+		DynamicPropertyRegistrar propertyRegistrar() {
+			return (registry) -> registry.add("from.registrar", () -> "two");
+		}
+
 	}
 
 }

spring-boot-project/spring-boot-testcontainers/src/main/java/org/springframework/boot/testcontainers/context/ContainerFieldsImporter.java

@@ -19,9 +19,12 @@
 import java.lang.reflect.Field;
 import java.lang.reflect.Modifier;
 import java.util.ArrayList;
+import java.util.HashSet;
 import java.util.List;
+import java.util.Set;
 
 import org.testcontainers.containers.Container;
+import org.testcontainers.lifecycle.Startable;
 
 import org.springframework.beans.factory.support.BeanDefinitionRegistry;
 import org.springframework.boot.autoconfigure.container.ContainerImageMetadata;
@@ -35,12 +38,17 @@
  */
 class ContainerFieldsImporter {
 
-	void registerBeanDefinitions(BeanDefinitionRegistry registry, Class<?> definitionClass) {
+	Set<Startable> registerBeanDefinitions(BeanDefinitionRegistry registry, Class<?> definitionClass) {
+		Set<Startable> importedContainers = new HashSet<>();
 		for (Field field : getContainerFields(definitionClass)) {
 			assertValid(field);
 			Container<?> container = getContainer(field);
+			if (container instanceof Startable startable) {
+				importedContainers.add(startable);
+			}
 			registerBeanDefinition(registry, field, container);
 		}
+		return importedContainers;
 	}
 
 	private List<Field> getContainerFields(Class<?> containersClass) {