`AxonTestFixture`: Automatic event processor catch-up at phase transitions

[MateuszNaKodach]

Feature Description

Introduce automatic waiting for StreamingEventProcessor catch-up at each phase transition in AxonTestFixture, so that tests with streaming processors no longer need explicit await() calls for basic processor-driven assertions.

A new EventProcessorCatchUpWaiter (or different name - similar of what it's here) utility captures the event store's head TrackingToken once (or in the loop - consider pros and cons), then polls with Awaitility until every registered StreamingEventProcessor tracking token covers that head. This is invoked automatically at three transition points:

1. given() → when() — ensures Given-phase events are fully processed before the When command executes (critical when processors build read models consumed by command handlers).
2. given() → then() — ensures Given-phase processor side effects (e.g., dispatched commands) are visible before assertions.
3. when.xxx() → then() — ensures When-phase side effects (command-handler-published events processed by streaming processors) are visible before assertions. Applies to when().command(), when().event(), and when().nothing() paths.

The waiting uses a snapshot-outside strategy: the head token is captured once before the Awaitility loop starts. This guarantees deterministic convergence (fixed target) and avoids infinite loops from cascading automation chains. Tests with deep cascade chains (event → processor → command → handler → event → ...) can still use await() for those secondary effects.

Waiting is ON by default and configurable via Customization (it's an idea, you can design different API for configuration):

• disableProcessorWait() — disables auto-waiting entirely
• processorWaitTimeout(Duration) — adjusts the per-transition timeout (default: 5 seconds)

If no EventStore is available (EventBus-only setup) or no StreamingEventProcessor instances are registered, the waiter returns immediately with no overhead.

Current Behaviour

Streaming event processors run asynchronously, so processor-driven side effects (commands dispatched by event handlers, read models built from events) are not guaranteed to be visible at phase transitions. Tests must use await() for any assertion that depends on processor output:

// Must use await() — processor may not have dispatched the command yet
fixture.given()
       .events(new StudentNameChangedEvent("s1", "Alice", 1))
       .then()
       .await(r -> r.commands(new SendNotificationCommand("s1", "Name changed")));

// Flaky — read model built by processor may not be ready when When command executes
fixture.given()
       .events(new DwellingBuiltEvent("d1", "angel"))
       .when()
       .command(new ProclaimWeekSymbolCommand("angel", 3))
       .then()
       .commands(new IncreaseAvailableCreaturesCommand("d1", "angel", 3)); // race condition

Wanted Behaviour

Phase transitions automatically wait for processors to catch up, making await() unnecessary for basic processor-driven assertions:

// No await() needed — processors are caught up before then() asserts
fixture.given()
       .events(new StudentNameChangedEvent("s1", "Alice", 1))
       .then()
       .commands(new SendNotificationCommand("s1", "Name changed"));

// No race condition — read model is guaranteed up-to-date before When command executes
fixture.given()
       .events(new DwellingBuiltEvent("d1", "angel"))
       .when()
       .command(new ProclaimWeekSymbolCommand("angel", 3))
       .then()
       .commands(new IncreaseAvailableCreaturesCommand("d1", "angel", 3));

Users can opt out or adjust timeout via Customization:

// Disable auto-wait
var fixture = AxonTestFixture.with(config, c -> c.disableProcessorWait()); // I'm not sure if it should be general or configurable per phase

// Custom timeout
var fixture = AxonTestFixture.with(config, c -> c.processorWaitTimeout(Duration.ofSeconds(10)));

Possible Workarounds

Use explicit await() calls at every assertion that depends on processor output. This works but is verbose, easy to forget, and produces flaky tests when omitted.

[theoema]

@MateuszNaKodach I like this, it was something I tried tackling when filing that PR you mentioned, but it wasn't very well thought out, I'm sure you guys can come up with something better. Its one of those UX improvements that I think are really nice to have. I think the two things that are unintuitive about the AxonTestFixture is the awaiting, and the conflicts when running tests in parallell. But I'm sure you guys have plans for that as well. Let me know if you need any help with this :)

[theoema]

Hey @MateuszNaKodach @smcvb . This thread actually gave me an idea, you guys probably already thought of this but I'll share it in case you didn't.

As you know, the AxonTestFixture, because it tests your actual application, using actual infrastructure, we run into the issue of isolation between tests, because if not explicitly designed for, the events will accumulate and impact each other. My workaround to this has been to try to make sure the each test gets unique fields and sometimes providing custom filters in the tests to make sure only stuff relevant to the test makes it through.

The other workaround is purging the event store before each test. And while that definitely provides isolation, it has quite a performance impact when running a lot of tests.

But I thought of something this morning that I think would be a cool addition.

What if we provided something along the lines of a TestIsolationConfigurationEnhancer that for each test generates a UUID testId and:

• Registers a TestScopeDispatchInterceptor that adds a metadata value testId to all dispatched messages.

• Registers a TestScopedTagResolver decorator which always adds the testId as a Tag on append.

• Registers a TestScopedEventStorageEngine decorator which intercepts any incoming SourcingCondition and makes sure reads also are scoped to the testId.

• Registers "TestScoped" decorators for the RecordingEventSink, RecordingCommandBus, etc, that scopes all .recorded() calls to the testId

I haven't looked to deeply into the feasibility of this, but I think it could be a pretty good solution for providing isolation between tests even though they're running on the same configuration and infrastructure without impacting test performance and without needing the developer to keep it in their heads.

Let me know what you think, if you like it, perhaps we could discuss it more deeply and see if I can submit a PR for it.

[smcvb]

Curious idea...at first, I though you wanted to discuss you preferred to tests slices of the application.
So, for example, only to test a specific Event Processor or Event Sourced Entity.
For that, the approach will be straightforward due to the way how Axon's Configuration is broken down.

We have the top level Configuration, which we could call the "parent-bucket-of-all-global-components".
This is where the CommandBus, EventStore, QueryBus, converters, and resolvers, mostly life.

When you draft an @EventSourcedEntity, that generates a so called Module.
This Module will become a Configuration in it's own right. With it's own specific fields, but moving up to the parent for global input.

So, these modules (essentially location transparency on the configuration) should allows us to adjust the AxonTestFixture such that you can "just" validate your @EventSourcedEntity or EventProcessor-xyz.

---

That said, that's not what you suggested at all. You're about keeping the entire app in the AxonTestFixture, but ensuring messages become (unit) test specific, right?

[theoema]

@smcvb Correct! I'm well aware that we can specify exactly what parts of the Configuration we want to test and pass just those to the AxonTestFixture, although I will admit this is a little more muddy inside a Spring context than a bare bone setup, but thats beside the point.

The point is that regardless of if I have a AxonTestFixture with per slices configuration or pass the entire AxonConfiguration to the fixture like the @AxonSpringBootTest does underneath the hood. The minute I have more than one test that sources from events that happen to fit into each others sourcing criteria (common especially with statically generated tests) the tests can start impacting each other.

You have a purgeEventsFromAxonserver() method inside AxonServerContainerUtils which technically solves this problem, but it does so by deleting the entire context, recreating it, and then waiting 500ms. That takes at least 500ms (bare minimum, I haven't measured but I would assume its probably closer to 2-3s), and has to be done between every single test, that leads to minutes of wait time for testing just a few slices.

I think that if we could do something along the lines of my suggestions, theres practically no stop time needed between tests, they can just run on the same configuration and same infrastructure but be completely isolated via a tag in the metadata.

[MateuszNaKodach]

@theoema

Do you have some publicly available code of your tests you'd like to share?

I do share my EventStore across tests and don't purge it, and I don't have problems with isolation — you can see an example in this PR:
https://github.com/MateuszNaKodach/HeroesOfDomainDrivenDesign.EventSourcing.DCB.Kotlin.Axon5.Spring/pull/16/changes#diff-bb5c58140808c2c2da11d08fa6c07fa089ed992f80f0ee6cd11c480e23b353d4
in the class AddCreatureToArmySpringSliceTest.

The key thing is — I don't use predefined values for tags. Instead, I always use something unique per test, generally a UUID.

[71 AxonTestFixture tests](https://github.com/MateuszNaKodach/HeroesOfDomainDrivenDesign.EventSourcing.DCB.Kotlin.Axon5.Spring/actions/runs/22931111942/job/66552657376) with a Spring Boot context (+ shared Testcontainers) take just 1m 33s.
I still have some TimeoutExceptions in EventProcessor tests that I need to investigate.

I also test one slice per test (not the whole app), thanks to simple feature flags using app properties in @TestPropertySource. The AxonTestFixture has an instance per test (you need to remember to properly stop it so you don't keep the AxonServerConnection open — or inject it as a Spring Bean using @AxonSpringBootTest, which handles that for you).

But if you don't have a test per slice, there are of course other challenges — for example, you have a command that publishes events, but those events have handlers that may trigger other commands, and so on.

---

Disclaimer: When I was writing the following paragraphs, I thought the idea was the same as "testId" — then I realized it's not. But just to think out loud and maybe provide more input/inspiration, I decided to leave it.

TestId sounds like a solid idea — it resembles what we have in frontend test frameworks to select desired components.

I was thinking about something else as well. We already have causationId and correlationId in metadata. When we publish a message in the WHEN phase, we know its causationId and correlationId. So I was thinking: in the THEN phase assertions, we could say that we only care about messages caused by or correlated with what we did in WHEN. What do you think about that?

---

Back to the testId idea — it sounds promising, because we could filter at the app level, even at the EventStorageEngine. I like it! An additional criterion with a tag unique to each test is a nice idea.

The only thing I'm worried about is that the test setup becomes more and more different from the production application (and we wanted to stay as close as possible). It shouldn't make a difference in general, but there is an additional tag being added.

Also — do you use projections stored in a database? That's the common use case for read models, and even with testId-based filtering around EventSourced-related stuff, we'd still share the same database (without purging it).
What are your thoughts on that? Those ideas are really nice and I'd like to hear your option on this as well.

[theoema]

Hey @MateuszNaKodach , thanks for joining the discussion. I'll be brief as I'm going up in about 6 hours to enter a military exercise.

Thanks for your input. I currently do the exact same thing as you, I make sure all tests have random tags so they don't conflict. It definitely works, but its not what I would call ideal.

I definitely get what you're saying about not straying from a production environment too much, which is valid. You guys obviously put it a lot of thought and work into getting the framework to a place where you can essentially emulate a production environment in the tests, and I get not wanting to stray from that. Thats why I think it would be hard to make this behaviour "default". I do however think that theres space to make this a "opt-in" configuration.

Regarding projections, I do use Postgres most of the time. Now ofcourse, this testId idea wouldn't solve the issue with the database being shared across tests. My current solution is truncating tables after each test. This testId filtering idea could definitely be extended all the way to database filtering, but I think it would be difficult to actually execute on that, because at the end of the day, its the user of the framework that brings that implementation in, it doesn't really make sense for us to try and manage it.