feat: flamingock test support foundation (#751)

Author: davidfrigolet

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

@@ -0,0 +1,25 @@
+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")
+}
+
+description = "Test support module for Flamingock framework"
+
+
+tasks.withType<JavaCompile>().configureEach {
+    if (name.contains("Test", ignoreCase = true)) {
+        options.compilerArgs.addAll(listOf(
+            "-Asources=${projectDir}/src/test/java",
+            "-Aresources=${projectDir}/src/test/resources"
+        ))
+    }
+}
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(8))
+    }
+}

core/flamingock-test-support/src/main/java/io/flamingock/internal/core/builder/BuilderAccessor.java

@@ -0,0 +1,31 @@
+/*
+ * 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.internal.core.builder;
+
+import io.flamingock.internal.core.store.AuditStore;
+
+public class BuilderAccessor {
+
+    private AbstractChangeRunnerBuilder<?, ?> builder;
+
+    public BuilderAccessor(AbstractChangeRunnerBuilder<?,?> builder) {
+        this.builder = builder;
+    }
+
+    public AuditStore<?> getAuditStore(){
+        return builder.auditStore;
+    }
+}

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

@@ -0,0 +1,87 @@
+/*
+ * 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;
+
+
+import io.flamingock.internal.core.builder.AbstractChangeRunnerBuilder;
+import io.flamingock.internal.core.builder.BuilderAccessor;
+import io.flamingock.support.impl.GivenStageImpl;
+
+/**
+ * Entry point for the Flamingock BDD-style test support framework.
+ *
+ * <p>This class provides a fluent API for testing Flamingock change executions using the
+ * Given-When-Then pattern. It allows you to set up preconditions (existing audit state),
+ * define expectations, and verify the resulting audit entries.</p>
+ *
+ * <h2>Usage Example</h2>
+ * <pre>{@code
+ * FlamingockTestSupport
+ *     .given(builder)
+ *     .andAppliedChanges(InitialSetupChange.class, SchemaV1Change.class)
+ *     .andFailedChanges(FailedMigrationChange.class)
+ *     .whenRun()
+ *     .thenExpectAuditSequenceStrict(
+ *         APPLIED("schema-v2-change")
+ *             .withClass(SchemaV2Change.class)
+ *             .withAuthor("dev-team"),
+ *         APPLIED("data-migration-change")
+ *     )
+ *     .verify();
+ * }</pre>
+ *
+ * <h2>Test Flow</h2>
+ * <ol>
+ *   <li><b>Given</b> ({@link GivenStage}): Define the initial audit state (preconditions)</li>
+ *   <li><b>When</b> ({@link WhenStage}): Define expectations for when the runner executes</li>
+ *   <li><b>Then</b> ({@link ThenStage}): Chain additional expectations</li>
+ *   <li><b>Verify</b> ({@link ThenStage#verify()}): Execute the runner and validate expectations</li>
+ * </ol>
+ *
+ * <p><b>Note:</b> This is a lazy API similar to Java Streams. All methods except
+ * {@link ThenStage#verify()} are intermediate operations. The actual execution
+ * and verification only occur when {@code verify()} is called.</p>
+ *
+ * @see GivenStage
+ * @see WhenStage
+ * @see ThenStage
+ * @see io.flamingock.support.domain.AuditEntryExpectation
+ */
+public final class FlamingockTestSupport {
+
+    private FlamingockTestSupport() {
+    }
+
+    /**
+     * Starts the test setup phase with the provided Flamingock builder.
+     *
+     * <p>This method initializes the BDD test flow by accepting a configured
+     * {@link AbstractChangeRunnerBuilder}. The builder should be fully configured
+     * with the pipeline, audit store, and any other required settings before
+     * being passed to this method.</p>
+     *
+     * @param builder the configured change runner builder to test; must not be {@code null}
+     * @return the {@link GivenStage} for defining initial audit state preconditions
+     * @throws NullPointerException if {@code builder} is {@code null}
+     */
+    public static GivenStage given(AbstractChangeRunnerBuilder<?, ?> builder) {
+        if (builder == null) {
+            throw new NullPointerException("builder must not be null");
+        }
+        BuilderAccessor builderAccessor = new BuilderAccessor(builder);
+        return new GivenStageImpl();
+    }
+}

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

@@ -0,0 +1,95 @@
+/*
+ * 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;
+
+/**
+ * Represents the "Given" phase of the BDD test flow for setting up preconditions.
+ *
+ * <p>This stage allows you to define the initial audit state that should exist
+ * before running the change runner. You can specify which changes should be
+ * marked as already applied, failed, or rolled back in the audit store.</p>
+ *
+ * <p>All methods in this interface are intermediate operations that return {@code this}
+ * to enable fluent method chaining. When setup is complete, call {@link #whenRun()}
+ * to transition to the assertion phase.</p>
+ *
+ * <p>Note: This is a lazy API. No execution occurs until {@link ThenStage#verify()}
+ * is called at the end of the chain.</p>
+ *
+ * <h2>Example</h2>
+ * <pre>{@code
+ * FlamingockTestSupport
+ *     .given(builder)
+ *     .andAppliedChanges(SetupChange.class, MigrationV1.class)
+ *     .andFailedChanges(FailedChange.class)
+ *     .whenRun()
+ *     // ... assertions
+ * }</pre>
+ *
+ * @see FlamingockTestSupport#given(io.flamingock.internal.core.builder.AbstractChangeRunnerBuilder)
+ * @see WhenStage
+ */
+public interface GivenStage {
+
+    /**
+     * Specifies changes that should be marked as successfully applied in the audit store
+     * before running the change runner.
+     *
+     * <p>These changes will be treated as if they were already executed successfully
+     * in a previous run. The change runner will skip them during execution.</p>
+     *
+     * @param changes the change classes to mark as applied
+     * @return this stage for method chaining
+     */
+    GivenStage andAppliedChanges(Class<?>... changes);
+
+    /**
+     * Specifies changes that should be marked as failed in the audit store
+     * before running the change runner.
+     *
+     * <p>These changes will be treated as if they failed in a previous run.
+     * Depending on the runner configuration, they may be retried or skipped.</p>
+     *
+     * @param changes the change classes to mark as failed
+     * @return this stage for method chaining
+     */
+    GivenStage andFailedChanges(Class<?>... changes);
+
+    /**
+     * Specifies changes that should be marked as rolled back in the audit store
+     * before running the change runner.
+     *
+     * <p>These changes will be treated as if they were executed but subsequently
+     * rolled back in a previous run.</p>
+     *
+     * @param changes the change classes to mark as rolled back
+     * @return this stage for method chaining
+     */
+    GivenStage andRolledBackChanges(Class<?>... changes);
+
+    /**
+     * Completes the setup phase and transitions to the assertion phase.
+     *
+     * <p>This method finalizes the preconditions and returns a {@link WhenStage}
+     * where you can define expectations about the audit entries that should
+     * result from running the change runner.</p>
+     *
+     * <p>Note: The actual execution occurs when {@link ThenStage#verify()} is called.</p>
+     *
+     * @return the {@link WhenStage} for defining assertions
+     */
+    WhenStage whenRun();
+}

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

@@ -0,0 +1,105 @@
+/*
+ * 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;
+
+import io.flamingock.support.domain.AuditEntryExpectation;
+
+import java.util.function.Consumer;
+
+/**
+ * Represents the "Then" phase of the BDD test flow for chaining assertions
+ * and triggering final execution and verification.
+ *
+ * <p>This stage allows you to add additional expectations after the initial assertion
+ * defined in {@link WhenStage}. The {@code andExpectXxx()} methods are intermediate
+ * operations that accumulate expectations.</p>
+ *
+ * <p>The {@link #verify()} method is the <b>terminal operation</b> that:</p>
+ * <ol>
+ *   <li>Executes the change runner with the configured preconditions</li>
+ *   <li>Validates all accumulated expectations against the actual results</li>
+ *   <li>Throws an assertion error if any expectation is not met</li>
+ * </ol>
+ *
+ * <h2>Example with Multiple Assertions</h2>
+ * <pre>{@code
+ * .whenRun()
+ * .thenExpectAuditSequenceStrict(
+ *     AuditEntryExpectation.APPLIED("change-1")
+ * )
+ * .andExpectAuditSequenceStrict(
+ *     AuditEntryExpectation.APPLIED("change-2")
+ * )
+ * .verify();  // Execution and verification happen here
+ * }</pre>
+ *
+ * @see WhenStage
+ * @see AuditEntryExpectation
+ */
+public interface ThenStage {
+
+    /**
+     * Adds an additional strict expectation for the audit entry sequence.
+     *
+     * <p>This method has the same semantics as
+     * {@link WhenStage#thenExpectAuditSequenceStrict(AuditEntryExpectation...)}
+     * but allows chaining multiple sequence expectations.</p>
+     *
+     * <p><b>Strict validation</b> means:</p>
+     * <ul>
+     *   <li>The number of actual audit entries must exactly match the number of expectations</li>
+     *   <li>The order of audit entries must exactly match the order of expectations</li>
+     *   <li>Each audit entry is validated against its corresponding expectation</li>
+     * </ul>
+     *
+     * @param expectations the expected audit entries in exact order
+     * @return this stage for method chaining
+     * @see AuditEntryExpectation
+     */
+    ThenStage andExpectAuditSequenceStrict(AuditEntryExpectation... expectations);
+
+    /**
+     * Adds an expectation that the execution should throw a specific exception.
+     *
+     * <p>This method has the same semantics as
+     * {@link WhenStage#thenExpectException(Class, Consumer)}
+     * but allows chaining after other assertions.</p>
+     *
+     * @param exceptionClass the expected exception type
+     * @param validator      a consumer to perform additional assertions on the thrown exception;
+     *                       may be {@code null} if no additional validation is needed
+     * @return this stage for method chaining
+     */
+    ThenStage andExpectException(Class<? extends Throwable> exceptionClass, Consumer<Throwable> validator);
+
+    /**
+     * Terminal operation that executes the change runner and verifies all expectations.
+     *
+     * <p>This method performs the following steps:</p>
+     * <ol>
+     *   <li>Sets up the audit store with the preconditions defined in {@link GivenStage}</li>
+     *   <li>Executes the Flamingock change runner</li>
+     *   <li>Validates all accumulated expectations against the actual audit entries</li>
+     * </ol>
+     *
+     * <p>This is the only method in the fluent chain that triggers actual execution.
+     * All preceding methods ({@code given}, {@code andAppliedChanges}, {@code whenRun},
+     * {@code thenExpect...}) are intermediate operations that only configure the test.</p>
+     *
+     * @throws AssertionError if any expectation is not met
+     */
+    void verify();
+}