feat: flamingock test support new validatorArgs and integration test (#766)

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.

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

@@ -20,6 +20,7 @@
 import io.flamingock.support.validation.impl.AuditSequenceStrictValidator;
 import io.flamingock.support.validation.impl.DefaultExceptionValidator;
 
+import java.util.List;
 import java.util.function.Consumer;
 
 public class ValidatorFactory {
@@ -30,11 +31,25 @@ public ValidatorFactory(AuditReader auditReader) {
         this.auditReader = auditReader;
     }
 
-    public Validator getAuditSeqStrictValidator(AuditEntryDefinition... definitions) {
+    public Validator getAuditSeqStrictValidator(List<AuditEntryDefinition> definitions) {
         return new AuditSequenceStrictValidator(auditReader, 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());
+        }
+
+        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,10 +19,11 @@
 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;
-import java.util.Arrays;
+import java.util.Collections;
 import java.util.List;
 import java.util.stream.Collectors;
 
@@ -44,13 +45,22 @@ public class AuditSequenceStrictValidator implements SimpleValidator {
     private final AuditReader auditReader;
     private final List<AuditEntryExpectation> expectations;
     private final List<AuditEntry> actualEntries;
+    private static final List<AuditEntry.Status> EXCLUDED_STATES = Collections.singletonList(
+            AuditEntry.Status.STARTED
+    );
 
-    public AuditSequenceStrictValidator(AuditReader auditReader, AuditEntryDefinition... definitions) {
+    public AuditSequenceStrictValidator(AuditReader auditReader, List<AuditEntryDefinition> definitions) {
         this.auditReader = auditReader;
-        this.expectations = Arrays.stream(definitions)
+        this.expectations = definitions != null
+                ? definitions.stream()
                 .map(AuditEntryExpectation::new)
+                .collect(Collectors.toList())
+                : new ArrayList<>();
+
+       this.actualEntries = auditReader.getAuditHistory().stream()
+                .filter(entry -> !EXCLUDED_STATES.contains(entry.getState()))
+                .sorted()
                 .collect(Collectors.toList());
-        this.actualEntries = auditReader.getAuditHistory();
     }
 
     /**
@@ -77,8 +87,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 +103,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 +127,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;
+        }
+    }
 }