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 Summary

Constructors

Constructor and Description
SagaTestFixture(Class<T> sagaType) Creates an instance of the AnnotatedSagaTestFixture to test sagas of the given sagaType.

Method Summary

Modifier and Type	Method and Description
GivenAggregateEventPublisher	andThenAggregate(String aggregateIdentifier) Use this method to indicate that an aggregate with given identifier published certain events.
ContinuedGivenState	andThenAPublished(Object event) Indicates that the given event has been published in the past.
ContinuedGivenState	andThenAPublished(Object event, Map<String,?> metaData) Indicates that the given event with given metaData has been published in the past.
ContinuedGivenState	andThenTimeAdvancesTo(Instant newDateTime) Simulate time shifts in the current given state.
ContinuedGivenState	andThenTimeElapses(Duration elapsedTime) Simulate time shifts in the current given state.
Instant	currentTime() Returns the time as "known" by the fixture.
protected void	ensureSagaResourcesInitialized() Initializes the saga resources if it hasn't already done so.
RecordingCommandBus	getCommandBus() Returns the command bus used by this fixture.
EventBus	getEventBus() Returns the event bus used by this fixture.
GivenAggregateEventPublisher	givenAggregate(String aggregateIdentifier) Use this method to indicate that an aggregate with given identifier published certain events.
ContinuedGivenState	givenAPublished(Object event) Indicates that the given applicationEvent has been published in the past.
ContinuedGivenState	givenCurrentTime(Instant currentTime) Use this method to indicate a specific moment as the initial current time "known" by the fixture at the start of the given state.
WhenState	givenNoPriorActivity() Indicates that no relevant activity has occurred in the past.
protected void	handleDeadline(ScopeDescriptor sagaDescriptor, DeadlineMessage<?> deadlineMessage) Handles the given deadlineMessage in the saga described by the given sagaDescriptor.
protected void	handleInSaga(EventMessage<?> event) Handles the given event in the scope of a Unit of Work.
<I> I	registerCommandGateway(Class<I> gatewayInterface) Creates a Command Gateway for the given gatewayInterface and registers that as a resource.
<I> I	registerCommandGateway(Class<I> gatewayInterface, I stubImplementation) Creates a Command Gateway for the given gatewayInterface and registers that as a resource.
FixtureConfiguration	registerDeadlineDispatchInterceptor(MessageDispatchInterceptor<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.
FixtureConfiguration	registerDeadlineHandlerInterceptor(MessageHandlerInterceptor<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.
FixtureConfiguration	registerFieldFilter(FieldFilter fieldFilter) Registers the given fieldFilter, which is used to define which Fields are used when comparing objects.
FixtureConfiguration	registerHandlerDefinition(HandlerDefinition handlerDefinition) Registers handler definition within this fixture.
FixtureConfiguration	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.
void	registerResource(Object resource) Registers the given resource.
FixtureConfiguration	registerStartRecordingCallback(Runnable onStartRecordingCallback) Registers a callback to be invoked when the fixture execution starts recording.
void	setCallbackBehavior(CallbackBehavior callbackBehavior) Sets the instance that defines the behavior of the Command Bus when a command is dispatched with a callback.
WhenAggregateEventPublisher	whenAggregate(String aggregateIdentifier) Use this method to indicate that an aggregate with given identifier should publish certain events, while recording the outcome.
FixtureExecutionResult	whenPublishingA(Object event) Use this method to indicate an application is published, while recording the outcome.
FixtureExecutionResult	whenPublishingA(Object event, Map<String,?> metaData) Use this method to indicate an application is published with given additional metaData, while recording the outcome.
FixtureExecutionResult	whenTimeAdvancesTo(Instant newDateTime) Mimic an elapsed time with no relevant activity for the Saga.
FixtureExecutionResult	whenTimeElapses(Duration elapsedTime) Mimic an elapsed time with no relevant activity for the Saga.
FixtureConfiguration	withTransienceCheckDisabled() Disables the check that injected resources are stored in fields that are marked 'transient'.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

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 Detail

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.

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

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)
                                       throws Exception

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

Throws:

Exception - if an exception happens when the duration elapses

andThenTimeAdvancesTo

public ContinuedGivenState andThenTimeAdvancesTo(Instant newDateTime)
                                          throws Exception

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

Throws:

Exception - if an exception happens when the time advances

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 handler definition within this fixture. This handlerDefinition will replace existing one within this fixture.

Specified by:

registerHandlerDefinition in interface FixtureConfiguration

Parameters:

handlerDefinition - used to create concrete handlers

Returns:

the current FixtureConfiguration, for fluent interfacing

registerDeadlineDispatchInterceptor

public FixtureConfiguration registerDeadlineDispatchInterceptor(MessageDispatchInterceptor<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<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

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

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