How to test event choreography?

[danstooamerican]

Hi,

I was wondering how I can write integration tests that verify a business process that is driven by application events (a saga essentially).
For example, the creation of a new account triggers an invitation. After the invitation is accepted the account is activated.
The corresponding events are AccountCreationInitiated, InvitationAccepted, and AccountActivated.

I want to be able to write a test, that:

1. Creates a new account
2. Gets hold of the invitation (ideally through the published event because the invitation process is handled by another module)
3. Accepts the invitation
4. Verifies that AccountActivated was published

I am able to write steps 1, 3, and 4 but step 2 is tricky. The problem is, that step two is performed by an @ApplicationModuleListener . This event handler is never called inside my test (it works if I start my application normally). I think it is because it waits for the transaction to finish but this never happens inside my test I think. The test runs fine if I replace the @ApplicationModuleListener with @EventHandler.

I am also not sure how the @Async annotation inside @ApplicationModuleListener interferes with my tests and how to reliably test these event handlers. I already added delays and timeouts to my verify calls which did not change the behavior.

Lastly, I would like to know if it makes sense to publish events inside my test methods to see how my system behaves.

How should I go about writing my integration tests?

[odrotbohm]

That's an interesting question. The natural scope in focus for Spring Modulith is indeed a module in isolation. That's what our integration test support is centered around. That said, there's also the PublishedEvents abstraction (docs still missing 😬) that can be used to capture application events published during the execution of a test case. With e.g. Awaitility, that could wait until the PublishedEvents instance has seen the AccountActivated event.

I wouldn't mind hearing about the results you can achieve with that. PublishedEvents' API is currently pretty basic. I can imagine we might want to add a few more dedicated methods like ….hasSeenEventOfType(Class<?>) so that you could end the Awaitility pipeline with ….until(() -> events.hasSeenEventOfType(…)).

[odrotbohm]

That is a good point. I think it would be just fine to start with the transactional event publication, as that indeed requires less knowledge about how to start the flow. You just kick it off, defining which state your module is in and which event actually stimulates it. That's very much in line with the encapsulating nature of a module.

I was wondering if, at the end, we might come up with some API that makes formulating these tests a bit less cluttered. Currently, you have to interact with TransactionOperations, ApplicationEventPublisher and Awaitility all separate from each other, get the former two injected into your test case. Maybe we can use the AssertablePublishedEvents to expose a factory method that would allow a fluent setup of transactional event publication, await condition plus a final code block to verify assertions once the condition has been met. Similar to the way assertions work in AssertJ, but slightly more high-level for the setup phase.

To drive that, experiments like yours are really valuable!

[danstooamerican]

That is exactly what I was thinking about. I worked with Axon Framework in the past which offers very nice testing support.
You might want to have a look at their documentation to get some inspiration. I especially like the given, when, then API and the helper functions for assertions (this could use AssertJ internally). The assertions of the PublishedEvents feel quite cumbersome at the moment because I always have to define the Conditions. I find their clear separation into Commands, Queries, and Events very helpful. We use Modulith with this idea in the back of our minds and it works great so far.

They call their test helpers TestFixtures which I think aptly describes the concept. I would personally prefer something along this terminology over PublishedEvents.

[odrotbohm]

I don't think we're going to go anywhere near what Axon provides. We're not in the business of CQRS. All we care about is events, as they allow us to decouple the modules. Whether you introduce commands to trigger functionality or just invoke methods on beans listening to these events is not something we care about. I guess if you want to buy into CQRS (which is perfectly fine) than you'd just go with a framework that supports that. There's no real point in us trying to replicate what's already existing in a well-supported and -designed way in Axon. Also, from what I hear, the additional technical complexity of those frameworks is also something that puts people off. In the end, I guess it's a tradeoff.

I guess we could add a couple of convenience methods to AssertablePublishedEvents to, for example, expect event instances matching, setting up waiting conditions etc.

[danstooamerican]

I did not mean to imply that Modulith should replicate Axon or any CQRS features. Those patterns have its place and purpose. I specifically did not choose Axon for our project because I needed something more lightweight but also supported an event driven programming style. So far Modulith has been minimally invasive and very easy to work with. We enjoy working with Modulith. What I meant to say is that the Axon TestFixtures are something I really enjoyed working with so maybe some ideas can be borrowed.

@Test
public void testName() {
    fixture.given(() -> {
        // put some logic to be executed during the Arrange step of the test (i.e., call module interface)
    })
    .when(() -> {
        // Act step of the test
     })
     // .whenEventIsPublished(new SomethingImportantHappened(...)) as a helper to publish events
     .assertThat(...) // some interface to put asserts
     .expectEvents(new SomethingImportantHappened(....)); // interface to assert event publication
}

That is what I have in mind for an improved PublishedEvents interface.

[odrotbohm]

I just filed #136 and pushed a first draft of an API. A test method parameter type of Scenario is now available to build integration testing descriptions. Would love to hear what you think.