refactor: add test support error foundation (#753)

Author: dieppa

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

@@ -0,0 +1,57 @@
+/*
+ * 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;
+
+import io.flamingock.support.validation.error.ValidationError;
+import io.flamingock.support.validation.error.ValidationResult;
+
+import java.util.List;
+
+/**
+ * Formats validation errors into a human-readable message for display
+ * in assertion errors.
+ *
+ * <p>The formatter groups errors by validator and presents them in a
+ * clear, structured format.</p>
+ */
+public class ValidationErrorFormatter {
+
+    private static final String HEADER = "Flamingock Test Verification Failed";
+    private static final String BULLET = "  • ";
+    private static final String NEWLINE = "\n";
+
+    /**
+     * Formats a list of validation failures into a human-readable message.
+     *
+     * @param failures the list of validation results that contain errors
+     * @return a formatted error message
+     */
+    public String format(List<ValidationResult> failures) {
+        StringBuilder sb = new StringBuilder();
+        sb.append(HEADER).append(NEWLINE);
+
+        for (ValidationResult result : failures) {
+            sb.append(NEWLINE);
+            sb.append("[").append(result.getValidatorName()).append("]").append(NEWLINE);
+
+            for (ValidationError error : result.getErrors()) {
+                sb.append(BULLET).append(error.formatMessage()).append(NEWLINE);
+            }
+        }
+
+        return sb.toString().trim();
+    }
+}

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

@@ -15,12 +15,27 @@
  */
 package io.flamingock.support.validation;
 
+import io.flamingock.support.validation.error.ExceptionNotExpectedError;
+import io.flamingock.support.validation.error.ValidationResult;
+
+import java.util.ArrayList;
 import java.util.List;
+import java.util.stream.Collectors;
 
+/**
+ * Orchestrates the execution of all validators and aggregates their results.
+ *
+ * <p>The handler executes all registered validators, collects their results,
+ * and throws an {@link AssertionError} if any validation fails. The error
+ * message is formatted to display all failures grouped by validator.</p>
+ */
 public class ValidationHandler {
 
+    private static final String EXECUTION_VALIDATOR_NAME = "Execution";
+
     private final List<Validator> validators;
     private final Throwable executionException;
+    private final ValidationErrorFormatter formatter;
 
     public ValidationHandler(List<Validator> validators) {
         this(validators, null);
@@ -29,14 +44,59 @@ public ValidationHandler(List<Validator> validators) {
     public ValidationHandler(List<Validator> validators, Throwable executionException) {
         this.validators = validators;
         this.executionException = executionException;
+        this.formatter = new ValidationErrorFormatter();
     }
 
-
+    /**
+     * Executes all validators and throws an AssertionError if any validation fails.
+     *
+     * <p>This method:</p>
+     * <ol>
+     *   <li>Executes each registered validator</li>
+     *   <li>Checks for unexpected exceptions (if no exception validator is registered)</li>
+     *   <li>Collects all validation failures</li>
+     *   <li>Throws an AssertionError with a formatted message if any failures exist</li>
+     * </ol>
+     *
+     * @throws AssertionError if any validation fails
+     */
     public void validate() throws AssertionError {
+        List<ValidationResult> results = new ArrayList<>();
 
-        //TODO process validator and grab the potential validation errors in a AssertionError
-        // we probably need another class for building the validation result
+        for (Validator validator : validators) {
+            ValidationResult result = executeValidator(validator);
+            if (result != null) {
+                results.add(result);
+            }
+        }
 
+        // Check if no exception expected but one occurred
+        if (executionException != null && !hasExceptionValidator()) {
+            results.add(ValidationResult.failure(EXECUTION_VALIDATOR_NAME,
+                    new ExceptionNotExpectedError(executionException)));
+        }
+
+        // Collect all failures
+        List<ValidationResult> failures = results.stream()
+                .filter(ValidationResult::hasErrors)
+                .collect(Collectors.toList());
+
+        if (!failures.isEmpty()) {
+            throw new AssertionError(formatter.format(failures));
+        }
+    }
+
+    private ValidationResult executeValidator(Validator validator) {
+        if (validator instanceof SimpleValidator) {
+            return ((SimpleValidator) validator).validate();
+        } else if (validator instanceof ExceptionValidator) {
+            return ((ExceptionValidator) validator).validate(executionException);
+        }
+        return null;
+    }
 
+    private boolean hasExceptionValidator() {
+        return validators.stream()
+                .anyMatch(v -> v instanceof ExceptionValidator);
     }
 }

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

@@ -0,0 +1,68 @@
+/*
+ * 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.error;
+
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Validation error indicating that the count of audit entries
+ * does not match the expected count.
+ *
+ * <p>This error includes both the expected and actual lists of change IDs
+ * to provide full context for debugging.</p>
+ */
+public class CountMismatchError extends ValidationError {
+
+    private final List<String> expectedChangeIds;
+    private final List<String> actualChangeIds;
+
+    /**
+     * Creates a new count mismatch error.
+     *
+     * @param expectedChangeIds the list of expected change IDs
+     * @param actualChangeIds   the list of actual change IDs found
+     */
+    public CountMismatchError(List<String> expectedChangeIds, List<String> actualChangeIds) {
+        super(ValidationErrorType.COUNT_MISMATCH);
+        this.expectedChangeIds = expectedChangeIds != null
+                ? Collections.unmodifiableList(expectedChangeIds)
+                : Collections.emptyList();
+        this.actualChangeIds = actualChangeIds != null
+                ? Collections.unmodifiableList(actualChangeIds)
+                : Collections.emptyList();
+    }
+
+    public List<String> getExpectedChangeIds() {
+        return expectedChangeIds;
+    }
+
+    public List<String> getActualChangeIds() {
+        return actualChangeIds;
+    }
+
+    @Override
+    public String formatMessage() {
+        return String.format(
+                "Audit entry count mismatch: expected <%d> entries but found <%d>\n" +
+                "    Expected: %s\n" +
+                "    Actual:   %s",
+                expectedChangeIds.size(),
+                actualChangeIds.size(),
+                expectedChangeIds,
+                actualChangeIds);
+    }
+}

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

@@ -0,0 +1,66 @@
+/*
+ * 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.error;
+
+/**
+ * Validation error indicating that a custom validation
+ * (user-provided validator) failed.
+ */
+public class CustomValidationError extends ValidationError {
+
+    private final String message;
+    private final Throwable cause;
+
+    /**
+     * Creates a new custom validation error with a message.
+     *
+     * @param message the error message describing the validation failure
+     */
+    public CustomValidationError(String message) {
+        this(message, null);
+    }
+
+    /**
+     * Creates a new custom validation error with a message and cause.
+     *
+     * @param message the error message describing the validation failure
+     * @param cause   the exception thrown by the custom validator, or {@code null}
+     */
+    public CustomValidationError(String message, Throwable cause) {
+        super(ValidationErrorType.CUSTOM_VALIDATION);
+        this.message = message;
+        this.cause = cause;
+    }
+
+    public String getMessage() {
+        return message;
+    }
+
+    public Throwable getCause() {
+        return cause;
+    }
+
+    @Override
+    public String formatMessage() {
+        if (cause != null) {
+            return String.format("Custom validation failed: %s (caused by: %s - '%s')",
+                    message,
+                    cause.getClass().getSimpleName(),
+                    cause.getMessage());
+        }
+        return String.format("Custom validation failed: %s", message);
+    }
+}

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

@@ -0,0 +1,49 @@
+/*
+ * 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.error;
+
+/**
+ * Validation error indicating that an exception was thrown
+ * when none was expected.
+ */
+public class ExceptionNotExpectedError extends ValidationError {
+
+    private final Throwable actualException;
+
+    /**
+     * Creates a new unexpected exception error.
+     *
+     * @param actualException the exception that was thrown
+     */
+    public ExceptionNotExpectedError(Throwable actualException) {
+        super(ValidationErrorType.EXCEPTION_NOT_EXPECTED);
+        this.actualException = actualException;
+    }
+
+    public Throwable getActualException() {
+        return actualException;
+    }
+
+    @Override
+    public String formatMessage() {
+        String exceptionName = actualException.getClass().getSimpleName();
+        String message = actualException.getMessage();
+        if (message != null && !message.isEmpty()) {
+            return String.format("Unexpected exception thrown: %s - '%s'", exceptionName, message);
+        }
+        return String.format("Unexpected exception thrown: %s", exceptionName);
+    }
+}

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

@@ -0,0 +1,59 @@
+/*
+ * 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.error;
+
+/**
+ * Validation error indicating that the thrown exception type
+ * does not match the expected type, or no exception was thrown
+ * when one was expected.
+ */
+public class ExceptionTypeMismatchError extends ValidationError {
+
+    private final Class<? extends Throwable> expectedType;
+    private final Class<? extends Throwable> actualType;
+
+    /**
+     * Creates a new exception type mismatch error.
+     *
+     * @param expectedType the expected exception type
+     * @param actualType   the actual exception type thrown, or {@code null} if no exception was thrown
+     */
+    public ExceptionTypeMismatchError(Class<? extends Throwable> expectedType,
+                                      Class<? extends Throwable> actualType) {
+        super(ValidationErrorType.EXCEPTION_TYPE_MISMATCH);
+        this.expectedType = expectedType;
+        this.actualType = actualType;
+    }
+
+    public Class<? extends Throwable> getExpectedType() {
+        return expectedType;
+    }
+
+    public Class<? extends Throwable> getActualType() {
+        return actualType;
+    }
+
+    @Override
+    public String formatMessage() {
+        if (actualType == null) {
+            return String.format("Expected exception <%s> but none was thrown",
+                    expectedType.getSimpleName());
+        }
+        return String.format("Exception type mismatch: expected <%s> but was <%s>",
+                expectedType.getSimpleName(),
+                actualType.getSimpleName());
+    }
+}