Package org.bct.api

Class AssertionArgs

java.lang.Object
org.bct.api.AssertionArgs
public class AssertionArgs extends Object
Configuration and context object for advanced assertion operations.

This class encapsulates additional arguments and configuration options for assertion methods in the Bean-Centric Testing (BCT) framework. It provides a fluent API for customizing assertion behavior including custom converters and enhanced error messaging.

The primary purposes of this class are:

  • Custom Bean Conversion: Override the default BeanConverter for specialized object introspection
  • Enhanced Error Messages: Add context-specific error messages with parameter substitution
  • Fluent Configuration: Chain configuration calls for readable test setup
  • Assertion Context: Provide additional context for complex assertion scenarios
Basic Usage:

// Simple usage with default settings assertBean(args(), myBean, "name,age", "John,30"); // Custom error message assertBean(args().setMessage("User validation failed"), user, "email,active", "john@example.com,true");

Custom Bean Converter:

// Use custom converter for specialized object handling var customConverter = BasicBeanConverter.builder() .defaultSettings() .addStringifier(MyClass.class, obj -> obj.getDisplayName()) .build(); assertBean(args().setBeanConverter(customConverter), myCustomObject, "property", "expectedValue");

Advanced Error Messages:

// Parameterized error messages assertBean(args().setMessage("Validation failed for user {0}", userId), user, "status", "ACTIVE"); // Dynamic error message with supplier assertBean(args().setMessage(() -> "Test failed at " + Instant.now()), result, "success", "true");

Fluent Configuration:

// Chain multiple configuration options var testArgs = args() .setBeanConverter(customConverter) .setMessage("Integration test failed for module {0}", moduleName); assertBean(testArgs, moduleConfig, "enabled,version", "true,2.1.0"); assertBeans(testArgs, moduleList, "name,status", "ModuleA,ACTIVE", "ModuleB,ACTIVE");

Error Message Composition:

When assertion failures occur, error messages are intelligently composed:

// Example error message composition: // Base: "User validation failed for user 123" // Context: "Bean assertion failed." // Result: "User validation failed for user 123, Caused by: Bean assertion failed."

Thread Safety:

This class is not thread-safe and is intended for single-threaded test execution. Each test method should create its own instance using BctAssertions.args() or create a new instance directly with new AssertionArgs().

Immutability Considerations:

While this class uses fluent setters that return this for chaining, the instance is mutable. For reusable configurations across multiple tests, consider creating a factory method that returns pre-configured instances.

See Also:

  • Constructor Details

    • AssertionArgs

      public AssertionArgs()
      Creates a new instance with default settings.

      Instances start with no custom bean converter and no custom error message. All assertion methods will use default behavior until configured otherwise.

  • Method Details

    • setBeanConverter

      public AssertionArgs setBeanConverter(BeanConverter value)
      Sets a custom BeanConverter for object introspection and property access.

      The custom converter allows fine-tuned control over how objects are converted to strings, how collections are listified, and how nested properties are accessed. This is particularly useful for:

      • Custom Object Types: Objects that don't follow standard JavaBean patterns
      • Specialized Formatting: Custom string representations for assertion comparisons
      • Performance Optimization: Cached or optimized property access strategies
      • Domain-Specific Logic: Business-specific property resolution rules
      Example:

      // Create converter with custom stringifiers var converter = BasicBeanConverter.builder() .defaultSettings() .addStringifier(LocalDate.class, date -> date.format(DateTimeFormatter.ISO_LOCAL_DATE)) .addStringifier(Money.class, money -> money.getAmount().toPlainString()) .build(); // Use in assertions assertBean(args().setBeanConverter(converter), order, "date,total", "2023-12-01,99.99");

      Parameters:
      value - The custom bean converter to use. If null, assertions will fall back to the default converter.
      Returns:
      This instance for method chaining.

    • getBeanConverter

      protected Optional<BeanConverter> getBeanConverter()
      Gets the configured bean converter, if any.
      Returns:
      An Optional containing the custom converter, or empty if using default behavior.

    • setMessage

      public AssertionArgs setMessage(Supplier<String> value)
      Sets a custom error message supplier for assertion failures.

      The supplier allows for dynamic message generation, including context that may only be available at the time of assertion failure. This is useful for:

      • Timestamps: Including the exact time of failure
      • Test State: Including runtime state information
      • Expensive Operations: Deferring costly string operations until needed
      • Conditional Messages: Different messages based on runtime conditions
      Example:

      // Dynamic message with timestamp assertBean(args().setMessage(() -> "Test failed at " + Instant.now()), result, "status", "SUCCESS"); // Message with expensive computation assertBean(args().setMessage(() -> "Failed after " + computeTestDuration() + " ms"), response, "error", "null");

      Parameters:
      value - The message supplier. Called only when an assertion fails.
      Returns:
      This instance for method chaining.

    • setMessage

      public AssertionArgs setMessage(String message, Object... args)
      Sets a parameterized error message for assertion failures.

      This method uses MessageFormat to substitute parameters into the message template. The formatting occurs immediately when this method is called, not when the assertion fails.

      Parameter Substitution:

      Uses standard MessageFormat patterns:

      • {0} - First parameter
      • {1} - Second parameter
      • {0,number,#} - Formatted number
      • {0,date,short} - Formatted date
      Examples:

      // Simple parameter substitution assertBean(args().setMessage("User {0} validation failed", userId), user, "active", "true"); // Multiple parameters assertBean(args().setMessage("Test {0} failed on iteration {1}", testName, iteration), result, "success", "true"); // Number formatting assertBean(args().setMessage("Expected {0,number,#.##} but got different value", expectedValue), actual, "value", "123.45");

      Parameters:
      message - The message template with MessageFormat placeholders.
      args - The parameters to substitute into the message template.
      Returns:
      This instance for method chaining.

    • getMessage

      protected Supplier<String> getMessage()
      Gets the base message supplier for composition with assertion-specific messages.
      Returns:
      The configured message supplier, or null if no custom message was set.

    • getMessage

      protected Supplier<String> getMessage(String msg, Object... args)
      Composes the final error message by combining custom and assertion-specific messages.

      This method implements the message composition strategy used throughout the assertion framework:

      • No Custom Message: Returns the assertion-specific message as-is
      • With Custom Message: Returns "{custom}, Caused by: {assertion}"

      This allows tests to provide high-level context while preserving the specific technical details about what assertion failed.

      Parameters:
      msg - The assertion-specific message template.
      args - Parameters for the assertion-specific message.
      Returns:
      A supplier that produces the composed error message.