feat: flamingock test support new validatorArgs and integration test

Author: davidfrigolet

core/flamingock-test-support/build.gradle.kts

@@ -1,9 +1,15 @@
 dependencies {
     api(project(":core:flamingock-core"))
 
+
     testImplementation(platform("org.junit:junit-bom:5.10.0"))
     testImplementation("org.junit.jupiter:junit-jupiter")
     testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+
+    // Add test utilities from the repository so tests can use InMemoryTestKit and pipeline helpers
+    testImplementation(project(":utils:test-util"))
+    testImplementation(project(":core:target-systems:nontransactional-target-system"))
+    api("org.mockito:mockito-inline:4.11.0")
 }
 
 description = "Test support module for Flamingock framework"

core/flamingock-test-support/src/main/java/io/flamingock/support/domain/AuditEntryDefinition.java

@@ -29,10 +29,7 @@
 import java.lang.reflect.Method;
 import java.time.LocalDateTime;
 
-import static io.flamingock.internal.common.core.audit.AuditEntry.Status.APPLIED;
-import static io.flamingock.internal.common.core.audit.AuditEntry.Status.FAILED;
-import static io.flamingock.internal.common.core.audit.AuditEntry.Status.ROLLBACK_FAILED;
-import static io.flamingock.internal.common.core.audit.AuditEntry.Status.ROLLED_BACK;
+import static io.flamingock.internal.common.core.audit.AuditEntry.Status.*;
 
 /**
  * Defines an audit entry for use in BDD-style tests.
@@ -61,6 +58,7 @@
  *
  * <h3>String-based (manual configuration)</h3>
  * <ul>
+ *   <li>{@link #STARTED(String)} - Define a started change</li>
  *   <li>{@link #APPLIED(String)} - Define an applied change</li>
  *   <li>{@link #FAILED(String)} - Define a failed change</li>
  *   <li>{@link #ROLLED_BACK(String)} - Define a rolled-back change</li>
@@ -69,6 +67,7 @@
  *
  * <h3>Class-based (auto-extraction from annotations)</h3>
  * <ul>
+ *   <li>{@link #STARTED(Class)} - Extracts changeId, author, className, methodName from annotations</li>
  *   <li>{@link #APPLIED(Class)} - Extracts changeId, author, className, methodName from annotations</li>
  *   <li>{@link #FAILED(Class)} - Same extraction for failed changes</li>
  *   <li>{@link #ROLLED_BACK(Class)} - Extracts rollback method name from {@code @Rollback}</li>
@@ -120,6 +119,16 @@ private AuditEntryDefinition(String changeId, AuditEntry.Status state) {
 
     // ========== Static Factory Methods (String-based) ==========
 
+    /**
+     * Creates a definition for a started change.
+     *
+     * @param changeId the unique identifier of the change
+     * @return a new definition builder for further configuration
+     */
+    public static AuditEntryDefinition STARTED(String changeId) {
+        return new AuditEntryDefinition(changeId, STARTED);
+    }
+
     /**
      * Creates a definition for an applied change.
      *
@@ -162,6 +171,29 @@ public static AuditEntryDefinition ROLLBACK_FAILED(String changeId) {
 
     // ========== Static Factory Methods (Class-based) ==========
 
+    /**
+     * Creates a definition for a started change by extracting metadata from annotations.
+     *
+     * <p>Extracts from the change class:</p>
+     * <ul>
+     *   <li>Change ID and author from {@code @Change} annotation</li>
+     *   <li>Class name from the class itself</li>
+     *   <li>Method name from the method annotated with {@code @Apply}</li>
+     *   <li>Target system ID from {@code @TargetSystem} annotation (if present)</li>
+     *   <li>Recovery strategy from {@code @Recovery} annotation (if present)</li>
+     *   <li>Order from class name pattern {@code _ORDER__CHANGE-NAME} (if applicable)</li>
+     *   <li>Transactional flag from {@code @Change.transactional()}</li>
+     * </ul>
+     *
+     * @param changeClass the change class annotated with {@code @Change}
+     * @return a new definition builder pre-populated with annotation values
+     * @throws IllegalArgumentException if the class is not annotated with {@code @Change}
+     *         or does not contain a method annotated with {@code @Apply}
+     */
+    public static AuditEntryDefinition STARTED(Class<?> changeClass) {
+        return fromChangeClass(changeClass, STARTED);
+    }
+
     /**
      * Creates a definition for an applied change by extracting metadata from annotations.
      *
@@ -261,7 +293,7 @@ private static AuditEntryDefinition fromChangeClass(Class<?> changeClass, AuditE
 
     private static String findMethodName(Class<?> changeClass, AuditEntry.Status status) {
         Class<? extends Annotation> annotationClass =
-                (status == APPLIED || status == FAILED) ? Apply.class : Rollback.class;
+                (status == STARTED || status == APPLIED || status == FAILED) ? Apply.class : Rollback.class;
 
         for (Method method : changeClass.getDeclaredMethods()) {
             if (method.isAnnotationPresent(annotationClass)) {

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

@@ -19,52 +19,53 @@
 import io.flamingock.support.domain.AuditEntryDefinition;
 import io.flamingock.support.precondition.PreconditionInserter;
 import io.flamingock.support.validation.ValidationHandler;
-import io.flamingock.support.validation.Validator;
-import io.flamingock.support.validation.ValidatorFactory;
+import io.flamingock.support.validation.ValidatorArgs;
+import io.flamingock.support.validation.impl.AuditSequenceStrictValidator;
+import io.flamingock.support.validation.impl.DefaultExceptionValidator;
 
 import java.util.ArrayList;
 import java.util.List;
 import java.util.function.Consumer;
+import java.util.Arrays;
+import java.util.Collections;
 
 final class ThenStageImpl implements ThenStage {
 
-    private final List<Validator> validators = new ArrayList<>();
-    private final ValidatorFactory validatorFactory;
+    private final List<ValidatorArgs> validators = new ArrayList<>();
     private final TestContext testContext;
 
     ThenStageImpl(TestContext testContext) {
         this.testContext = testContext;
-        validatorFactory = new ValidatorFactory(testContext.getAuditReader());
     }
 
     @Override
     public ThenStage andExpectAuditSequenceStrict(AuditEntryDefinition... definitions) {
-        validators.add(validatorFactory.getAuditSeqStrictValidator(definitions));
+        List<AuditEntryDefinition> definitionsList = definitions != null ? Arrays.asList(definitions) : Collections.<AuditEntryDefinition>emptyList();
+        validators.add(new AuditSequenceStrictValidator.Args(definitionsList));
         return this;
     }
 
     @Override
     public ThenStage andExpectException(Class<? extends Throwable> exceptionClass, Consumer<Throwable> exceptionConsumer) {
-        validators.add(validatorFactory.getExceptionValidator(exceptionClass, exceptionConsumer));
+        validators.add(new DefaultExceptionValidator.Args(exceptionClass, exceptionConsumer));
         return this;
     }
 
     @Override
     public void verify() throws AssertionError {
-        // Insert preconditions first
-        PreconditionInserter preconditionInserter = new PreconditionInserter(testContext.getAuditWriter());
-        preconditionInserter.insert(testContext.getPreconditions());
-
         ValidationHandler validationHandler;
         try {
             testContext.run();
-            validationHandler = new ValidationHandler(validators);
+            validationHandler = new ValidationHandler(testContext, validators);
 
         } catch (Throwable actualException) {
-            validationHandler = new ValidationHandler(validators, actualException);
+            validationHandler = new ValidationHandler(testContext, validators, actualException);
 
         }
 
         validationHandler.validate();
+
+        PreconditionInserter preconditionInserter = new PreconditionInserter(testContext.getAuditWriter());
+        preconditionInserter.insert(testContext.getPreconditions());
     }
 }

core/flamingock-test-support/src/main/java/io/flamingock/support/validation/ValidationHandler.java

@@ -15,6 +15,7 @@
  */
 package io.flamingock.support.validation;
 
+import io.flamingock.support.context.TestContext;
 import io.flamingock.support.validation.error.ExceptionNotExpectedError;
 import io.flamingock.support.validation.error.ValidationResult;
 
@@ -47,6 +48,25 @@ public ValidationHandler(List<Validator> validators, Throwable executionExceptio
         this.formatter = new ValidationErrorFormatter();
     }
 
+    // TestContext and deferred ValidatorArgs
+    public ValidationHandler(TestContext testContext, List<ValidatorArgs> args) {
+        this(testContext, args, null);
+    }
+
+    public ValidationHandler(TestContext testContext, List<ValidatorArgs> args, Throwable executionException) {
+        this.executionException = executionException;
+        this.formatter = new ValidationErrorFormatter();
+        // Build actual validators now that we have access to the TestContext
+        ValidatorFactory factory = new ValidatorFactory(testContext.getAuditReader());
+        List<Validator> built = new ArrayList<>();
+        if (args != null) {
+            for (ValidatorArgs a : args) {
+                built.add(factory.getValidator(a));
+            }
+        }
+        this.validators = built;
+    }
+
     /**
      * Executes all validators and throws an AssertionError if any validation fails.
      *

core/flamingock-test-support/src/main/java/io/flamingock/support/validation/ValidatorArgs.java

@@ -0,0 +1,72 @@
+/*
+ * 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.support.validation;
+
+/**
+ * Marker interface for validator argument carriers used in the BDD test framework.
+ *
+ * <p>This interface serves as a deferred construction pattern for validators. Instead of
+ * creating validators immediately when defining expectations in the "Then" stage, implementations
+ * of this interface carry the necessary arguments until the {@link io.flamingock.support.stages.ThenStage#verify()} method
+ * is called. This allows validators to be constructed with access to the {@link io.flamingock.support.context.TestContext},
+ * particularly the {@link io.flamingock.internal.common.core.audit.AuditReader}.</p>
+ *
+ * <h2>Purpose</h2>
+ * <p>The deferred construction is necessary because:</p>
+ * <ul>
+ *   <li>The audit reader is only available after the test context is fully initialized</li>
+ *   <li>Validators need access to actual audit entries, which are only available after execution</li>
+ *   <li>The BDD API is lazy - expectations are defined but not executed until {@code verify()}</li>
+ * </ul>
+ *
+ * <h2>Implementation</h2>
+ * <p>Implementations are typically static inner classes within their corresponding validators:</p>
+ * <pre>{@code
+ * public class AuditSequenceStrictValidator implements SimpleValidator {
+ *     // ... validator implementation
+ *
+ *     public static class Args implements ValidatorArgs {
+ *         private final List<AuditEntryDefinition> expectations;
+ *
+ *         public Args(List<AuditEntryDefinition> expectations) {
+ *             this.expectations = expectations;
+ *         }
+ *
+ *         public List<AuditEntryDefinition> getExpectations() {
+ *             return expectations;
+ *         }
+ *     }
+ * }
+ * }</pre>
+ *
+ * <h2>Usage in Framework</h2>
+ * <p>The framework uses these argument carriers as follows:</p>
+ * <ol>
+ *   <li>User calls expectation method (e.g., {@code thenExpectAuditSequenceStrict(...)})</li>
+ *   <li>Stage creates an {@code Args} instance and stores it in the validators list</li>
+ *   <li>When {@code verify()} is called, the {@link ValidationHandler} constructs actual
+ *       validators using {@link ValidatorFactory#getValidator(ValidatorArgs)}</li>
+ *   <li>Validators are executed with access to the test context and audit reader</li>
+ * </ol>
+ *
+ * @see ValidatorFactory#getValidator(ValidatorArgs)
+ * @see ValidationHandler
+ * @see io.flamingock.support.stages.ThenStage#verify()
+ */
+public interface ValidatorArgs {
+}
+
+

core/flamingock-test-support/src/main/java/io/flamingock/support/validation/ValidatorFactory.java

@@ -37,4 +37,18 @@ public Validator getAuditSeqStrictValidator(AuditEntryDefinition... definitions)
     public Validator getExceptionValidator(Class<? extends Throwable> exceptionClass, Consumer<Throwable> exceptionConsumer) {
         return new DefaultExceptionValidator(exceptionClass, exceptionConsumer);
     }
+
+    public Validator getValidator(ValidatorArgs args) {
+        if (args instanceof AuditSequenceStrictValidator.Args) {
+            AuditSequenceStrictValidator.Args a = (AuditSequenceStrictValidator.Args) args;
+            return new AuditSequenceStrictValidator(auditReader, a.getExpectations().toArray(new AuditEntryDefinition[0]));
+        }
+
+        if (args instanceof DefaultExceptionValidator.Args) {
+            DefaultExceptionValidator.Args a = (DefaultExceptionValidator.Args) args;
+            return new DefaultExceptionValidator(a.getExceptionClass(), a.getExceptionConsumer());
+        }
+
+        throw new IllegalArgumentException("Unknown ValidatorArgs type: " + (args != null ? args.getClass() : "null"));
+    }
 }

core/flamingock-test-support/src/main/java/io/flamingock/support/validation/impl/AuditSequenceStrictValidator.java

@@ -19,6 +19,7 @@
 import io.flamingock.internal.common.core.audit.AuditReader;
 import io.flamingock.support.domain.AuditEntryDefinition;
 import io.flamingock.support.validation.SimpleValidator;
+import io.flamingock.support.validation.ValidatorArgs;
 import io.flamingock.support.validation.error.*;
 
 import java.util.ArrayList;
@@ -77,8 +78,8 @@ public ValidationResult validate() {
         allErrors.addAll(getValidationErrors(expectations, actualEntries));
 
         return allErrors.isEmpty()
-          ? ValidationResult.success(VALIDATOR_NAME)
-          : ValidationResult.failure(VALIDATOR_NAME, allErrors.toArray(new ValidationError[0]));
+                ? ValidationResult.success(VALIDATOR_NAME)
+                : ValidationResult.failure(VALIDATOR_NAME, allErrors.toArray(new ValidationError[0]));
     }
 
     private static List<ValidationError> getValidationErrors(List<AuditEntryExpectation> expectedEntries, List<AuditEntry> actualEntries) {
@@ -93,15 +94,15 @@ private static List<ValidationError> getValidationErrors(List<AuditEntryExpectat
             AuditEntryExpectation expected = i < expectedEntries.size() ? expectedEntries.get(i) : null;
             AuditEntry actual = i < actualEntries.size() ? actualEntries.get(i) : null;
             if( expected != null && actual != null) {
-               allErrors.addAll(expected.compareWith(actual));
+                allErrors.addAll(expected.compareWith(actual));
             } else if( expected != null) {
-               AuditEntryDefinition def = expected.getDefinition();
+                AuditEntryDefinition def = expected.getDefinition();
                 allErrors.add(new MissingEntryError(i, def.getChangeId(), def.getState()));
             } else {
                 assert actual != null;
                 allErrors.add(new UnexpectedEntryError(i, actual.getTaskId(), actual.getState()));
             }
-           
+
         }
         return allErrors;
     }
@@ -117,4 +118,16 @@ private List<String> getActualChangeIds() {
                 .map(AuditEntry::getTaskId)
                 .collect(Collectors.toList());
     }
+
+    public static class Args implements ValidatorArgs {
+        private final List<AuditEntryDefinition> expectations;
+
+        public Args(List<AuditEntryDefinition> expectations) {
+            this.expectations = expectations;
+        }
+
+        public List<AuditEntryDefinition> getExpectations() {
+            return expectations;
+        }
+    }
 }

core/flamingock-test-support/src/main/java/io/flamingock/support/validation/impl/DefaultExceptionValidator.java

@@ -68,4 +68,22 @@ public ValidationResult validate(Throwable actualException) {
         }
         return ValidationResult.success(VALIDATOR_NAME);
     }
+
+    public static class Args implements io.flamingock.support.validation.ValidatorArgs {
+        private final Class<? extends Throwable> exceptionClass;
+        private final Consumer<Throwable> exceptionConsumer;
+
+        public Args(Class<? extends Throwable> exceptionClass, Consumer<Throwable> exceptionConsumer) {
+            this.exceptionClass = exceptionClass;
+            this.exceptionConsumer = exceptionConsumer;
+        }
+
+        public Class<? extends Throwable> getExceptionClass() {
+            return exceptionClass;
+        }
+
+        public Consumer<Throwable> getExceptionConsumer() {
+            return exceptionConsumer;
+        }
+    }
 }