Package org.axonframework.test.aggregate

Interface FixtureConfiguration<T>

Type Parameters:
T - The type of the aggregate under test
All Known Implementing Classes:
AggregateTestFixture
public interface FixtureConfiguration<T>
Interface describing the operations available on a test fixture in the configuration stage. This stage allows a test case to prepare the fixture for test execution.

The fixture is initialized using a Command Handler that expects an @CommandHandler aggregate. If you have implemented your own command handler (either using annotations, or by implementing the MessageHandler interface), you must register the command handler using registerAnnotatedCommandHandler(Object) or registerCommandHandler(Class, MessageHandler), respectively. A typical command handler will require a repository. The test fixture initializes an Event Sourcing Repository, which can be obtained using getRepository(). Alternatively, you can register your own repository using the registerRepository(Repository) method. Registering the repository will cause the fixture to configure the correct EventBus and EventStore implementations required by the test.

Typical usage example:

 public class MyCommandHandlerTest() {
 
       private FixtureConfiguration fixture;
 
      @Before
     public void setUp() {
         fixture = new AggregateTestFixture(MyAggregate.class);
         MyCommandHandler commandHandler = new MyCommandHandler();
         commandHandler.setRepository(fixture.getRepository());
         fixture.registerAnnotatedCommandHandler(commandHandler);
     }
 
      @Test
     public void testCommandHandlerCase() {
         fixture.given(new MyEvent(1), new MyEvent(2))
                .when(new TestCommand())
                .expectResultMessagePayload(null)
                .expectEvents(new MyEvent(3));
     }
 
  }

If you use @CommandHandler annotations on the aggregate, you do not need to configure any additional command handlers. In that case, no configuration is required:

Providing the "given" events using the given(Object...) or given(List<DomainEvent>) methods must be the last operation in the configuration stage. To indicate that no "given" events are available, just call given() with no parameters.

Besides setting configuration, you can also use the FixtureConfiguration to get access to the configured components. This allows you to (manually) inject the EventBus or any other component into you command handler, for example.

Since:
0.6
Author:
Allard Buijze

  • Method Details

    • withSubtypes

      FixtureConfiguration<T> withSubtypes(Class<? extends T>... subtypes)
      Registers subtypes of this aggregate to support aggregate polymorphism. Command Handlers defined on this subtype will be considered part of this aggregate's handlers.
      Parameters:
      subtypes - subtypes in this polymorphic hierarchy
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • useStateStorage

      FixtureConfiguration<T> useStateStorage()
      Configures the fixture for state stored aggregates. This will register an in-memory
      invalid reference 
      org.axonframework.commandhandling.model.Repository
      with this fixture. Should be used before calling givenState(Supplier) or givenCommands(List) (Supplier)}.
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerRepository

      FixtureConfiguration<T> registerRepository(Repository<T> repository)
      Registers an arbitrary repository with the fixture. The repository must be wired with the Event Store of this test fixture.

      Should not be used in combination with registerAggregateFactory(org.axonframework.eventsourcing.AggregateFactory), as that will overwrite any repository previously registered.

      Parameters:
      repository - The repository to use in the test case
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerRepositoryProvider

      FixtureConfiguration<T> registerRepositoryProvider(RepositoryProvider repositoryProvider)
      Registers repository provider with the fixture. If an aggregate being tested spawns new aggregates, this provider should be registered. Otherwise, it is not going to be invoked.
      Parameters:
      repositoryProvider - provides repositories for specified aggregate types
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerAggregateFactory

      FixtureConfiguration<T> registerAggregateFactory(AggregateFactory<T> aggregateFactory)
      Registers the given aggregateFactory with the fixture. The repository used by the fixture will use the given factory to create new aggregate instances. Defaults to an Aggregate Factory that uses the no-arg constructor to create new instances.

      Should not be used in combination with registerRepository(Repository), as that will overwrite any aggregate factory previously registered.

      Parameters:
      aggregateFactory - The Aggregate Factory to create empty aggregates with
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerAnnotatedCommandHandler

      FixtureConfiguration<T> registerAnnotatedCommandHandler(Object annotatedCommandHandler)
      Registers an annotatedCommandHandler with this fixture. This will register this command handler with the command bus used in this fixture.
      Parameters:
      annotatedCommandHandler - The command handler to register for this test
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerCommandHandler

      FixtureConfiguration<T> registerCommandHandler(Class<?> payloadType, MessageHandler<CommandMessage<?>> commandHandler)
      Registers a commandHandler to handle commands of the given commandType with the command bus used by this fixture.
      Parameters:
      payloadType - The type of command to register the handler for
      commandHandler - The handler to register
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerCommandHandler

      FixtureConfiguration<T> registerCommandHandler(String commandName, MessageHandler<CommandMessage<?>> commandHandler)
      Registers a commandHandler to handle commands of the given commandType with the command bus used by this fixture.
      Parameters:
      commandName - The name of the command to register the handler for
      commandHandler - The handler to register
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerInjectableResource

      FixtureConfiguration<T> registerInjectableResource(Object resource)
      Registers a resource that is eligible for injection in handler method (e.g. methods annotated with @CommandHandler, @EventSourcingHandler and EventHandler. These resource must be registered before registering any command handler.
      Parameters:
      resource - the resource eligible for injection
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerInjectableResources

      default FixtureConfiguration<T> registerInjectableResources(Object... resources)
      Default implementation to register multiple resources in handler method (e.g. methods annotated with @CommandHandler, @EventSourcingHandler and EventHandler. These resource must be registered before registering any command handler. Internally this method calls invalid input: 'for each resource. @param resources collection of resources eligible for injection @return the current FixtureConfiguration, for fluent interfacing'

    • registerParameterResolverFactory

      FixtureConfiguration<T> registerParameterResolverFactory(ParameterResolverFactory parameterResolverFactory)
      Registers a ParameterResolverFactory within this fixture. The given parameterResolverFactory will be added to the other parameter resolver factories introduced through ClasspathParameterResolverFactory.forClass(Class) and the SimpleResourceParameterResolverFactory adding the registered resources (with registerInjectableResource(Object). The generic T is used as input for the ClasspathParameterResolverFactory#forClass(Class) operation.
      Parameters:
      parameterResolverFactory - the ParameterResolver to register within this fixture
      Returns:
      the current FixtureConfiguration, for fluent interfacing
      See Also:

    • registerCommandDispatchInterceptor

      FixtureConfiguration<T> registerCommandDispatchInterceptor(MessageDispatchInterceptor<? super CommandMessage<?>> commandDispatchInterceptor)
      Register a MessageDispatchInterceptor for CommandMessages which will be invoked before any command is dispatched on the CommandBus to perform a task specified in the interceptor. For example by adding MetaData or throwing an exception based on the command.
      Parameters:
      commandDispatchInterceptor - the MessageDispatchInterceptor for CommandMessages to be added to this fixture's CommandBus
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerCommandHandlerInterceptor

      FixtureConfiguration<T> registerCommandHandlerInterceptor(MessageHandlerInterceptor<? super CommandMessage<?>> commandHandlerInterceptor)
      Register a MessageHandlerInterceptor for CommandMessages which will be invoked before or after the command has been dispatched on the CommandBus to perform a task specified in the interceptor. It could for example block the command for security reasons or add auditing to the command bus
      Parameters:
      commandHandlerInterceptor - the MessageHandlerInterceptor for CommandMessages to be added to this fixture's CommandBus
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerDeadlineDispatchInterceptor

      FixtureConfiguration<T> registerDeadlineDispatchInterceptor(MessageDispatchInterceptor<? super DeadlineMessage<?>> deadlineDispatchInterceptor)
      Registers a deadline dispatch interceptor which will always be invoked before a deadline is dispatched (scheduled) on the DeadlineManager to perform a task specified in the interceptor.
      Parameters:
      deadlineDispatchInterceptor - the interceptor for dispatching (scheduling) deadlines
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerDeadlineHandlerInterceptor

      FixtureConfiguration<T> registerDeadlineHandlerInterceptor(MessageHandlerInterceptor<? super DeadlineMessage<?>> deadlineHandlerInterceptor)
      Registers a deadline handler interceptor which will always be invoked before a deadline is handled to perform a task specified in the interceptor.
      Parameters:
      deadlineHandlerInterceptor - the interceptor for handling deadlines
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerFieldFilter

      FixtureConfiguration<T> registerFieldFilter(FieldFilter fieldFilter)
      Registers the given fieldFilter, which is used to define which Fields are used when comparing objects. The ResultValidator.expectEvents(Object...) and ResultValidator.expectResultMessagePayload(Object), for example, use this filter.

      When multiple filters are registered, a Field must be accepted by all registered filters in order to be accepted.

      By default, all Fields are included in the comparison.

      Parameters:
      fieldFilter - The FieldFilter that defines which fields to include in the comparison
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerIgnoredField

      FixtureConfiguration<T> registerIgnoredField(Class<?> declaringClass, String fieldName)
      Indicates that a field with given fieldName, which is declared in given declaringClass is ignored when performing deep equality checks.
      Parameters:
      declaringClass - The class declaring the field
      fieldName - The name of the field
      Returns:
      the current FixtureConfiguration, for fluent interfacing
      Throws:
      FixtureExecutionException - when no such field is declared

    • registerHandlerDefinition

      FixtureConfiguration<T> registerHandlerDefinition(HandlerDefinition handlerDefinition)
      Registers a HandlerDefinition within this fixture. The given handlerDefinition is added to the handler definitions introduced through ClasspathHandlerDefinition.forClass(Class). The generic T is used as input for the ClasspathHandlerDefinition#forClass(Class) operation.
      Parameters:
      handlerDefinition - used to create concrete handlers
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerHandlerEnhancerDefinition

      FixtureConfiguration<T> registerHandlerEnhancerDefinition(HandlerEnhancerDefinition handlerEnhancerDefinition)
      Registers a HandlerEnhancerDefinition within this fixture. This given handlerEnhancerDefinition is added to the handler enhancer definitions introduced through ClasspathHandlerEnhancerDefinition.forClass(Class). The generic T is used as input for the ClasspathHandlerEnhancerDefinition#forClass(Class) operation.
      Parameters:
      handlerEnhancerDefinition - the HandlerEnhancerDefinition to register within this fixture
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerCommandTargetResolver

      FixtureConfiguration<T> registerCommandTargetResolver(CommandTargetResolver commandTargetResolver)
      Registers the CommandTargetResolver within this fixture. The commandTargetResolver will replace the default implementation (defined by the AggregateAnnotationCommandHandler within this fixture.
      Parameters:
      commandTargetResolver - the CommandTargetResolver used to resolve an Aggregate for a given command
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • given

      TestExecutor<T> given(Object... domainEvents)
      Configures the given domainEvents as the "given" events. These are the events returned by the event store when an aggregate is loaded.

      If an item in the given domainEvents implements Message, the payload and MetaData from that Message are copied into a newly created DomainEventMessage. Otherwise, a DomainEventMessage with the item as payload and empty MetaData is created.

      Note that transitioning to the returned TestExecutor will clear any previously defined "given" state to ensure the fixture can run a clean test environment.

      Parameters:
      domainEvents - The domain events the event store should return.
      Returns:
      A TestExecutor instance that can execute the test with this configuration.

    • givenState

      TestExecutor<T> givenState(Supplier<T> aggregateState)
      Sets the aggregate instance as supplied by given aggregateState as the initial state for a test case.

      Usage of this method is highly discouraged for event sourced aggregates. In that case, use given(Object...) to specify historic events.

      Note that transitioning to the returned TestExecutor will clear any previously defined "given" state to ensure the fixture can run a clean test environment.

      Parameters:
      aggregateState - A Supplier providing the state to use as starting point for this fixture.
      Returns:
      A TestExecutor instance that can execute the test with this configuration.

    • givenNoPriorActivity

      TestExecutor<T> givenNoPriorActivity()
      Indicates that no relevant activities like commands or events have occurred in the past. This also means that no previous state is present in the repository.
      Returns:
      A TestExecutor instance that can execute the test with this configuration.

    • given

      TestExecutor<T> given(List<?> domainEvents)
      Configures the given domainEvents as the "given" events. These are the events returned by the event store when an aggregate is loaded.

      If an item in the list implements Message, the payload and MetaData from that Message are copied into a newly created DomainEventMessage. Otherwise, a DomainEventMessage with the item as payload and empty MetaData is created.

      Note that transitioning to the returned TestExecutor will clear any previously defined "given" state to ensure the fixture can run a clean test environment.

      Parameters:
      domainEvents - The domain events the event store should return.
      Returns:
      A TestExecutor instance that can execute the test with this configuration.

    • givenCommands

      TestExecutor<T> givenCommands(Object... commands)
      Configures the given commands as to execute against the aggregate under test to initiate the given-phase. The commands are executed, and the resulting stored events are captured.

      Note that transitioning to the returned TestExecutor will clear any previously defined "given" state to ensure the fixture can run a clean test environment.

      Parameters:
      commands - The commands to execute against the aggregate under test to initiate the given-phase.
      Returns:
      A TestExecutor instance that can execute the test with this configuration.

    • givenCommands

      TestExecutor<T> givenCommands(List<?> commands)
      Configures the given commands as to execute against the aggregate under test to initiate the given-phase. The commands are executed, and the resulting stored events are captured.

      Note that transitioning to the returned TestExecutor will clear any previously defined "given" state to ensure the fixture can run a clean test environment.

      Parameters:
      commands - The commands to execute against the aggregate under test to initiate the given-phase.
      Returns:
      A TestExecutor instance that can execute the test with this configuration.

    • getCommandBus

      CommandBus getCommandBus()
      Returns the command bus used by this fixture. The command bus is provided for wiring purposes only, for example to support composite commands (a single command that causes the execution of one or more others).
      Returns:
      the command bus used by this fixture

    • getEventBus

      EventBus getEventBus()
      Returns the event bus used by this fixture. The event bus is provided for wiring purposes only, for example to allow command handlers to publish events other than Domain Events. Events published on the returned event bus are recorded an evaluated in the ResultValidator operations.
      Returns:
      the event bus used by this fixture

    • getEventStore

      EventStore getEventStore()
      Returns the event store used by this fixture. This event store is provided for wiring purposes only.
      Returns:
      the event store used by this fixture

    • getRepository

      Repository<T> getRepository()
      Returns the repository used by this fixture. This repository is provided for wiring purposes only. The repository is configured to use the fixture's event store to load events.
      Returns:
      the repository used by this fixture

    • givenCurrentTime

      TestExecutor<T> givenCurrentTime(Instant time)
      Use this method to indicate a specific moment as the initial current time "known" by the fixture at the start of the given state.

      Note that transitioning to the returned TestExecutor will clear any previously defined "given" state to ensure the fixture can run a clean test environment.

      Parameters:
      time - An Instant defining the simulated "current time" at which the given state is initialized.
      Returns:
      A TestExecutor instance that can execute the test with this configuration.

    • setReportIllegalStateChange

      void setReportIllegalStateChange(boolean reportIllegalStateChange)
      Sets whether or not the fixture should detect and report state changes that occur outside of Event Handler methods.
      Parameters:
      reportIllegalStateChange - whether or not to detect and report state changes outside of Event Handler methods.