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 = "4.1.1"
+micronaut-core = "4.1.5"
 micronaut-docs = "2.0.0"
-micronaut = "4.1.5"
 
 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"
@@ -27,10 +30,12 @@ micronaut-gradle-plugin = "4.1.0"
 
 [libraries]
 # Core
-micronaut-core = { module = 'io.micronaut:micronaut-core-bom', version.ref = 'micronaut' }
+micronaut-core = { module = 'io.micronaut:micronaut-core-bom', version.ref = 'micronaut-core' }
+micronaut-platform = { module = 'io.micronaut.platform:micronaut-platform', version.ref = 'micronaut' }
 
 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,41 @@
+:icons: font
+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> The annotation is used to specify the location of the SQL scripts to be executed. (The default datasource name is `default`, but this can be overriden by setting the `datasourceName` property for the annotation)

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/TestSqlAnnotationHandler.java

@@ -0,0 +1,113 @@
+/*
+ * 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.ApplicationContext;
+import io.micronaut.core.annotation.AnnotationValue;
+import io.micronaut.core.annotation.Experimental;
+import io.micronaut.core.io.ResourceLoader;
+import io.micronaut.inject.BeanDefinition;
+import io.micronaut.inject.qualifiers.Qualifiers;
+import io.micronaut.test.annotation.Sql;
+import io.micronaut.test.support.sql.processor.SqlScriptProcessor;
+import io.micronaut.test.support.sql.resolver.DataSourceResolver;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URL;
+import java.nio.charset.StandardCharsets;
+import java.sql.SQLException;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * Static helper class to handle {@link Sql} annotations.
+ *
+ * @since 4.1.0
+ * @author Tim Yates
+ */
+@Experimental
+public final class TestSqlAnnotationHandler {
+
+    private static final Logger LOG = LoggerFactory.getLogger(TestSqlAnnotationHandler.class);
+
+    private TestSqlAnnotationHandler() {
+    }
+
+    /**
+     * Given a spec definition and application context, find and process all {@link Sql} annotations.
+     *
+     * @param specDefinition The test class
+     * @param applicationContext The application context
+     * @throws SQLException If an error occurs executing the SQL
+     * @throws IOException If an error occurs reading the SQL
+     */
+    public static void handle(BeanDefinition<?> specDefinition, ApplicationContext applicationContext) throws SQLException, IOException {
+        ResourceLoader resourceLoader = applicationContext.getBean(ResourceLoader.class);
+
+        var compositeDataSourceHandler = applicationContext.getBean(DataSourceResolver.class);
+
+        Optional<List<AnnotationValue<Sql>>> sqlAnnotations = specDefinition
+            .findAnnotation(Sql.Sqls.class)
+            .map(s -> s.getAnnotations("value", Sql.class));
+
+        if (sqlAnnotations.isPresent()) {
+            for (var sql : sqlAnnotations.get()) {
+                String datasourceName = sql.getRequiredValue("datasourceName", String.class);
+                Class<?> dataSourceType = sql.getRequiredValue("resourceType", Class.class);
+
+                Object bean = applicationContext.getBean(dataSourceType, Qualifiers.byName(datasourceName));
+
+                if (LOG.isTraceEnabled()) {
+                    LOG.trace("Looking for resource of type {} with name {}", dataSourceType, datasourceName);
+                }
+
+                Optional<? extends SqlScriptProcessor> resolve = compositeDataSourceHandler.resolve(bean);
+
+                if (resolve.isPresent()) {
+                    handleScript(
+                        resourceLoader,
+                        Arrays.asList(sql.stringValues("value")),
+                        resolve.get()
+                    );
+                } else {
+                    LOG.warn("Could not resolve data source: {}", datasourceName);
+                }
+            }
+        }
+    }
+
+    private static void handleScript(
+        ResourceLoader loader,
+        List<String> scripts,
+        SqlScriptProcessor processor
+    ) throws IOException, SQLException {
+        for (String script : scripts) {
+            Optional<URL> resource = loader.getResource(script);
+            if (resource.isPresent()) {
+                try (InputStream in = resource.get().openStream()) {
+                    String scriptBody = new String(in.readAllBytes(), StandardCharsets.UTF_8);
+                    processor.process(scriptBody);
+                }
+            } else {
+                LOG.warn("Could not find SQL script: {}", script);
+            }
+        }
+    }
+}

test-core/src/main/java/io/micronaut/test/support/sql/processor/R2DBCConnectionFactoryProcessor.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.processor;
+
+import io.micronaut.core.annotation.Experimental;
+import io.micronaut.core.annotation.NonNull;
+import io.r2dbc.spi.ConnectionFactory;
+import io.r2dbc.spi.Result;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Mono;
+
+import java.util.List;
+
+/**
+ * Processes SQL scripts against an R2DBC {@link ConnectionFactory}.
+ *
+ * @since 4.1.0
+ * @author Tim Yates
+ */
+@Experimental
+public class R2DBCConnectionFactoryProcessor implements SqlScriptProcessor {
+
+    private static final Logger LOG = LoggerFactory.getLogger(R2DBCConnectionFactoryProcessor.class);
+    private final ConnectionFactory connectionFactory;
+
+    public R2DBCConnectionFactoryProcessor(ConnectionFactory connectionFactory) {
+        this.connectionFactory = connectionFactory;
+    }
+
+    @Override
+    public void process(@NonNull 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);
+        }
+    }
+}