[#729] Add Query Testing Support To AxonTestFixture

[theoema]

Add Query Testing Support to AxonTestFixture

Overview

This PR adds query testing capabilities to AxonTestFixture, enabling developers to test queries
with the same fluent given-when-then API used for command testing. The implementation includes a
deterministic auto-await mechanism that ensures read models are fully caught up before queries
execute to ensure results are reliable without putting the eventual consistency inside the developers head.

Problem Statement

Previously, testing queries in Axon Framework 5 required:

• Testing readmodels directly by using assertions.
• Arbitrary delays with (Thread.sleep) or manual awaits to wait for async event processing
• No fluent API for query assertions
• Unreliable tests that could fail due to timing issues if done incorrectly.

Solution

🎯 Deterministic Token-Based Auto-Await

The key innovation is a deterministic waiting mechanism that eliminates timing-related test failures:

fixture.given()
       .events(new StudentNameChangedEvent(studentId, "John Doe", 1))
.when()
       .query(new GetStudentById(studentId))  // ← Automatically waits for processors to catch up before executing
.then()
       .expectQueryResult(expectedResult);

How it works:

1. Before executing the query, fixture waits for all StreamingEventProcessor instances
2. Compares each processor's current tracking token against EventStore.latestToken()
3. Polls every 50ms until all processors reach the head position (using existing polling patterns)
4. Only then executes the query, ensuring read model is up-to-date
5. Default timeout: 5 seconds (configurable, or use Duration.ZERO to skip entirely)

📋 Complete API

Query Execution

.query(payload)                    // Execute with sensible default of 5-second timeout
.query(payload, Duration.ZERO)    // Execute immediately (no wait)
.query(payload, Duration.ofSeconds(10))  // Custom timeout (probably not needed but exists anyway)

Result Assertions

.then()
  .expectResult(expected)                    // Exact match
  .expectQueryResult(expected)               // Wrapper around ExpectResult to make tests more explicit and readable.
  .expectResultSatisfies(result -> { ... })  // Custom assertions
  .expectQueryResultSatisfies(result -> { ... })  // Also an Alias around expectResultSatisfies for explicitness and readability.
  .success()                                 // Assert no exception

Exception Assertions

.then()
  .exceptionSatisfies(ex -> {
      assertThat(ex).hasCauseInstanceOf(StudentNotFoundException.class);
      assertThat(ex.getCause()).hasMessage("Student not found");
  })

Note: Query handler exceptions are wrapped in QueryExecutionException, so use .hasCauseInstanceOf() to
check the actual exception.

Example Usage

@Test
void queryReturnsUpdatedReadModelAfterEventProcessing() {
    var configurer = EventSourcingConfigurer.create()
        .componentRegistry(cr -> cr.registerComponent(
            StudentRepository.class,
            cfg -> new InMemoryStudentRepository()
        ))
        .registerQueryHandlingModule(queryHandlerModule)
        .modelling(modelling -> modelling.messaging(messaging ->
            messaging.eventProcessing(ep ->
                ep.pooledStreaming(ps -> ps.processor(projectionProcessor))
            )
        ));

    var fixture = AxonTestFixture.with(configurer);

    fixture.given()
           .events(new StudentNameChangedEvent("123", "Alice", 1))
    .when()
           .query(new GetStudentById("123"))
    .then()
           .expectQueryResultSatisfies(result -> {
               GetStudentById.Result wrapped = (GetStudentById.Result) result;
               assertThat(wrapped.student().name()).isEqualTo("Alice");
           });
}

Architecture

New Components

RecordingQueryBus

Query bus decorator for testing that records all dispatched queries and their responses.

• Location: org.axonframework.test.fixture
• Records query-response pairs for future assertions
• Provides recorded(), recordedQueries(), responsesOf() methods
• reset() clears recorded queries between test phases

EventProcessorUtils

Utility class for waiting on event processors during testing.

• Location: org.axonframework.test.util
• Method: waitForEventProcessorsToCatchUp(AxonConfiguration, Duration)
• Reusable for future use cases beyond queries
• Any test code needing to wait for event processors can use this utility

AxonTestThenQuery

Implements the Then.Query phase with result and exception assertions.

• Extends AxonTestThenMessage for event/command assertions
• Accepts RecordingQueryBus for future query assertion features
• Uses PayloadMatcher for deep equality checking
• Handles wrapped exceptions (checks .getCause())

AxonTestWhen (Enhanced)

• Added .query() methods to When phase
• Integrated auto-await before query execution
• Null-check for missing query handlers
• Passes RecordingQueryBus to Then phase

Sample Domain

Comprehensive test domain in test/fixture/sampledomain:

• StudentReadModel - Read model record
• GetStudentById - Query with nested Result wrapper
• StudentRepository + InMemoryStudentRepository - Repository pattern with
  thread-safe implementation
• StudentProjection - Event handler with @EventHandler
• StudentQueryHandler - Query handler with @QueryHandler
• StudentNotFoundException - Custom exception

Test Coverage

Six comprehensive tests demonstrate all features:

Test	Scenario
givenEventsWhenQueryThenExpectResult_Success	Events → async processing → query returns result
givenEventsWhenQueryThenExpectResultSatisfies_Success	Custom assertions on result structure
givenNoEventsWhenQueryThenExpectException_Success	Query throws exception (checks wrapped cause)
givenNoEventsWhenQueryThenExpectExceptionWithMessage_Success	Exception with specific message
givenNoEventsWhenQueryThenExpectExceptionSatisfies_Success	Custom exception assertions
givenEventsWhenQueryThenSuccess_Success	Success assertion (no exception)

All tests use PooledStreamingEventProcessor with async processing to verify the deterministic mechanism.

Breaking Changes

None. This is a pure addition to the existing AxonTestFixture API.

Migration Guide

No migration needed. Existing tests continue to work unchanged. New query testing is opt-in.

Related Issues

#729

Commits

• 48e8731 Implement deterministic query testing with token-based auto-await mechanism
• e90b19c Implement auto-await mechanism for query testing with delay-based approach
• d3558ea Add query testing support to AxonTestFixture

[theoema]

Hey @abuijze @smcvb @MateuszNaKodach @zambrovski! Does this resemble the direction you wanted to go for query testing? I was thinking of adding subscriptionQuery testing aswell but wanted to check in with you before proceeding.

[smcvb]

I did a rough skim of what you've provided, @theoema. Rough, mainly, because the AF-team still wants (and needs) to discuss what the API is going to be.

Although there's nothing wrong with providing a new API to us in a PR, the test fixture flow is already quite different from what it was in AF2, AF3, and AF4 with the current setup.

Next, the issue you attached it too, called projection testing, is not strictly scoping in query handler validation. It suggests we have a means to validate "the activities" performed by an event handler (and if not, I need to update the description). Again, not wrong to add queries in the mix, as we want verification for those as well.

Long story short, we're not suited yet to approve or request changes on this PR. Once we've had more discussions on the angle to take for projection testing and query handler validation, we'll be sure to update this PR too.

[smcvb]

If the returned MessageStream is based on a Publisher/Flux, I think it will become an issue to collect everything.

[smcvb]

I am wondering whether the expect operations should be a reflection of the event and command versions. Query responses can be singular, plural, directly returned, async, or reactive. Whether that should be reflected is up for debate still. Differently put, we have not started the design sessions for this in the AF-team.

[MateuszNaKodach]

Yes, I think this is the main issue to discuss here - how to support ALL our query types.

[theoema]

@smcvb @MateuszNaKodach I hear you. I could do some research on how to better support reactive MessageStreams. As for the supporting of ALL query types I guess it would be beneficial to break it down what we would like the API to look like for different query types. For example I think it makes a lot of sense to have the API for subscriptionQueries to be:

given()
.subscriptionQuery(query)
.when()
.events(events)
.then()
.expect(initialResult(result)
.and()
.expectUpdate(update).

Which is completely different from the api in this PR, so I think it would be hard to group ALL query types under one single API. I would assume that the best course of action is to put this on hold until you guys have agreed on the future of this API. I'm sure some of the stuff in this PR is still usable either way.

[smcvb]

Setting this PR to milestone 5.2.0, as we do not have sufficient time to round of this contribution before our foreseen release date of 5.1.0.