Support property placeholders in @⁠Sql script paths

Prior to this commit, paths configured via the scripts attribute in
@⁠Sql were required to be final paths without dynamic placeholders;
however, being able to make script paths dependent on the current
environment can be useful in certain testing scenarios.

This commit introduces support for property placeholders (${...}) in
@⁠Sql script paths which will be replaced by properties available in
the Environment of the test's ApplicationContext.

Closes gh-33114

framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc

@@ -122,6 +122,9 @@ classpath resource (for example, `"/org/example/schema.sql"`). A path that refer
 URL (for example, a path prefixed with `classpath:`, `file:`, `http:`) is loaded by using
 the specified resource protocol.
 
+As of Spring Framework 6.2, paths may contain property placeholders (`${...}`) that will
+be replaced by properties stored in the `Environment` of the test's `ApplicationContext`.
+
 The following example shows how to use `@Sql` at the class level and at the method level
 within a JUnit Jupiter based integration test class:
 

spring-test/src/main/java/org/springframework/test/context/jdbc/Sql.java

@@ -115,6 +115,10 @@ public @interface Sql {
 	 * {@link org.springframework.util.ResourceUtils#CLASSPATH_URL_PREFIX classpath:},
 	 * {@link org.springframework.util.ResourceUtils#FILE_URL_PREFIX file:},
 	 * {@code http:}, etc.) will be loaded using the specified resource protocol.
+	 * <p>As of Spring Framework 6.2, paths may contain property placeholders
+	 * (<code>${...}</code>) that will be replaced by properties stored in the
+	 * {@link org.springframework.core.env.Environment Environment} of the test's
+	 * {@code ApplicationContext}.
 	 * <h4>Default Script Detection</h4>
 	 * <p>If no SQL scripts or {@link #statements} are specified, an attempt will
 	 * be made to detect a <em>default</em> script depending on where this
@@ -131,6 +135,7 @@ public @interface Sql {
 	 * </ul>
 	 * @see #value
 	 * @see #statements
+	 * @see org.springframework.core.env.Environment#resolveRequiredPlaceholders(String)
 	 */
 	@AliasFor("value")
 	String[] scripts() default {};

spring-test/src/main/java/org/springframework/test/context/jdbc/SqlScriptsTestExecutionListener.java

@@ -308,8 +308,9 @@ public class SqlScriptsTestExecutionListener extends AbstractTestExecutionListen
 		Method testMethod = (methodLevel ? testContext.getTestMethod() : null);
 
 		String[] scripts = getScripts(sql, testContext.getTestClass(), testMethod, classLevel);
+		ApplicationContext applicationContext = testContext.getApplicationContext();
 		List<Resource> scriptResources = TestContextResourceUtils.convertToResourceList(
-				testContext.getApplicationContext(), scripts);
+				applicationContext, applicationContext.getEnvironment(), scripts);
 		for (String stmt : sql.statements()) {
 			if (StringUtils.hasText(stmt)) {
 				stmt = stmt.trim();

spring-test/src/main/java/org/springframework/test/context/util/TestContextResourceUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2022 the original author or authors.
+ * Copyright 2002-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.
@@ -23,6 +23,7 @@ import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
+import org.springframework.core.env.Environment;
 import org.springframework.core.io.Resource;
 import org.springframework.core.io.ResourceLoader;
 import org.springframework.core.io.support.ResourcePatternUtils;
@@ -145,6 +146,28 @@ public abstract class TestContextResourceUtils {
 		return stream(resourceLoader, paths).collect(Collectors.toCollection(ArrayList::new));
 	}
 
+	/**
+	 * Convert the supplied paths to a list of {@link Resource} handles using the given
+	 * {@link ResourceLoader} and {@link Environment}.
+	 * @param resourceLoader the {@code ResourceLoader} to use to convert the paths
+	 * @param environment the {@code Environment} to use to resolve property placeholders
+	 * in the paths
+	 * @param paths the paths to be converted
+	 * @return a new, mutable list of resources
+	 * @since 6.2
+	 * @see #convertToResources(ResourceLoader, String...)
+	 * @see #convertToClasspathResourcePaths
+	 * @see Environment#resolveRequiredPlaceholders(String)
+	 */
+	public static List<Resource> convertToResourceList(
+			ResourceLoader resourceLoader, Environment environment, String... paths) {
+
+		return Arrays.stream(paths)
+				.map(environment::resolveRequiredPlaceholders)
+				.map(resourceLoader::getResource)
+				.collect(Collectors.toCollection(ArrayList::new));
+	}
+
 	private static Stream<Resource> stream(ResourceLoader resourceLoader, String... paths) {
 		return Arrays.stream(paths).map(resourceLoader::getResource);
 	}

spring-test/src/test/java/org/springframework/test/context/jdbc/PropertyPlaceholderSqlScriptsTests.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2002-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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.test.context.jdbc;
+
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+
+import org.springframework.test.annotation.DirtiesContext;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.TestPropertySource;
+
+/**
+ * Integration tests that verify support for property placeholders in SQL script locations.
+ *
+ * @author Sam Brannen
+ * @since 6.2
+ */
+@ContextConfiguration(classes = PopulatedSchemaDatabaseConfig.class)
+class PropertyPlaceholderSqlScriptsTests {
+
+	private static final String SCRIPT_LOCATION = "classpath:org/springframework/test/context/jdbc/${vendor}/data.sql";
+
+	@Nested
+	@TestPropertySource(properties = "vendor = db1")
+	@DirtiesContext
+	class DatabaseOneTests extends AbstractTransactionalTests {
+
+		@Test
+		@Sql(SCRIPT_LOCATION)
+		void placeholderIsResolvedInScriptLocation() {
+			assertUsers("Dilbert 1");
+		}
+	}
+
+	@Nested
+	@TestPropertySource(properties = "vendor = db2")
+	@DirtiesContext
+	class DatabaseTwoTests extends AbstractTransactionalTests {
+
+		@Test
+		@Sql(SCRIPT_LOCATION)
+		void placeholderIsResolvedInScriptLocation() {
+			assertUsers("Dilbert 2");
+		}
+	}
+
+}

spring-test/src/test/java/org/springframework/test/context/jdbc/SqlScriptsTestExecutionListenerTests.java

@@ -21,6 +21,7 @@ import org.mockito.BDDMockito;
 
 import org.springframework.context.ApplicationContext;
 import org.springframework.core.annotation.AnnotationConfigurationException;
+import org.springframework.mock.env.MockEnvironment;
 import org.springframework.test.context.TestContext;
 
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
@@ -84,6 +85,7 @@ class SqlScriptsTestExecutionListenerTests {
 		ApplicationContext ctx = mock();
 		given(ctx.getResource(anyString())).willReturn(mock());
 		given(ctx.getAutowireCapableBeanFactory()).willReturn(mock());
+		given(ctx.getEnvironment()).willReturn(new MockEnvironment());
 
 		Class<?> clazz = IsolatedWithoutTxMgr.class;
 		BDDMockito.<Class<?>> given(testContext.getTestClass()).willReturn(clazz);
@@ -98,6 +100,7 @@ class SqlScriptsTestExecutionListenerTests {
 		ApplicationContext ctx = mock();
 		given(ctx.getResource(anyString())).willReturn(mock());
 		given(ctx.getAutowireCapableBeanFactory()).willReturn(mock());
+		given(ctx.getEnvironment()).willReturn(new MockEnvironment());
 
 		Class<?> clazz = MissingDataSourceAndTxMgr.class;
 		BDDMockito.<Class<?>> given(testContext.getTestClass()).willReturn(clazz);

spring-test/src/test/resources/org/springframework/test/context/jdbc/db1/data.sql

@@ -0,0 +1 @@
+INSERT INTO user VALUES('Dilbert 1');

spring-test/src/test/resources/org/springframework/test/context/jdbc/db2/data.sql

@@ -0,0 +1 @@
+INSERT INTO user VALUES('Dilbert 2');