Skip to content

Commit b1a7161

Browse files
committed
Document @⁠Sql class-level execution phase support in the reference manual
Closes gh-31377
1 parent 332de60 commit b1a7161

File tree

1 file changed

+67
-7
lines changed

1 file changed

+67
-7
lines changed

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

Lines changed: 67 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -95,13 +95,22 @@ In addition to the aforementioned mechanisms for running SQL scripts programmati
9595
you can declaratively configure SQL scripts in the Spring TestContext Framework.
9696
Specifically, you can declare the `@Sql` annotation on a test class or test method to
9797
configure individual SQL statements or the resource paths to SQL scripts that should be
98-
run against a given database before or after an integration test method. Support for
99-
`@Sql` is provided by the `SqlScriptsTestExecutionListener`, which is enabled by default.
100-
101-
NOTE: Method-level `@Sql` declarations override class-level declarations by default. As
102-
of Spring Framework 5.2, however, this behavior may be configured per test class or per
103-
test method via `@SqlMergeMode`. See
104-
xref:testing/testcontext-framework/executing-sql.adoc#testcontext-executing-sql-declaratively-script-merging[Merging and Overriding Configuration with `@SqlMergeMode`] for further details.
98+
run against a given database before or after an integration test class or test method.
99+
Support for `@Sql` is provided by the `SqlScriptsTestExecutionListener`, which is enabled
100+
by default.
101+
102+
[NOTE]
103+
====
104+
Method-level `@Sql` declarations override class-level declarations by default, but this
105+
behavior may be configured per test class or per test method via `@SqlMergeMode`. See
106+
xref:testing/testcontext-framework/executing-sql.adoc#testcontext-executing-sql-declaratively-script-merging[Merging and Overriding Configuration with `@SqlMergeMode`]
107+
for further details.
108+
109+
However, this does not apply to class-level declarations configured for the
110+
`BEFORE_TEST_CLASS` or `AFTER_TEST_CLASS` execution phases. Such declarations cannot be
111+
overridden, and the corresponding scripts and statements will be executed once per class
112+
in addition to any method-level scripts and statements.
113+
====
105114

106115
[[testcontext-executing-sql-declaratively-script-resources]]
107116
=== Path Resource Semantics
@@ -300,6 +309,57 @@ Kotlin::
300309
NOTE: `ISOLATED` and `AFTER_TEST_METHOD` are statically imported from
301310
`Sql.TransactionMode` and `Sql.ExecutionPhase`, respectively.
302311

312+
As of Spring Framework 6.1, it is possible to run a particular set of scripts before or
313+
after the test class by setting the `executionPhase` attribute in a class-level `@Sql`
314+
declaration to `BEFORE_TEST_CLASS` or `AFTER_TEST_CLASS`, as the following example shows:
315+
316+
[tabs]
317+
======
318+
Java::
319+
+
320+
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
321+
----
322+
@SpringJUnitConfig
323+
@Sql(scripts = "/test-schema.sql", executionPhase = BEFORE_TEST_CLASS)
324+
class DatabaseTests {
325+
326+
@Test
327+
void emptySchemaTest() {
328+
// run code that uses the test schema without any test data
329+
}
330+
331+
@Test
332+
@Sql("/test-user-data.sql")
333+
void userTest() {
334+
// run code that uses the test schema and test data
335+
}
336+
}
337+
----
338+
339+
Kotlin::
340+
+
341+
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
342+
----
343+
@SpringJUnitConfig
344+
@Sql("/test-schema.sql", executionPhase = BEFORE_TEST_CLASS)
345+
class DatabaseTests {
346+
347+
@Test
348+
fun emptySchemaTest() {
349+
// run code that uses the test schema without any test data
350+
}
351+
352+
@Test
353+
@Sql("/test-user-data.sql")
354+
fun userTest() {
355+
// run code that uses the test schema and test data
356+
}
357+
}
358+
----
359+
======
360+
361+
NOTE: `BEFORE_TEST_CLASS` is statically imported from `Sql.ExecutionPhase`.
362+
303363
[[testcontext-executing-sql-declaratively-script-configuration]]
304364
=== Script Configuration with `@SqlConfig`
305365

0 commit comments

Comments
 (0)