feature: flamingock test support for springboot

Author: dieppa

core/flamingock-test-support/src/main/java/io/flamingock/support/FlamingockTestSupport.java

@@ -84,7 +84,7 @@ private FlamingockTestSupport() {
      * @return the {@link GivenStage} for defining initial audit state preconditions
      * @throws NullPointerException if {@code builder} is {@code null}
      */
-    public static GivenStage given(AbstractChangeRunnerBuilder<?, ?> builder) {
+    public static GivenStage givenBuilder(AbstractChangeRunnerBuilder<?, ?> builder) {
         if (builder == null) {
             throw new NullPointerException("builder must not be null");
         }

core/flamingock-test-support/src/main/java/io/flamingock/support/stages/GivenStage.java

@@ -47,7 +47,7 @@
  *     // ... assertions
  * }</pre>
  *
- * @see FlamingockTestSupport#given(io.flamingock.internal.core.builder.AbstractChangeRunnerBuilder)
+ * @see FlamingockTestSupport#givenBuilder(io.flamingock.internal.core.builder.AbstractChangeRunnerBuilder)
  * @see WhenStage
  * @see AuditEntryDefinition
  */

core/flamingock-test-support/src/test/java/io/flamingock/support/integration/FlamingockTestSupportIntegrationTest.java

@@ -50,7 +50,7 @@ void shouldExecuteNonTransactionalChange() {
             NonTransactionalTargetSystem targetSystem = new NonTransactionalTargetSystem("kafka");
 
             FlamingockTestSupport
-                    .given(testKit.createBuilder().addTargetSystem(targetSystem))
+                    .givenBuilder(testKit.createBuilder().addTargetSystem(targetSystem))
                     .whenRun()
                     .thenExpectAuditSequenceStrict(
                             APPLIED(_001__SimpleNonTransactionalChange.class)
@@ -75,7 +75,7 @@ void shouldVerifyMultipleChangesInSequence() {
             );
 
             FlamingockTestSupport
-                    .given(testKit.createBuilder()
+                    .givenBuilder(testKit.createBuilder()
                             .addTargetSystem(new NonTransactionalTargetSystem("okta"))
                             .addTargetSystem(new NonTransactionalTargetSystem("elasticsearch"))
                             .addTargetSystem(new NonTransactionalTargetSystem("s3")))
@@ -101,7 +101,7 @@ void shouldVerifyFailingTransactionalChangeTriggersRollback() {
             );
 
             FlamingockTestSupport
-                    .given(testKit.createBuilder()
+                    .givenBuilder(testKit.createBuilder()
                             .addTargetSystem(new NonTransactionalTargetSystem("salesforce"))
                             .addTargetSystem(new NonTransactionalTargetSystem("okta"))
                             .addTargetSystem(new NonTransactionalTargetSystem("elasticsearch"))
@@ -129,7 +129,7 @@ void shouldVerifyAlreadyAppliedChangesAreSkipped() {
             );
 
             FlamingockTestSupport
-                    .given(testKit.createBuilder()
+                    .givenBuilder(testKit.createBuilder()
                             .addTargetSystem(new NonTransactionalTargetSystem("stripe-api"))
                             .addTargetSystem(new NonTransactionalTargetSystem("okta"))
                             .addTargetSystem(new NonTransactionalTargetSystem("elasticsearch"))
@@ -164,7 +164,7 @@ void shouldVerifyDependencyInjectionInRollbackForNonTransactionalChanges() {
             );
 
             FlamingockTestSupport
-                    .given(testKit.createBuilder().addTargetSystem(targetSystem))
+                    .givenBuilder(testKit.createBuilder().addTargetSystem(targetSystem))
                     .whenRun()
                     .thenExpectException(PipelineExecutionException.class, ex -> {
                         assertTrue(ex.getMessage().contains("Intentional failure"));
@@ -192,7 +192,7 @@ void shouldVerifyTransactionalChangeExecutesSuccessfully() {
             );
 
             FlamingockTestSupport
-                    .given(testKit.createBuilder()
+                    .givenBuilder(testKit.createBuilder()
                             .addTargetSystem(new NonTransactionalTargetSystem("okta"))
                             .addTargetSystem(new NonTransactionalTargetSystem("elasticsearch"))
                             .addTargetSystem(new NonTransactionalTargetSystem("s3")))

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

@@ -0,0 +1,22 @@
+package io.flamingock.springboot.testsupport;
+
+import io.flamingock.internal.core.builder.AbstractChangeRunnerBuilder;
+import io.flamingock.support.FlamingockTestSupport;
+import io.flamingock.support.stages.GivenStage;
+
+public class FlamingockSpringBootTestSupport {
+
+    private final AbstractChangeRunnerBuilder<?, ?> builderFromContext;
+
+    FlamingockSpringBootTestSupport(AbstractChangeRunnerBuilder<?,?> builderFromContext) {
+        this.builderFromContext = builderFromContext;
+    }
+
+    public GivenStage givenBuilderFromContext() {
+        return FlamingockTestSupport.givenBuilder(builderFromContext);
+    }
+
+    public GivenStage givenBuilder(AbstractChangeRunnerBuilder<?,?> builderFromContextOverwrite) {
+        return FlamingockTestSupport.givenBuilder(builderFromContextOverwrite);
+    }
+}

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

@@ -0,0 +1,77 @@
+/*
+ * 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 io.flamingock.internal.core.builder.AbstractChangeRunnerBuilder;
+import io.flamingock.support.FlamingockTestSupport;
+import io.flamingock.support.stages.GivenStage;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Scope;
+
+/**
+ * Auto-configuration that provides a {@link GivenStage} bean for Flamingock testing.
+ *
+ * <p>This configuration is automatically picked up when using {@link FlamingockSpringBootTest}
+ * and provides a ready-to-use {@code GivenStage} bean that can be autowired directly in tests.</p>
+ *
+ * <p><strong>Example usage:</strong></p>
+ * <pre>{@code
+ * @FlamingockSpringBootTest(classes = {MyApp.class, TestConfig.class})
+ * class MyFlamingockTest {
+ *
+ *     @Autowired
+ *     private GivenStage givenStage;
+ *
+ *     @Test
+ *     void testMigration() {
+ *         givenStage
+ *             .whenRun()
+ *             .thenExpectAuditSequenceStrict(APPLIED(MyChange.class))
+ *             .verify();
+ *     }
+ * }
+ * }</pre>
+ *
+ * <p><strong>Note:</strong> The {@code GivenStage} bean has prototype scope, meaning a new instance
+ * is created for each injection point. This is necessary because {@code GivenStage} accumulates
+ * internal state (preconditions, expectations) and is not reusable between tests.</p>
+ *
+ * @see FlamingockSpringBootTest
+ * @see FlamingockTestSupport
+ * @see GivenStage
+ * @since 1.0
+ */
+@Configuration
+public class FlamingockTestAutoConfiguration {
+
+    /**
+     * Creates a {@link GivenStage} bean for Flamingock testing.
+     *
+     * <p>The bean has prototype scope to ensure each test gets its own fresh instance,
+     * as {@code GivenStage} accumulates state and cannot be shared between tests.</p>
+     *
+     * @param builderFromContext the Flamingock builder, automatically configured by Spring Boot
+     * @return a new {@code GivenStage} instance ready for testing
+     */
+    @Bean
+    @Scope("prototype")
+    @ConditionalOnBean(AbstractChangeRunnerBuilder.class)
+    public FlamingockSpringBootTestSupport flamingockGivenStage(AbstractChangeRunnerBuilder<?, ?> builderFromContext) {
+        return new FlamingockSpringBootTestSupport(builderFromContext);
+    }
+}

platform-plugins/flamingock-springboot-test-support/src/main/resources/META-INF/spring.factories

@@ -0,0 +1,2 @@
+org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
+io.flamingock.springboot.testsupport.FlamingockTestAutoConfiguration

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

@@ -15,42 +15,25 @@
  */
 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 io.flamingock.springboot.testsupport.changes._001__SimpleTestChange;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.context.ApplicationContext;
 import org.springframework.test.context.junit.jupiter.SpringExtension;
 
-import java.util.List;
-import java.util.stream.Collectors;
-
+import static io.flamingock.support.domain.AuditEntryDefinition.APPLIED;
 import static org.assertj.core.api.Assertions.assertThat;
 
-/**
- * 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)  // Required for Spring Boot 2.0.x
+@ExtendWith(SpringExtension.class)  // Required for Spring Boot 2.0.x. For >= 2.1.0, not required
 @FlamingockSpringBootTest(classes = {TestApplication.class, FlamingockTestConfiguration.class})
 class SpringBootFlamingockIntegrationTest {
 
     @Autowired
     private ApplicationContext context;
 
     @Autowired
-    private CommunityAuditStore auditStore;
-
-    @Autowired
-    private AbstractChangeRunnerBuilder<?, ?> flamingockBuilder;
+    private FlamingockSpringBootTestSupport testSupport;
 
     @Test
     void contextLoads() {
@@ -68,22 +51,15 @@ void flamingockRunnerBeanExists() {
     }
 
     @Test
-    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());
+    void shouldUseTestSupportAsExpected() {
 
-        assertThat(appliedEntries)
-            .as("Change should be applied after manual execution")
-            .hasSize(1);
+        testSupport
+                .givenBuilderFromContext()
+                .whenRun()
+                .thenExpectAuditSequenceStrict(
+                        APPLIED(_001__SimpleTestChange.class)
+                )
+                .verify();
     }
+
 }