public class MyCommandComponentTest {

    private FixtureConfiguration fixture;

    @Before
    public void setUp() {
        fixture = Fixtures.newGivenWhenThenFixture(); 
        MyCommandHandler myCommandHandler = new MyCommandHandler(
                              fixture.createGenericRepository(MyAggregate.class)); 
        fixture.registerAnnotatedCommandHandler(myCommandHandler); 
    }

    @Test
    public void testFirstFixture() {
        fixture.given(new MyEvent(1)) 
               .when(new TestCommand())
               .expectVoidReturnType()
               .expectEvents(new MyEvent(2));
    }
}

During the configuration phase, you provide the building blocks required to execute the test. Specialized versions of the event bus, command bus and event store are provided as part of the fixture. There are getters in place to obtain references to them. The repository and command handlers need to be provided. This can be done using the registerRepository and registerCommandHandler (or registerAnnotatedCommandHandler) methods. If your aggregate allows the use of a generic repository, you can use the createGenericRepository method to create a generic repository and register it with the fixture in a single call. The example above uses this feature.

If the command handler and repository are configured, you can define the "given" events. These events need to be subclasses of DomainEvent, as they represent events coming from the event store. You do not need to set aggregate identifiers of sequence numbers. The fixture will inject those for you (using the aggregate identifier exposed by getAggregateIdentifier and a sequence number starting with 0.

Alternatively, you may also provide commands as "given" scenario. In that case, the events generated by hose commands will be used to event source the Aggregate when executing the actual command under test.

The execution phase allows you to provide a command to be executed against the command handling component. That's all. Note that successful execution of this command requires that a command handler that can handle this type of command has been configured with the test fixture.

The last phase is the validation phase, and allows you to check on the activities of the command handling component. This is done purely in terms of return values and events (both stored and dispatched).

The test fixture allows you to validate return values of your command handlers. You can explicitly define an expected void return value or any arbitrary value. You may also express the expectancy of an exception.

The other component is validation of stored and dispatched events. In most cases, the stored and dispatched are equal. In some cases however, you may dispatch events (e.g. ApplicationEvent) that are not stored in the event store. In the first case, you can use the expectEvents method to validate events. In the latter case, you may use the expectPublishedEvents and expectStoredEvents methods to validate published and stored events, respectively.

There are two ways of matching expected events.

The first is to pass in Event instances that need to be literally compared with the actual events. All properties of the expected Events are compared (using equals()) with their counterparts in the actual Events. If one of the properties is not equal, the test fails and an extensive error report is generated.

The other way of expressing expectancies is using Matchers (provided by the Hamcrest library). Matcher is an interface prescribing two methods: matches(Object) and describeTo(Description). The first returns a boolean to indicate whether the matcher matches or not. The second allows you to express your expectation. For example, a "GreaterThanTwoMatcher" could append "any event with value greater than two" to the description. Descriptions allow expressive error messages to be created about why a test case fails.

Creating matchers for a list of events can be tedious and error-prone work. To simplify things, Axon provides a set of matchers that allow you to provide a set of event specific matchers and tell Axon how they should match against the list.

Below is an overview of the available Event List matchers and their purpose:

For convenience, a few commonly required Event Matchers are provided. They match against a single Event instance:

Below is a small code sample displaying the usage of these matchers. In this example, we expect two events to be stored and published. The first event must be "aThirdEvent", and the second "aFourthEventWithSomeSpecialThings". There may be no third event, as that will fail against the "andNoMore" matcher.

fixture.given(new FirstEvent(), new SecondEvent())
       .when(new DoSomethingCommand(fixture.getAggregateIdentifier()))
       .expectEvents(exactSequenceOf(
           aThirdEvent(),
           aFourthEventWithSomeSpecialThings(),
           andNoMore()
       ));

AnnotatedSagaTestFixture fixture = new AnnotatedSagaTestFixture(InvoicingSaga.class); 
fixture.givenAggregate(invoiceId).published(new InvoiceCreatedEvent()) 
       .whenTimeElapses(Duration.standardDays(31)) 
       .expectDispatchedCommandsMatching(Matchers.listWithAllOf(aMarkAsOverdueCommand()));  

Often, Sagas will interact with external resources. These resources aren't part of the Saga's state, but are injected after a Saga is loaded or created. The test fixtures allows you to register resources that need to be injected in the Saga. To register a resource, simply invoke the fixture.registerResource(Object) method with the resource as parameter. The fixture will detect appropriate setter methods on the Saga and invoke it with an available resource.

The test fixture tries to eliminate elapsing system time where possible. This means that it will appear that no time elapses while the test executes, unless you explicitly state so using whenTimeElapses(). All events will have the timestamp of the moment the test fixture was created.

Having the time stopped during the test makes it easier to predict at what time events are scheduled for publication. If your test case verifies that an event is scheduled for publication in 30 seconds, it will remain 30 seconds, regardless of the time taken between actual scheduling and test execution.

You can also use the StubEventScheduler independently of the test fixtures if you need to test scheduling of events. This EventScheduler implementation allows you to verify which events are scheduled for whch time and gives you options to manipulate the progress of time. You can either advance time with a specific Duration, move the clock to a specific DateTime or advance time to the next scheduled event. All these opertaions will return the events scheduled within the progressed interval.