From de828e9764ecd6bfac05df5c94db8536b2e540d9 Mon Sep 17 00:00:00 2001 From: Sam Brannen <104798+sbrannen@users.noreply.github.com> Date: Fri, 1 Mar 2024 14:37:31 +0100 Subject: [PATCH] =?UTF-8?q?Improve=20documentation=20for=20@=E2=81=A0Sql?= =?UTF-8?q?=20execution=20phases=20regarding=20lifecycle?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes gh-32343 --- .../test/context/jdbc/Sql.java | 49 +++++++++++++++++-- 1 file changed, 44 insertions(+), 5 deletions(-) diff --git a/spring-test/src/main/java/org/springframework/test/context/jdbc/Sql.java b/spring-test/src/main/java/org/springframework/test/context/jdbc/Sql.java index 4f4b3a86384..5b4642637dd 100644 --- a/spring-test/src/main/java/org/springframework/test/context/jdbc/Sql.java +++ b/spring-test/src/main/java/org/springframework/test/context/jdbc/Sql.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2023 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. @@ -171,28 +171,67 @@ public @interface Sql { enum ExecutionPhase { /** - * The configured SQL scripts and statements will be executed - * once per test class before any test method is run. + * The configured SQL scripts and statements will be executed once per + * test class before any test method is run. + *

Specifically, the configured SQL scripts and statements will be + * executed prior to any before class lifecycle methods of a + * particular testing framework — for example, methods annotated + * with JUnit Jupiter's {@link org.junit.jupiter.api.BeforeAll @BeforeAll} + * annotation. + *

NOTE: Configuring {@code BEFORE_TEST_CLASS} as the execution phase + * causes the test's {@code ApplicationContext} to be eagerly loaded + * during test class initialization which can potentially result in + * undesired side effects. For example, + * {@link org.springframework.test.context.DynamicPropertySource @DynamicPropertySource} + * methods will be invoked before {@code @BeforeAll} methods when using + * {@code BEFORE_TEST_CLASS}. * @since 6.1 + * @see #AFTER_TEST_CLASS + * @see #BEFORE_TEST_METHOD + * @see #AFTER_TEST_METHOD */ BEFORE_TEST_CLASS, /** - * The configured SQL scripts and statements will be executed - * once per test class after all test methods have run. + * The configured SQL scripts and statements will be executed once per + * test class after all test methods have run. + *

Specifically, the configured SQL scripts and statements will be + * executed after any after class lifecycle methods of a + * particular testing framework — for example, methods annotated + * with JUnit Jupiter's {@link org.junit.jupiter.api.AfterAll @AfterAll} + * annotation. * @since 6.1 + * @see #BEFORE_TEST_CLASS + * @see #BEFORE_TEST_METHOD + * @see #AFTER_TEST_METHOD */ AFTER_TEST_CLASS, /** * The configured SQL scripts and statements will be executed * before the corresponding test method. + *

Specifically, the configured SQL scripts and statements will be + * executed prior to any before test lifecycle methods of a + * particular testing framework — for example, methods annotated + * with JUnit Jupiter's {@link org.junit.jupiter.api.BeforeEach @BeforeEach} + * annotation. + * @see #BEFORE_TEST_CLASS + * @see #AFTER_TEST_CLASS + * @see #AFTER_TEST_METHOD */ BEFORE_TEST_METHOD, /** * The configured SQL scripts and statements will be executed * after the corresponding test method. + *

Specifically, the configured SQL scripts and statements will be + * executed after any after test lifecycle methods of a + * particular testing framework — for example, methods annotated + * with JUnit Jupiter's {@link org.junit.jupiter.api.AfterEach @AfterEach} + * annotation. + * @see #BEFORE_TEST_CLASS + * @see #AFTER_TEST_CLASS + * @see #BEFORE_TEST_METHOD */ AFTER_TEST_METHOD }