Package org.axonframework.test.saga

Class SagaTestFixture<T>

java.lang.Object
org.axonframework.test.saga.SagaTestFixture<T>
All Implemented Interfaces:
ContinuedGivenState, FixtureConfiguration, WhenState
public class SagaTestFixture<T> extends Object implements FixtureConfiguration, ContinuedGivenState
Fixture for testing Annotated Sagas based on events and time passing. This fixture allows resources to be configured for the sagas to use.
Since:
1.1
Author:
Allard Buijze

  • Constructor Details

    • SagaTestFixture

      public SagaTestFixture(Class<T> sagaType)
      Creates an instance of the AnnotatedSagaTestFixture to test sagas of the given sagaType.
      Parameters:
      sagaType - The type of saga under test

  • Method Details

    • handleInSaga

      protected void handleInSaga(EventMessage<?> event)
      Handles the given event in the scope of a Unit of Work. If handling the event results in an exception the exception will be wrapped in a FixtureExecutionException.
      Parameters:
      event - The event message to handle

    • handleDeadline

      protected void handleDeadline(ScopeDescriptor sagaDescriptor, DeadlineMessage<?> deadlineMessage) throws Exception
      Handles the given deadlineMessage in the saga described by the given sagaDescriptor. Deadline message is handled in the scope of a UnitOfWork. If handling the deadline results in an exception, the exception will be wrapped in a FixtureExecutionException.
      Parameters:
      sagaDescriptor - A ScopeDescriptor describing the saga under test
      deadlineMessage - The DeadlineMessage to be handled
      Throws:
      Exception

    • ensureSagaResourcesInitialized

      protected void ensureSagaResourcesInitialized()
      Initializes the saga resources if it hasn't already done so. If once initialized, this method does nothing.

    • withTransienceCheckDisabled

      public FixtureConfiguration withTransienceCheckDisabled()
      Description copied from interface: FixtureConfiguration
      Disables the check that injected resources are stored in fields that are marked 'transient'.

      By default, Saga fixtures check for the transient modifier on fields that hold injected resources. These resources are generally not means to be serialized as part of the Saga.

      When the transience check reports false positives, this method allows this check to be skipped.

      Specified by:
      withTransienceCheckDisabled in interface FixtureConfiguration
      Returns:
      this instance for fluent interfacing.

    • whenTimeElapses

      public FixtureExecutionResult whenTimeElapses(Duration elapsedTime)
      Description copied from interface: WhenState
      Mimic an elapsed time with no relevant activity for the Saga. If any Events are scheduled to be published within this time frame, they are published. All activity by the Saga on the CommandBus and EventBus (meaning that scheduled events are excluded) is recorded.

      Note that if you inject resources using FixtureConfiguration.registerResource(Object), you may need to reset them yourself if they are manipulated by the Saga in the "given" stage of the test.

      Specified by:
      whenTimeElapses in interface WhenState
      Parameters:
      elapsedTime - The amount of time to elapse
      Returns:
      an object allowing you to verify the test results

    • whenTimeAdvancesTo

      public FixtureExecutionResult whenTimeAdvancesTo(Instant newDateTime)
      Description copied from interface: WhenState
      Mimic an elapsed time with no relevant activity for the Saga. If any Events are scheduled to be published within this time frame, they are published. All activity by the Saga on the CommandBus and EventBus (meaning that scheduled events are excluded) is recorded.

      Note that if you inject resources using FixtureConfiguration.registerResource(Object), you may need to reset them yourself if they are manipulated by the Saga in the "given" stage of the test.

      Specified by:
      whenTimeAdvancesTo in interface WhenState
      Parameters:
      newDateTime - The time to advance the clock to
      Returns:
      an object allowing you to verify the test results

    • registerResource

      public void registerResource(Object resource)
      Description copied from interface: FixtureConfiguration
      Registers the given resource. When a Saga is created, all resources are injected on that instance before any Events are passed onto it.

      Note that a CommandBus, EventBus and EventScheduler are already registered as resources, and need not be registered again.

      Also note that you might need to reset the resources manually if you want to isolate behavior during the "when" stage of the test.

      Specified by:
      registerResource in interface FixtureConfiguration
      Parameters:
      resource - the resource to register.

    • registerParameterResolverFactory

      public FixtureConfiguration registerParameterResolverFactory(ParameterResolverFactory parameterResolverFactory)
      Description copied from interface: FixtureConfiguration
      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 FixtureConfiguration.registerResource(Object). The type of the saga under test is used as input for the ClasspathParameterResolverFactory#forClass(Class) operation.
      Specified by:
      registerParameterResolverFactory in interface FixtureConfiguration
      Parameters:
      parameterResolverFactory - the ParameterResolver to register within this fixture
      Returns:
      the current FixtureConfiguration, for fluent interfacing
      See Also:

    • setCallbackBehavior

      public void setCallbackBehavior(CallbackBehavior callbackBehavior)
      Description copied from interface: FixtureConfiguration
      Sets the instance that defines the behavior of the Command Bus when a command is dispatched with a callback.
      Specified by:
      setCallbackBehavior in interface FixtureConfiguration
      Parameters:
      callbackBehavior - The instance deciding to how the callback should be invoked.

    • givenAggregate

      public GivenAggregateEventPublisher givenAggregate(String aggregateIdentifier)
      Description copied from interface: FixtureConfiguration
      Use this method to indicate that an aggregate with given identifier published certain events.

      Can be chained to build natural sentences:
      andThenAggregate(someIdentifier).published(someEvents)

      Specified by:
      givenAggregate in interface FixtureConfiguration
      Parameters:
      aggregateIdentifier - The identifier of the aggregate the events should appear to come from
      Returns:
      an object that allows registration of the actual events to send

    • givenAPublished

      public ContinuedGivenState givenAPublished(Object event)
      Description copied from interface: FixtureConfiguration
      Indicates that the given applicationEvent has been published in the past. This event is sent to the associated sagas.
      Specified by:
      givenAPublished in interface FixtureConfiguration
      Parameters:
      event - The event to publish
      Returns:
      an object that allows chaining of more given state

    • givenAPublished

      public ContinuedGivenState givenAPublished(Object event, Map<String,?> metaData)
      Description copied from interface: FixtureConfiguration
      Indicates that the given event with given metaData has been published in the past. This event is sent to the associated sagas.
      Specified by:
      givenAPublished in interface FixtureConfiguration
      Parameters:
      event - The event to publish
      metaData - The meta data to attach to the event
      Returns:
      an object that allows chaining of more given state

    • givenCurrentTime

      public ContinuedGivenState givenCurrentTime(Instant currentTime)
      Description copied from interface: FixtureConfiguration
      Use this method to indicate a specific moment as the initial current time "known" by the fixture at the start of the given state.
      Specified by:
      givenCurrentTime in interface FixtureConfiguration
      Parameters:
      currentTime - The simulated "current time" at which the given state is initialized
      Returns:
      an object that allows chaining of more given state

    • givenNoPriorActivity

      public WhenState givenNoPriorActivity()
      Description copied from interface: FixtureConfiguration
      Indicates that no relevant activity has occurred in the past.
      Specified by:
      givenNoPriorActivity in interface FixtureConfiguration
      Returns:
      an object that allows the definition of the activity to measure Saga behavior

    • andThenAggregate

      public GivenAggregateEventPublisher andThenAggregate(String aggregateIdentifier)
      Description copied from interface: ContinuedGivenState
      Use this method to indicate that an aggregate with given identifier published certain events.

      Can be chained to build natural sentences:
      andThenAggregate(someIdentifier).published(someEvents)

      Specified by:
      andThenAggregate in interface ContinuedGivenState
      Parameters:
      aggregateIdentifier - The identifier of the aggregate the events should appear to come from
      Returns:
      an object that allows registration of the actual events to send

    • andThenTimeElapses

      public ContinuedGivenState andThenTimeElapses(Duration elapsedTime)
      Description copied from interface: ContinuedGivenState
      Simulate time shifts in the current given state. This can be useful when the time between given events is of importance.
      Specified by:
      andThenTimeElapses in interface ContinuedGivenState
      Parameters:
      elapsedTime - The amount of time that will elapse
      Returns:
      an object that allows registration of the actual events to send

    • andThenTimeAdvancesTo

      public ContinuedGivenState andThenTimeAdvancesTo(Instant newDateTime)
      Description copied from interface: ContinuedGivenState
      Simulate time shifts in the current given state. This can be useful when the time between given events is of importance.
      Specified by:
      andThenTimeAdvancesTo in interface ContinuedGivenState
      Parameters:
      newDateTime - The time to advance the clock to
      Returns:
      an object that allows registration of the actual events to send

    • andThenAPublished

      public ContinuedGivenState andThenAPublished(Object event)
      Description copied from interface: ContinuedGivenState
      Indicates that the given event has been published in the past. This event is sent to the associated sagas.
      Specified by:
      andThenAPublished in interface ContinuedGivenState
      Parameters:
      event - The event to publish
      Returns:
      an object that allows chaining of more given state

    • andThenAPublished

      public ContinuedGivenState andThenAPublished(Object event, Map<String,?> metaData)
      Description copied from interface: ContinuedGivenState
      Indicates that the given event with given metaData has been published in the past. This event is sent to the associated sagas.
      Specified by:
      andThenAPublished in interface ContinuedGivenState
      Parameters:
      event - The event to publish
      metaData - The meta data to attach to the event
      Returns:
      an object that allows chaining of more given state

    • whenAggregate

      public WhenAggregateEventPublisher whenAggregate(String aggregateIdentifier)
      Description copied from interface: WhenState
      Use this method to indicate that an aggregate with given identifier should publish certain events, while recording the outcome. In contrast to the FixtureConfiguration.givenAggregate(String) given} and ContinuedGivenState.andThenAggregate(String) andThen} methods, this method will start recording activity on the EventBus and CommandBus.

      Can be chained to build natural sentences:
      whenAggregate(someIdentifier).publishes(anEvent)

      Note that if you inject resources using FixtureConfiguration.registerResource(Object), you may need to reset them yourself if they are manipulated by the Saga in the "given" stage of the test.

      Specified by:
      whenAggregate in interface WhenState
      Parameters:
      aggregateIdentifier - The identifier of the aggregate the events should appear to come from
      Returns:
      an object that allows registration of the actual events to send

    • whenPublishingA

      public FixtureExecutionResult whenPublishingA(Object event)
      Description copied from interface: WhenState
      Use this method to indicate an application is published, while recording the outcome.

      Note that if you inject resources using FixtureConfiguration.registerResource(Object), you may need to reset them yourself if they are manipulated by the Saga in the "given" stage of the test.

      Specified by:
      whenPublishingA in interface WhenState
      Parameters:
      event - the event to publish
      Returns:
      an object allowing you to verify the test results

    • whenPublishingA

      public FixtureExecutionResult whenPublishingA(Object event, Map<String,?> metaData)
      Description copied from interface: WhenState
      Use this method to indicate an application is published with given additional metaData, while recording the outcome.

      Note that if you inject resources using FixtureConfiguration.registerResource(Object), you may need to reset them yourself if they are manipulated by the Saga in the "given" stage of the test.

      Specified by:
      whenPublishingA in interface WhenState
      Parameters:
      event - the event to publish
      metaData - The meta data to attach to the event
      Returns:
      an object allowing you to verify the test results

    • currentTime

      public Instant currentTime()
      Description copied from interface: FixtureConfiguration
      Returns the time as "known" by the fixture. This is the time at which the fixture was created, plus the amount of time the fixture was told to simulate a "wait".

      This time can be used to predict calculations that the saga may have made based on timestamps from the events it received.

      Specified by:
      currentTime in interface FixtureConfiguration
      Returns:
      the simulated "current time" of the fixture.

    • registerCommandGateway

      public <I> I registerCommandGateway(Class<I> gatewayInterface)
      Description copied from interface: FixtureConfiguration
      Creates a Command Gateway for the given gatewayInterface and registers that as a resource. The gateway will dispatch commands on the Command Bus contained in this Fixture, so that you can validate commands using FixtureExecutionResult.expectDispatchedCommands(Object...) and FixtureExecutionResult.expectDispatchedCommandsMatching(org.hamcrest.Matcher).

      Note that you need to use FixtureConfiguration.setCallbackBehavior(org.axonframework.test.utils.CallbackBehavior) to defined the behavior of commands when expecting return values. Alternatively, you can use FixtureConfiguration.registerCommandGateway(Class, Object) to define behavior using a stub implementation.

      Specified by:
      registerCommandGateway in interface FixtureConfiguration
      Type Parameters:
      I - The gateway type
      Parameters:
      gatewayInterface - The interface describing the gateway
      Returns:
      the gateway implementation being registered as a resource.

    • registerCommandGateway

      public <I> I registerCommandGateway(Class<I> gatewayInterface, I stubImplementation)
      Description copied from interface: FixtureConfiguration
      Creates a Command Gateway for the given gatewayInterface and registers that as a resource. The gateway will dispatch commands on the Command Bus contained in this Fixture, so that you can validate commands using FixtureExecutionResult.expectDispatchedCommands(Object...) and FixtureExecutionResult.expectDispatchedCommandsMatching(org.hamcrest.Matcher).

      The behavior of the created gateway is defined by the given stubImplementation, if not null. Dispatched Commands are still recorded for verification. Note that only commands executed in the "when" phase are recorded, while the stub implementation may record activity during the "given" phase as well.

      Specified by:
      registerCommandGateway in interface FixtureConfiguration
      Type Parameters:
      I - The gateway type
      Parameters:
      gatewayInterface - The interface describing the gateway
      stubImplementation - The stub or mock implementation defining behavior of the gateway
      Returns:
      the gateway implementation being registered as a resource.

    • registerFieldFilter

      public FixtureConfiguration registerFieldFilter(FieldFilter fieldFilter)
      Description copied from interface: FixtureConfiguration
      Registers the given fieldFilter, which is used to define which Fields are used when comparing objects. The ResultValidator.expectEvents(Object...) and ResultValidator.expectResultMessage(CommandResultMessage), 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.

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

    • registerIgnoredField

      public FixtureConfiguration registerIgnoredField(Class<?> declaringClass, String fieldName)
      Description copied from interface: FixtureConfiguration
      Indicates that a field with given fieldName, which is declared in given declaringClass is ignored when performing deep equality checks.
      Specified by:
      registerIgnoredField in interface FixtureConfiguration
      Parameters:
      declaringClass - The class declaring the field
      fieldName - The name of the field
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerHandlerDefinition

      public FixtureConfiguration registerHandlerDefinition(HandlerDefinition handlerDefinition)
      Description copied from interface: FixtureConfiguration
      Registers a HandlerDefinition within this fixture. The given handlerDefinition is added to the handler definitions introduced through ClasspathHandlerDefinition.forClass(Class). The type of the saga under test is used as input for the ClasspathHandlerDefinition#forClass(Class) operation.
      Specified by:
      registerHandlerDefinition in interface FixtureConfiguration
      Parameters:
      handlerDefinition - used to create concrete handlers
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerHandlerEnhancerDefinition

      public FixtureConfiguration registerHandlerEnhancerDefinition(HandlerEnhancerDefinition handlerEnhancerDefinition)
      Description copied from interface: FixtureConfiguration
      Registers a HandlerEnhancerDefinition within this fixture. This given handlerEnhancerDefinition is added to the handler enhancer definitions introduced through ClasspathHandlerEnhancerDefinition.forClass(Class). The type of the saga under test is used as input for the ClasspathHandlerEnhancerDefinition#forClass(Class) operation.
      Specified by:
      registerHandlerEnhancerDefinition in interface FixtureConfiguration
      Parameters:
      handlerEnhancerDefinition - the HandlerEnhancerDefinition to register within this fixture
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerDeadlineDispatchInterceptor

      public FixtureConfiguration registerDeadlineDispatchInterceptor(MessageDispatchInterceptor<? super DeadlineMessage<?>> deadlineDispatchInterceptor)
      Description copied from interface: FixtureConfiguration
      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.
      Specified by:
      registerDeadlineDispatchInterceptor in interface FixtureConfiguration
      Parameters:
      deadlineDispatchInterceptor - the interceptor for dispatching (scheduling) deadlines
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerDeadlineHandlerInterceptor

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

    • registerEventHandlerInterceptor

      public FixtureConfiguration registerEventHandlerInterceptor(MessageHandlerInterceptor<? super EventMessage<?>> eventHandlerInterceptor)
      Description copied from interface: FixtureConfiguration
      Registers a MessageHandlerInterceptor for EventMessages.

      Will always be invoked before an event is handled to perform a task specified in the interceptor. Interceptors are invoked in the order they have been registered in.

      Specified by:
      registerEventHandlerInterceptor in interface FixtureConfiguration
      Parameters:
      eventHandlerInterceptor - the interceptor for handling EventMessages
      Returns:
      The current FixtureConfiguration, for fluent interfacing.

    • registerStartRecordingCallback

      public FixtureConfiguration registerStartRecordingCallback(Runnable onStartRecordingCallback)
      Description copied from interface: FixtureConfiguration
      Registers a callback to be invoked when the fixture execution starts recording. This happens right before invocation of the 'when' step (stimulus) of the fixture.

      Use this to manage Saga dependencies which are not an Axon first class citizen, but do require monitoring of their interactions. For example, register the callback to set a mock in recording mode.

      Specified by:
      registerStartRecordingCallback in interface FixtureConfiguration
      Parameters:
      onStartRecordingCallback - callback to invoke
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • registerListenerInvocationErrorHandler

      public FixtureConfiguration registerListenerInvocationErrorHandler(ListenerInvocationErrorHandler listenerInvocationErrorHandler)
      Description copied from interface: FixtureConfiguration
      Registers a ListenerInvocationErrorHandler to be set for the Saga to deal with exceptions being thrown from within Saga Event Handlers. Will be given to the AnnotatedSagaManager for the defined Saga type. Defaults to a LoggingErrorHandler wrapped inside a RecordingListenerInvocationErrorHandler.
      Specified by:
      registerListenerInvocationErrorHandler in interface FixtureConfiguration
      Parameters:
      listenerInvocationErrorHandler - to be set for the Saga to deal with exceptions being thrown from within Saga Event Handlers
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • suppressExceptionInGivenPhase

      public FixtureConfiguration suppressExceptionInGivenPhase(boolean suppress)
      Description copied from interface: FixtureConfiguration
      Configure whether the fixture should suppress exceptions thrown during the given-phase. When suppress is true, the fixture moves on to the when-phase regardless of any exceptions thrown during the given-phase.

      Note that setting this to true means the registered ListenerInvocationErrorHandler is not invoked during exception in the given-phase. Defaults to suppressing during given-phase exceptions.

      Specified by:
      suppressExceptionInGivenPhase in interface FixtureConfiguration
      Parameters:
      suppress - A boolean describing whether the fixture should suppress failures during the given-phase.
      Returns:
      The current fixture, for fluent interfacing.

    • registerResourceInjector

      public FixtureConfiguration registerResourceInjector(ResourceInjector resourceInjector)
      Description copied from interface: FixtureConfiguration
      Registers a ResourceInjector within this fixture. This approach can be used if a custom ResourceInjector has been built for a project which the user wants to take into account when testing it's sagas.

      The provided resourceInjector will be paired with the fixture's default ResourceInjector to keep support for the FixtureConfiguration.registerResource(Object) and FixtureConfiguration.withTransienceCheckDisabled() methods. Note that first the default injector is called, and after that the given resourceInjector. This approach ensures the fixture's correct workings for default provided resources, like the EventBus and CommandBus}, whilst allowing the capability to append and/or override with the given resourceInjector.

      Care should be taken if the custom resourceInjector overrides default resources like the EventBus and CommandBus, as the fixture uses specialized versions of the default sources to support all testing functionality.

      Specified by:
      registerResourceInjector in interface FixtureConfiguration
      Parameters:
      resourceInjector - the ResourceInjector to register within this fixture
      Returns:
      the current FixtureConfiguration, for fluent interfacing

    • getEventBus

      public EventBus getEventBus()
      Description copied from interface: FixtureConfiguration
      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.
      Specified by:
      getEventBus in interface FixtureConfiguration
      Returns:
      the event bus used by this fixture

    • getCommandBus

      public RecordingCommandBus getCommandBus()
      Description copied from interface: FixtureConfiguration
      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).
      Specified by:
      getCommandBus in interface FixtureConfiguration
      Returns:
      the command bus used by this fixture