Introduce class-level execution phases for @⁠Sql

This commit introduces BEFORE_TEST_CLASS and AFTER_TEST_CLASS execution
phases for @⁠Sql.

See gh-27285

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

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2002-2023 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 javax.sql.DataSource;
+
+import org.junit.jupiter.api.Order;
+import org.junit.jupiter.api.Test;
+
+import org.springframework.core.Ordered;
+import org.springframework.jdbc.BadSqlGrammarException;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.test.annotation.Commit;
+import org.springframework.test.annotation.DirtiesContext;
+import org.springframework.test.context.TestContext;
+import org.springframework.test.context.TestExecutionListener;
+import org.springframework.test.context.TestExecutionListeners;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+import org.springframework.test.context.transaction.TestContextTransactionUtils;
+
+import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+
+/**
+ * Verifies that {@link Sql @Sql} with {@link Sql.ExecutionPhase#AFTER_TEST_CLASS} is run after all tests in the class
+ * have been run.
+ *
+ * @author Andreas Ahlenstorf
+ * @since 6.1
+ */
+@SpringJUnitConfig(PopulatedSchemaDatabaseConfig.class)
+@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS)
+@Sql(value = {"drop-schema.sql"}, executionPhase = Sql.ExecutionPhase.AFTER_TEST_CLASS)
+@TestExecutionListeners(
+		value = AfterTestClassSqlScriptsTests.VerifyTestExecutionListener.class,
+		mergeMode = TestExecutionListeners.MergeMode.MERGE_WITH_DEFAULTS
+)
+class AfterTestClassSqlScriptsTests extends AbstractTransactionalTests {
+
+	@Test
+	@Order(1)
+	@Sql(scripts = "data-add-catbert.sql")
+	@Commit
+	void databaseHasBeenInitialized() {
+		assertUsers("Catbert");
+	}
+
+	@Test
+	@Order(2)
+	@Sql(scripts = "data-add-dogbert.sql")
+	@Commit
+	void databaseIsNotWipedBetweenTests() {
+		assertUsers("Catbert", "Dogbert");
+	}
+
+	static class VerifyTestExecutionListener implements TestExecutionListener, Ordered {
+
+		@Override
+		public void afterTestClass(TestContext testContext) throws Exception {
+			DataSource dataSource = TestContextTransactionUtils.retrieveDataSource(testContext, null);
+			JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource);
+
+			assertThatExceptionOfType(BadSqlGrammarException.class)
+					.isThrownBy(() -> jdbcTemplate.queryForList("SELECT name FROM user", String.class));
+		}
+
+		@Override
+		public int getOrder() {
+			// Must run before DirtiesContextTestExecutionListener. Otherwise, the old data source will be removed and
+			// replaced with a new one.
+			return 3001;
+		}
+	}
+}

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

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2002-2023 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.Test;
+
+import org.springframework.test.annotation.DirtiesContext;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+
+import static org.springframework.test.context.jdbc.SqlMergeMode.MergeMode.MERGE;
+import static org.springframework.test.context.jdbc.SqlMergeMode.MergeMode.OVERRIDE;
+
+/**
+ * Verifies that {@link Sql @Sql} with {@link Sql.ExecutionPhase#BEFORE_TEST_CLASS} is run before all tests in the class
+ * have been run.
+ *
+ * @author Andreas Ahlenstorf
+ * @since 6.1
+ */
+@SpringJUnitConfig(classes = EmptyDatabaseConfig.class)
+@DirtiesContext
+@Sql(value = {"schema.sql", "data-add-catbert.sql"}, executionPhase = Sql.ExecutionPhase.BEFORE_TEST_CLASS)
+class BeforeTestClassSqlScriptsTests extends AbstractTransactionalTests {
+
+	@Test
+	void classLevelScriptsHaveBeenRun() {
+		assertUsers("Catbert");
+	}
+
+	@Test
+	@Sql("data-add-dogbert.sql")
+	@SqlMergeMode(MERGE)
+	void mergeDoesNotAffectClassLevelPhase() {
+		assertUsers("Catbert", "Dogbert");
+	}
+
+	@Test
+	@Sql({"data-add-dogbert.sql"})
+	@SqlMergeMode(OVERRIDE)
+	void overrideDoesNotAffectClassLevelPhase() {
+		assertUsers("Dogbert", "Catbert");
+	}
+
+}

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

@@ -25,6 +25,7 @@ import org.springframework.test.context.TestContext;
 import org.springframework.test.context.jdbc.SqlConfig.TransactionMode;
 
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.assertj.core.api.Assertions.assertThatIllegalArgumentException;
 import static org.assertj.core.api.Assertions.assertThatIllegalStateException;
 import static org.mockito.ArgumentMatchers.anyString;
 import static org.mockito.BDDMockito.given;
@@ -34,6 +35,7 @@ import static org.mockito.Mockito.mock;
  * Unit tests for {@link SqlScriptsTestExecutionListener}.
  *
  * @author Sam Brannen
+ * @author Andreas Ahlenstorf
  * @since 4.1
  */
 class SqlScriptsTestExecutionListenerTests {
@@ -56,6 +58,7 @@ class SqlScriptsTestExecutionListenerTests {
 	void missingValueAndScriptsAndStatementsAtMethodLevel() throws Exception {
 		Class<?> clazz = MissingValueAndScriptsAndStatementsAtMethodLevel.class;
 		BDDMockito.<Class<?>> given(testContext.getTestClass()).willReturn(clazz);
+		given(testContext.hasTestMethod()).willReturn(true);
 		given(testContext.getTestMethod()).willReturn(clazz.getDeclaredMethod("foo"));
 
 		assertExceptionContains(clazz.getSimpleName() + ".foo" + ".sql");
@@ -102,6 +105,30 @@ class SqlScriptsTestExecutionListenerTests {
 		assertExceptionContains("supply at least a DataSource or PlatformTransactionManager");
 	}
 
+	@Test
+	void beforeTestClassOnMethod() throws Exception {
+		Class<?> clazz = ClassLevelExecutionPhaseOnMethod.class;
+		BDDMockito.<Class<?>> given(testContext.getTestClass()).willReturn(clazz);
+		given(testContext.hasTestMethod()).willReturn(true);
+		given(testContext.getTestMethod()).willReturn(clazz.getDeclaredMethod("beforeTestClass"));
+
+		assertThatIllegalArgumentException()
+				.isThrownBy(() -> listener.beforeTestMethod(testContext))
+				.withMessage("BEFORE_TEST_CLASS cannot be used on methods");
+	}
+
+	@Test
+	void afterTestClassOnMethod() throws Exception {
+		Class<?> clazz = ClassLevelExecutionPhaseOnMethod.class;
+		BDDMockito.<Class<?>> given(testContext.getTestClass()).willReturn(clazz);
+		given(testContext.hasTestMethod()).willReturn(true);
+		given(testContext.getTestMethod()).willReturn(clazz.getDeclaredMethod("afterTestClass"));
+
+		assertThatIllegalArgumentException()
+				.isThrownBy(() -> listener.beforeTestMethod(testContext))
+				.withMessage("AFTER_TEST_CLASS cannot be used on methods");
+	}
+
 	private void assertExceptionContains(String msg) throws Exception {
 		assertThatIllegalStateException().isThrownBy(() ->
 				listener.beforeTestMethod(testContext))
@@ -146,4 +173,14 @@ class SqlScriptsTestExecutionListenerTests {
 		}
 	}
 
+	static class ClassLevelExecutionPhaseOnMethod {
+
+		@Sql(scripts = "foo.sql", executionPhase = Sql.ExecutionPhase.BEFORE_TEST_CLASS)
+		public void beforeTestClass() {
+		}
+
+		@Sql(scripts = "foo.sql", executionPhase = Sql.ExecutionPhase.AFTER_TEST_CLASS)
+		public void afterTestClass() {
+		}
+	}
 }