refactor(springboot-test-support): added @FlamingockSpringBootTest annotation

Author: dieppa

platform-plugins/flamingock-springboot-integration/src/main/java/io/flamingock/springboot/FlamingockAutoConfiguration.java

@@ -48,15 +48,15 @@ public class FlamingockAutoConfiguration {
     @ConditionalOnExpression("'${flamingock.runner-type:ApplicationRunner}'.toLowerCase().equals('applicationrunner')")
     public ApplicationRunner applicationRunner(RunnerBuilder runnerBuilder,
                                                @Value("${flamingock.autorun:true}") boolean autoRun) {
-        return SpringbootUtil.toApplicationRunner(runnerBuilder.build(), autoRun);
+        return SpringbootUtil.toApplicationRunner(runnerBuilder, autoRun);
     }
 
     @Bean("flamingock-runner")
     @Profile(Constants.NON_CLI_PROFILE)
     @ConditionalOnExpression("'${flamingock.runner-type:null}'.toLowerCase().equals('initializingbean')")
     public InitializingBean initializingBeanRunner(RunnerBuilder runnerBuilder,
                                                    @Value("${flamingock.autorun:true}") boolean autoRun) {
-        return SpringbootUtil.toInitializingBean(runnerBuilder.build(), autoRun);
+        return SpringbootUtil.toInitializingBean(runnerBuilder, autoRun);
     }
 
     @Bean("flamingock-builder")

platform-plugins/flamingock-springboot-integration/src/main/java/io/flamingock/springboot/SpringbootUtil.java

@@ -16,6 +16,7 @@
 package io.flamingock.springboot;
 
 import io.flamingock.internal.core.runner.Runner;
+import io.flamingock.internal.core.runner.RunnerBuilder;
 import io.flamingock.internal.util.log.FlamingockLoggerFactory;
 import org.slf4j.Logger;
 import org.springframework.beans.factory.InitializingBean;
@@ -28,16 +29,17 @@ public final class SpringbootUtil {
     private SpringbootUtil() {
     }
 
-    public static InitializingBean toInitializingBean(Runner runner, boolean autoRun) {
-        return () -> runIfApply(runner, autoRun);
+    public static InitializingBean toInitializingBean(RunnerBuilder runnerBuilder, boolean autoRun) {
+        return () -> runIfApply(runnerBuilder, autoRun);
     }
 
-    public static ApplicationRunner toApplicationRunner(Runner runner, boolean autoRun) {
-        return args -> runIfApply(runner, autoRun);
+    public static ApplicationRunner toApplicationRunner(RunnerBuilder runnerBuilder, boolean autoRun) {
+        return args -> runIfApply(runnerBuilder, autoRun);
     }
 
-    private static void runIfApply(Runner runner, boolean autoRun) {
+    private static void runIfApply(RunnerBuilder runnerBuilder, boolean autoRun) {
         if(autoRun) {
+            Runner runner = runnerBuilder.build();
             runner.run();
         }  else {
             logger.info(

platform-plugins/flamingock-springboot-test-support/build.gradle.kts

@@ -10,6 +10,10 @@ dependencies {
     compileOnly("org.springframework.boot:spring-boot-autoconfigure:${springBootVersion}")
     annotationProcessor("org.springframework.boot:spring-boot-configuration-processor:${springBootVersion}")
 
+    // Required for @FlamingockSpringBootTest annotation
+    implementation("org.springframework.boot:spring-boot-test:${springBootVersion}")
+    implementation("org.springframework:spring-test:${springFrameworkVersion}")
+
 
     testImplementation(platform("org.springframework.boot:spring-boot-dependencies:${springBootVersion}"))
 

platform-plugins/flamingock-springboot-test-support/src/main/java/io/flamingock/springboot/testsupport/FlamingockSpringBootTest.java

@@ -0,0 +1,89 @@
+/*
+ * Copyright 2025 Flamingock (https://www.flamingock.io)
+ *
+ * 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
+ *
+ *     http://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.flamingock.springboot.testsupport;
+
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.core.annotation.AliasFor;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation for Flamingock integration tests with Spring Boot.
+ *
+ * <p>This annotation configures a Spring Boot test context with Flamingock's
+ * auto-run disabled ({@code flamingock.autorun=false}), allowing tests to
+ * manually control when Flamingock executes.</p>
+ *
+ * <p><strong>Usage:</strong></p>
+ * <pre>{@code
+ * @ExtendWith(SpringExtension.class)  // Required for Spring Boot < 2.1
+ * @FlamingockSpringBootTest(classes = {MyApplication.class, TestConfig.class})
+ * class MyFlamingockTest {
+ *
+ *     @Autowired
+ *     private AbstractChangeRunnerBuilder<?, ?> flamingockBuilder;
+ *
+ *     @Test
+ *     void testMigration() {
+ *         // Setup preconditions...
+ *
+ *         // Execute Flamingock manually
+ *         flamingockBuilder.build().run();
+ *
+ *         // Verify results...
+ *     }
+ * }
+ * }</pre>
+ *
+ * <p><strong>Note:</strong> For Spring Boot 2.0.x, you must add
+ * {@code @ExtendWith(SpringExtension.class)} to your test class.
+ * Spring Boot 2.1+ does not require this.</p>
+ *
+ * @see SpringBootTest
+ * @since 1.0
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@SpringBootTest(properties = "flamingock.autorun=false")
+public @interface FlamingockSpringBootTest {
+
+    /**
+     * Alias for {@link SpringBootTest#classes()}.
+     * The component classes to use for loading an ApplicationContext.
+     *
+     * @return the component classes
+     * @see SpringBootTest#classes()
+     */
+    @AliasFor(annotation = SpringBootTest.class, attribute = "classes")
+    Class<?>[] classes() default {};
+
+    /**
+     * Alias for {@link SpringBootTest#webEnvironment()}.
+     * The type of web environment to create when applicable.
+     *
+     * @return the web environment mode
+     * @see SpringBootTest#webEnvironment()
+     */
+    @AliasFor(annotation = SpringBootTest.class, attribute = "webEnvironment")
+    SpringBootTest.WebEnvironment webEnvironment() default SpringBootTest.WebEnvironment.MOCK;
+}

platform-plugins/flamingock-springboot-test-support/src/test/java/io/flamingock/springboot/testsupport/SpringBootFlamingockIntegrationTest.java

@@ -16,11 +16,11 @@
 package io.flamingock.springboot.testsupport;
 
 import io.flamingock.internal.common.core.audit.AuditEntry;
+import io.flamingock.internal.core.builder.AbstractChangeRunnerBuilder;
 import io.flamingock.internal.core.store.CommunityAuditStore;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.context.ApplicationContext;
 import org.springframework.test.context.junit.jupiter.SpringExtension;
 
@@ -30,12 +30,17 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 /**
- * Integration test that verifies Flamingock Spring Boot integration works correctly.
- * This test runs a real Spring Boot application with @EnableFlamingock and verifies
- * that the change is executed and recorded in the audit store.
+ * Integration test that verifies @FlamingockSpringBootTest annotation works correctly.
+ *
+ * <p>This test demonstrates that:</p>
+ * <ul>
+ *   <li>Flamingock does NOT auto-run on startup (flamingock.autorun=false)</li>
+ *   <li>The builder can be injected and executed manually</li>
+ *   <li>Changes are applied when executed manually</li>
+ * </ul>
  */
-@ExtendWith(SpringExtension.class)
-@SpringBootTest(classes = {TestApplication.class, FlamingockTestConfiguration.class})
+@ExtendWith(SpringExtension.class)  // Required for Spring Boot 2.0.x
+@FlamingockSpringBootTest(classes = {TestApplication.class, FlamingockTestConfiguration.class})
 class SpringBootFlamingockIntegrationTest {
 
     @Autowired
@@ -44,31 +49,41 @@ class SpringBootFlamingockIntegrationTest {
     @Autowired
     private CommunityAuditStore auditStore;
 
+    @Autowired
+    private AbstractChangeRunnerBuilder<?, ?> flamingockBuilder;
+
     @Test
     void contextLoads() {
         assertThat(context).isNotNull();
     }
 
     @Test
-    void flamingockRunnerBeanExists() {
-        assertThat(context.containsBean("flamingock-runner")).isTrue();
+    void flamingockBuilderBeanExists() {
+        assertThat(context.containsBean("flamingock-builder")).isTrue();
     }
 
     @Test
-    void flamingockBuilderBeanExists() {
-        assertThat(context.containsBean("flamingock-builder")).isTrue();
+    void flamingockRunnerBeanExists() {
+        assertThat(context.containsBean("flamingock-runner")).isTrue();
     }
 
     @Test
-    void changeWasApplied() {
-        // Verify that the change was executed by checking the audit store
-        List<AuditEntry> entries = auditStore.getPersistence()
+    void manualExecutionWorks() {
+        // This test implicitly verifies that Flamingock did NOT auto-run:
+        // If it had auto-run, the change would already be applied and we'd get a different result
+        // Execute Flamingock manually
+        flamingockBuilder.build().run();
+
+        // Verify that the change was applied
+        List<AuditEntry> appliedEntries = auditStore.getPersistence()
             .getAuditHistory()
             .stream()
             .filter(e -> "simple-test-change".equals(e.getTaskId()))
             .filter(e -> AuditEntry.Status.APPLIED.equals(e.getState()))
             .collect(Collectors.toList());
 
-        assertThat(entries).hasSize(1);
+        assertThat(appliedEntries)
+            .as("Change should be applied after manual execution")
+            .hasSize(1);
     }
 }