Annotation to load SQL before a test @Sql

buildSrc/src/main/groovy/io.micronaut.build.internal.micronaut-test-suite.gradle

@@ -0,0 +1,3 @@
+repositories {
+    mavenCentral()
+}

gradle/libs.versions.toml

@@ -1,6 +1,7 @@
 [versions]
-micronaut-docs = "2.0.0"
 micronaut = "4.1.5"
+micronaut-platform = "4.1.1"
+micronaut-docs = "2.0.0"
 
 groovy = "4.0.11"
 
@@ -18,6 +19,8 @@ graal-svm = "23.0.1"
 
 micronaut-data = "4.1.2"
 micronaut-hibernate-validator = "4.0.2"
+micronaut-logging = "1.1.2"
+micronaut-r2dbc = "5.0.1"
 micronaut-serde = "2.2.4"
 micronaut-spring = "5.0.2"
 micronaut-sql = "5.0.1"
@@ -28,9 +31,11 @@ micronaut-gradle-plugin = "4.1.0"
 [libraries]
 # Core
 micronaut-core = { module = 'io.micronaut:micronaut-core-bom', version.ref = 'micronaut' }
+micronaut-platform = { module = 'io.micronaut.platform:micronaut-platform', version.ref = 'micronaut-platform' }
 
 micronaut-data = { module = "io.micronaut.data:micronaut-data-bom", version.ref = "micronaut-data" }
 micronaut-hibernate-validator = { module = "io.micronaut.beanvalidation:micronaut-hibernate-validator", version.ref = "micronaut-hibernate-validator" }
+micronaut-r2dbc = { module = "io.micronaut.r2dbc:micronaut-r2dbc-bom", version.ref = "micronaut-r2dbc" }
 micronaut-serde = { module = "io.micronaut.serde:micronaut-serde-bom", version.ref = "micronaut-serde" }
 micronaut-spring = { module = "io.micronaut.spring:micronaut-spring-bom", version.ref = "micronaut-spring" }
 micronaut-sql = { module = "io.micronaut.sql:micronaut-sql-bom", version.ref = "micronaut-sql" }

settings.gradle

@@ -19,6 +19,7 @@ micronautBuild {
     importMicronautCatalog("micronaut-spring")
     importMicronautCatalog("micronaut-sql")
     importMicronautCatalog("micronaut-reactor")
+    importMicronautCatalog("micronaut-r2dbc")
 }
 
 rootProject.name = 'test-parent'
@@ -29,3 +30,5 @@ include "test-spock"
 include "test-junit5"
 include "test-kotest5"
 include "test-rest-assured"
+
+include 'test-suite-sql-r2dbc'

src/main/docs/guide/sql.adoc

@@ -0,0 +1,70 @@
+When performing a test with a backing database, often some data is required in the database prior to running the tests.
+As of `micronaut-test` version 4.1.0, there is an annotation api:test.annotation.Sql[].
+
+This annotation can be used to specify the location of one or more sql files to be executed prior to the test.
+The files are executed in the order specified in the annotation.
+
+For example given the two SQL scripts
+
+.test/resources/create.sql
+[source,sql]
+----
+include::test-junit5/src/test/resources/create.sql[]
+----
+
+and
+
+.test/resources/datasource_1_insert.sql
+[source,sql]
+----
+include::test-junit5/src/test/resources/datasource_1_insert.sql[]
+----
+
+We can annotate a test to run these two scripts prior to the test.
+
+[source, java, role="multi-language-sample"]
+----
+include::{junit5tests}/SqlDatasourceTest.java[tags="clazz"]
+----
+
+[source, groovy, role="multi-language-sample"]
+----
+include::{spocktests}/SqlDatasourceSpec.groovy[tags="clazz"]
+----
+
+[source, kotlin, role="multi-language-sample"]
+----
+include::{kotest5tests}/SqlDatasourceTest.kt[tags="clazz"]
+----
+
+<1> Specify the location of the SQL scripts to be executed for a DataSource with the name `default`.
+
+== Named Datasources
+
+If you have multiple datasources configured, you can specify the datasource name to use for the SQL scripts.
+
+[source, java, role="multi-language-sample"]
+----
+include::{junit5tests}/SqlNamedDatasourceTest.java[tags="clazz"]
+----
+
+[source, groovy, role="multi-language-sample"]
+----
+include::{spocktests}/SqlNamedDatasourceSpec.groovy[tags="clazz"]
+----
+
+[source, kotlin, role="multi-language-sample"]
+----
+include::{kotest5tests}/SqlNamedDatasourceTest.kt[tags="clazz"]
+----
+
+<1> Specify the location of the SQL scripts to be executed for a DataSource with the given name.
+
+== R2DBC
+
+For R2DBC, the `Sql` annotation can be used in the same way as for JDBC however it is required to pass the `resourceType` as `ConnectionFactory.class`.
+
+[source,java]
+----
+include::test-suite-sql-r2dbc/src/test/java/io/micronaut/test/r2dbc/MySqlConnectionTest.java[tags="clazz"]
+----

src/main/docs/guide/toc.yml

@@ -5,5 +5,6 @@ spock: Testing with Spock
 junit5: Testing with JUnit 5
 kotest5: Testing with Kotest 5
 restAssured: REST Assured
+sql: Loading SQL before tests
 #spek: Testing with Spek
 repository: Repository

test-core/build.gradle

@@ -6,6 +6,9 @@ plugins {
 dependencies {
     compileOnly(mn.micronaut.http.server)
     compileOnly(libs.junit.jupiter.api)
+    compileOnly(mnData.micronaut.data.connection.jdbc)
+    compileOnly(mnR2dbc.r2dbc.spi)
+    compileOnly(mn.reactor)
 
     api(mn.micronaut.inject)
 

test-core/src/main/java/io/micronaut/test/annotation/Sql.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2017-2023 original 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 io.micronaut.test.annotation;
+
+import io.micronaut.context.annotation.AliasFor;
+import io.micronaut.core.annotation.Experimental;
+
+import javax.sql.DataSource;
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation that can be applied to a test scenario to execute SQL against a test database prior to the sceario being run.
+ *
+ * @since 4.1.0
+ * @author Tim Yates
+ */
+@Target({ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@Experimental
+@Repeatable(Sql.Sqls.class)
+public @interface Sql {
+
+    /**
+     * @return The SQL scripts to execute
+     */
+    @AliasFor(member = "scripts")
+    String[] value() default {};
+
+    /**
+     * The name of the datasource to use for the SQL scripts.
+     *
+     * @return The datasource name
+     */
+    String dataSourceName() default "default";
+
+    /**
+     * @return The SQL scripts to execute
+     */
+    @AliasFor(member = "value")
+    String[] scripts() default {};
+
+    /**
+     * @return The type of the resource to use for the SQL scripts.
+     */
+    Class<?> resourceType() default DataSource.class;
+
+    /**
+     * Wrapper annotation class to allow multiple Sql annotations per test class or method.
+     */
+    @Target({ElementType.TYPE})
+    @Retention(RetentionPolicy.RUNTIME)
+    @Documented
+    @Inherited
+    @interface Sqls {
+
+        /**
+         * @return The SQL scripts to execute
+         */
+        Sql[] value();
+    }
+}
+

test-core/src/main/java/io/micronaut/test/extensions/AbstractMicronautExtension.java

@@ -44,6 +44,7 @@
 import io.micronaut.test.context.TestMethodInvocationContext;
 import io.micronaut.test.support.TestPropertyProvider;
 import io.micronaut.test.support.TestPropertyProviderFactory;
+import io.micronaut.test.support.sql.TestSqlAnnotationHandler;
 
 import java.io.IOException;
 import java.io.InputStream;
@@ -192,6 +193,9 @@ public void afterTestExecution(TestContext testContext) throws Exception {
     @Override
     public void beforeTestClass(TestContext testContext) throws Exception {
         fireListeners(TestExecutionListener::beforeTestClass, testContext, false);
+        if (specDefinition != null && applicationContext != null) {
+            TestSqlAnnotationHandler.handle(specDefinition, applicationContext);
+        }
     }
 
     @Override

test-core/src/main/java/io/micronaut/test/support/sql/ConnectionFactoryHandler.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2017-2023 original 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 io.micronaut.test.support.sql;
+
+import io.micronaut.context.annotation.Requires;
+import io.micronaut.core.annotation.Experimental;
+import io.micronaut.core.annotation.Internal;
+import io.r2dbc.spi.ConnectionFactory;
+import io.r2dbc.spi.Result;
+import jakarta.inject.Singleton;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Mono;
+
+import java.util.List;
+
+/**
+ * Handler for r2dbc {@link ConnectionFactory} instances.
+ *
+ * @since 4.1.0
+ * @author Tim Yates
+ */
+@Singleton
+@Internal
+@Experimental
+@Requires(classes = {ConnectionFactory.class})
+public class ConnectionFactoryHandler implements SqlHandler<ConnectionFactory> {
+
+    private static final Logger LOG = LoggerFactory.getLogger(ConnectionFactoryHandler.class);
+
+    @Override
+    public void handle(ConnectionFactory connectionFactory, String sql) {
+        List<Long> rowsUpdated = Mono.from(connectionFactory.create())
+            .flatMapMany(c -> {
+                if (LOG.isDebugEnabled()) {
+                    LOG.debug("{}: Executing SQL: {}", connectionFactory, sql);
+                }
+                return c.createStatement(sql).execute();
+            })
+            .flatMap(Result::getRowsUpdated)
+            .collectList()
+            .block();
+
+        if (LOG.isDebugEnabled()) {
+            LOG.debug("{}: Updated rows: {}", connectionFactory, rowsUpdated);
+        }
+    }
+}

test-core/src/main/java/io/micronaut/test/support/sql/DataSourceSqlHandler.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2017-2023 original 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 io.micronaut.test.support.sql;
+
+import io.micronaut.context.annotation.Requires;
+import io.micronaut.core.annotation.Experimental;
+import io.micronaut.core.annotation.Internal;
+import jakarta.inject.Singleton;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import javax.sql.DataSource;
+import java.sql.SQLException;
+
+/**
+ * Handler for raw {@link DataSource} instances.
+ *
+ * @since 4.1.0
+ * @author Tim Yates
+ */
+@Singleton
+@Internal
+@Experimental
+@Requires(classes = {DataSource.class})
+public class DataSourceSqlHandler implements SqlHandler<DataSource> {
+
+    private static final Logger LOG = LoggerFactory.getLogger(DataSourceSqlHandler.class);
+
+    @Override
+    public void handle(DataSource dataSource, String sql) {
+        try (var connection = dataSource.getConnection();
+             var statement = connection.createStatement()
+        ) {
+            if (LOG.isDebugEnabled()) {
+                LOG.debug("{}: Executing SQL: {}", dataSource, sql);
+            }
+            statement.execute(sql);
+        } catch (SQLException sqlException) {
+            throw new SqlAnnotationHandlingException(sqlException);
+        }
+    }
+}