Add assertion support on `@EventSourcedEntity` in the `AxonTestFixture`

[theoema]

When Event Modeling we frequently model automations, and when making specifications for automations we typically do it the same way we specify state views, and specify state changes. By defining Given (events) Then (readmodel), and Given (events) When (command), Then (event(s)).

Automations are typically implemented as a readmodel that is streaming to or being polled by a concurrency-limited / single-threaded processor. But Axon Framework 5 introduced a different way of implementing automations, that introduces significant concurrency benefits.

We dont want our implementation details to change the way we model, so that got me thinking about how to create automations in AF5 in a way that maps really cleanly to the specifications. Now I've also been playing a lot with static codegen from my event models into AF5 code, and one of the best features is being able to statically generate tests from specifications with the help of the AxonTestFixture. Having those tests in place is a real success factor when it comes to letting AI implement slices. But when I generate automations I found myself needing to statically generate "readmodel assertions" on @EventSourcedEntity classes.

Heres how I currently do it:

fixture.given()
       .event(new StudentCreatedEvent("student-1", "Alice"))
       .then()
       .events(new StudentNameChangedEvent("student-1", "Bob"))
       .expect(config -> {
           var stateManager = config.getComponent(StateManager.class);
           var uowFactory = config.getComponent(UnitOfWorkFactory.class);
           var processingContext = uowFactory.create().processingContext();
           var student = stateManager.loadEntity(Student.class, "student-1", processingContext).join();
           assertThat(student.name()).isEqualTo("Bob");
       });

But I think that the test fixture would benefit from a "cleaner" api regarding this, something like this:

fixture.given()
       .event(new StudentCreatedEvent("student-1", "Alice"))
       .then()
       .events(new StudentNameChangedEvent("student-1", "Bob"))
       .entity(Student.class, "student-1", student -> {
           assertThat(student.name()).isEqualTo("Bob");
       });

Would love to know what you guys think, I could definitely make a PR for it, but I wanted to discuss it first.

[MateuszNaKodach]

Hi Theo, I'm currently working on my own workflow for exactly what you described with the AI and code generation from Event Modeling (and I'm exploring different tools, thanks to this message I just discovered your eventmodeler project, I'd be happy to meet with you and discuss what your doing and how Axon Framework may be better incorporated into this stuff - I'm pretty sure it's the feature of development with AI, Spec-Driven done right).
Thanks for being so active in the Axon community and for your PR contributions!

Regarding your AxonTestFixture question — it's not something we can't do, but personally I wouldn't test this way. That said, maybe I'm missing something, and I'd love to hear more about your reasoning.

My chain of thought is as follows:
When you write tests, you care about behavior, which is defined by messages - events and commands.

Entities and state exist only to make the right decisions based on previous events and to produce accurate new events (while handling a command). If you always need to check certain conditions before publishing an event in response to a command — that's what state is for, but the state itself is an implementation detail.

So my question is: why do you want to assert on state when doing event sourcing? State is something derived from events — on the write side it's essentially a projection with a consistency boundary. I think we shouldn't cement entity shapes in tests. Keep them private per slice, don't leak them into the test API. You can fulfill the same behavioral contract with many different state representations.

For example: if there's a rule that a student can't change their name to the name they already have — you show that in the Given-When-Then specification in Event Modeling. The test verifies the behavior through events (then NOTHING or exception), not through state inspection.
For automations it's the same — I don't care about the internal state or the "todo list" used behind the scenes. The outcome is what matters, and the tests should give us freedom to change the internals. The messages are what we care about, not the state.
Of course, we can add this to the fixture API if there's a compelling use case — I'd just like to understand more about where state assertions become necessary in your workflow.

Please let me know what do you think.

PS.
Recently there was even a discussion about using Read Models in GWTs for projections on the Event Modeling discord, you can find it here: https://discord.com/channels/1139074016448098375/1475542521986940960/1475841760574836957

[theoema]

Hey @MateuszNaKodach thank you for the quick response and kind words. As for Eventmodeler, I have been planning on making a "introduction to eventmodeler" style video and sending it to the entire Axon team, I just have had to get it to a "stable state" before doing so. You can try it out right now at eventmodeler.com but I'm sure some documentation would go a long way when it comes to actually using the tool.

As for this issue, I'll try my best to make my reasoning a little clearer. When we model an "automation" in our systems, I typically see this:

Some people like to split automations into two slices. My personal preference is to tackle it as one slice, that allows me to keep all slices fully package private in the implementation.

Now when it comes to making specifications for this/these slices. You typically see specifications like this for the "read side".

Now when translating the model to code. I found that this was the most natural way to do it:

 @EventSourced(idType = ReadModel.Id.class)
  record ReadModel(
      UUID courseId,
      UUID teacherId,
      int courseCapacity,
      int enrolledStudents,
      boolean shouldNotify
  ) {
      record Id(UUID courseId) {}

      @EntityCreator
      static ReadModel create() {
          return new ReadModel(null, null, 0, 0, false);
      }

      @EventCriteriaBuilder
      static EventCriteria resolveCriteria(Id id) {
          return EventCriteria
              .havingTags(Tag.of("courseId", id.courseId().toString()))
              .andBeingOneOfTypes(
                  CourseRegistered.class.getName(),
                  CourseCapacitySpecified.class.getName(),
                  StudentEnrolled.class.getName(),
                  TeacherNotified.class.getName()
              );
      }

      @EventSourcingHandler
      ReadModel evolve(CourseRegistered event) {
          return new ReadModel(event.getCourseId(), event.getTeacherId(), courseCapacity, enrolledStudents, false);
      }

      @EventSourcingHandler
      ReadModel evolve(CourseCapacitySpecified event) {
          return new ReadModel(courseId, teacherId, event.getCapacity(), enrolledStudents, event.getCapacity() - enrolledStudents <= 3);
      }

      @EventSourcingHandler
      ReadModel evolve(StudentEnrolled event) {
          var newCount = enrolledStudents + 1;
          return new ReadModel(courseId, teacherId, courseCapacity, newCount, courseCapacity - newCount <= 3);
      }

      @EventSourcingHandler
      ReadModel evolve(TeacherNotified event) {
          return new ReadModel(courseId, teacherId, courseCapacity, enrolledStudents, false);
      }
  }

  @Component
  class Processor {

      @EventHandler
      void handle(StudentEnrolled event, ProcessingContext context) {
          var stateManager = context.component(StateManager.class);
          var commandDispatcher = context.component(CommandDispatcher.class);

          var readModel = stateManager.loadEntity(
              ReadModel.class,
              new ReadModel.Id(event.getCourseId()),
              context
          ).join();

          if (!readModel.shouldNotify()) {
              return;
          }

          commandDispatcher.send(new Command(readModel.courseId(), readModel.teacherId()));
      }
  }

So when I am playing around with code generation from the model. Its really helpful to be able to turn the eventmodel specifications directly into real tests, testing the actual application. Because it naturally gives guidelines to any AI agent working on implementing the slice.

So I've started statically generating tests that look like this:

 @Test
      @DisplayName("Enrollment increments count")
      void enrollmentIncrementsCount() {
          var courseId = UUID.randomUUID();
          var teacherId = UUID.randomUUID();
          var studentId = UUID.randomUUID();

          fixture.given()
              .events(
                  new CourseRegistered(courseId, teacherId),
                  new CourseCapacitySpecified(5, courseId),
                  new StudentEnrolled(courseId, studentId)
              )
              .then()
              .await(then -> then.expectAsync(config -> {
                  var uowFactory = config.getComponent(UnitOfWorkFactory.class);
                  var uow = uowFactory.create();
                  return uow.executeWithResult(ctx -> {
                      var stateManager = ctx.component(StateManager.class);
                      return stateManager.loadEntity(
                          ReadModel.class,
                          new ReadModel.Id(courseId),
                          ctx
                      ).thenAccept(readModel -> {
                          assertEquals(1, readModel.enrolledStudents());
                          assertFalse(readModel.shouldNotify());
                      });
                  });
              }));
      }

Which works great. Pairing this together with tests for the command dispatching like this:

@Test
  @DisplayName("Teacher is notified when only 3 spots left")
  void teacherIsNotifiedWhen3SpotsLeft() {
      var courseId = UUID.randomUUID();
      var teacherId = UUID.randomUUID();

      fixture.given()
          .events(
              new CourseRegistered(courseId, teacherId),
              new CourseCapacitySpecified(5, courseId),
              new StudentEnrolled(courseId, UUID.randomUUID())
          )
          .when()
          .event(new StudentEnrolled(courseId, UUID.randomUUID()))
          .then()
          .await(then -> then.commandsSatisfy(commands -> {
              var notifyCommands = commands.stream()
                  .map(CommandMessage::payload)
                  .filter(Command.class::isInstance)
                  .map(Command.class::cast)
                  .filter(cmd -> cmd.courseId().equals(courseId))
                  .toList();

              assertEquals(1, notifyCommands.size());
              assertEquals(teacherId, notifyCommands.get(0).teacherId());
          }));
  }

We really get great coverage for both the "readmodel function" and the "processor function" completely statically generated from the eventmodel specifications. Depending on the automation there may also be specifications defining the command side behaviour with typical GWTs.

As you see I essentially ended up treating the State entity in automations like you would treat a standard readmodel. The only differences really are that the readmodel is projected at query time and that we keep the consistency marker in mind when executing the command. So I would like to make the case that a State Entity doesnt necessarily need to be a decision model. It can actually serve the function of being a Readmodel, just with a little different implementation details. If we pair this mode of thinking with your great proposal of separating sourcing criteria and append criteria, we get SIGNIFICANT concurrency benefits when it comes to automations without sacrificing consistency.

So in conclusion I think that strictly separating the concept/usecase of a readmodel/projection and a State Entity might be a mistake, in DCB they're really not that different after all.

This comment may have been a mess, but I hope it gives some clarity as to my thinking and why I introduced this issue. Let me know what you think. And lets take that call sometime.

[MateuszNaKodach]

It's not messy at all, I understand :) Thanks for the explanation.

My 5 cents:

Regarding your Event Modeling approach — there are different styles, so I'm not judging here. I'd like to mention that I treat the whole "automation" as a single slice as well. Partly because of that, I don't validate the read model separately, since it's something "intermediate." My GWTs in this case would look like Given (events) Then (command) — I'd skip testing the read model on its own, because it's part of the same slice. So no separate specifications, just the test you showed for command dispatching. It already covers the read model, because the read model is what's used to decide when the command should be sent.

But...

OK, I agree that supporting what you asked for would be beneficial. Where I think it's beneficial: sometimes we may use an EventSourcedEntity as a read model (as you do), not just for automations, but also when we want to allow "read-your-own-writes" for the user. It's always a choice — whether we build a read model stored somewhere, or build it "on-demand" as a "read-only" entity. In that case though, we should probably be checking the query result instead (without exposing the entity). I know you opened the PR for that — I think we need to prioritize discussing it, because it's relevant here. We have different types of queries, and we need to figure out how to support all of them in the test fixtures. In your example you don't have a query for the read model, because it's only readable within the slice — there's no API for it. IMO that's another argument to keep it private and not expose it in tests.

So this could also support your style of specifications and testing. But do you really see the benefit of enrollmentIncrementsCount over teacherIsNotifiedWhen3SpotsLeft? To me, the latter already includes the former, without exposing the details of the entity used.

Please let me know what you think. If you feel that what I've written doesn't change your Event Modeling style and you still want to keep doing it this way — I think it won't harm us to have it, but it is of course more to maintain. I don't want to block you, and I really appreciate your initiative! :)

This is my personal opinion — I haven't discussed it with the team yet, but I'll try to bring it up soon (though we're in a rush to release 5.1.0, so it's not the highest priority).

[theoema]

Hey @MateuszNaKodach !

So this could also support your style of specifications and testing. But do you really see the benefit of enrollmentIncrementsCount over teacherIsNotifiedWhen3SpotsLeft? To me, the latter already includes the former, without exposing the details of the entity used.

I can agree with you that the "value of the test" isn't really anything noticable. I think the real value comes from aligning the code with the model. While the typical behaviour of a automation can be described by defining Given (events) Then (command). But specifications are typically given on a slice level, and I know a lot of people in the space that treat automations as two slices. And I think thats when Given (events) Then (command) becomes problematic. Because its kind of describing the behaviour of both slices. I dont know though, I feel like its perhaps something we could ask the community about in discord.

[MateuszNaKodach]

@theoema We discussed it internally.
Surprisingly (I didn't expect that) there was a consensus that we recommend to keep the entity state internal, so do not expose it in tests - but it's may be considered as a style you'd like to follow.

Whereas framework is not just for us and should not encorce certain style (of course we need to find a sweet spot between flexiblity and maintenance). Personally I would define specifications per slice, and treat the whole automation as a slice, as you - then the alignement with the model is kept.

But if you still think it's really needed we can have it in the framework along with some recommendations in the docs.
So fell free to preapre it in PR :)

[smcvb]

Loving write down, @theoema and @MateuszNaKodach; much appreciated and clear!
Given the scope at hand, I added milestone 5.3.0 to this issue. That would place it in the third quarter of this year.
That is, however, for our planning. If you, @theoema, or anybody else would want to provide a PR for this, that'll change the milestone attached.

Besides that, let me add some things I was thinking when reading this thread:

• I would hope Axon's inject entity logic can work for any kind of entity. Whether that's an old fashioned aggregate, as slice-based state object for decisions, automation state, or a read model. That is, in part, why I am so pleased with the current Repository structure and inject-logic for handlers
• State-based validation used to exist in AF4, although essentially for state-based aggregates. However, that support was requested years back, so should simply return. We have just not prioritized that over the other tasks at hand.
• Although I am on the same page as @MateuszNaKodach on whether this is the way to go, I fully agree with him that it comes down to taste. Axon Framework should support both; we will just give our preferred approach in the documentation, clarifying when to use which.

[theoema]

Thanks for you input @smcvb. I agree with you and @MateuszNaKodach that it truly comes down to taste. I definitely agree with @MateuszNaKodach point that having 50 tests testing the "automation readmodel" basically does the same thing as having 3 tests validating if the command is sent or not. When it all boils down, its the behaviour we want to validate. But I think that the broader Event Modeling community specifies automations in a certain way, and implements them a certain way, and I think that the fact that you're implementing your event model in AF5 shouldn't impact the way you model. So if you model your automations as two slices, and define your specifications on each slice, then we should make it as easy as possible to turn that model into code and tests, without you needing to adjust your model.