Testing Aggregates and Sagas with Message Flows

Testing Aggregate, Saga in PHP
On top of Messaging Test Support, Ecotone provides abstraction to handle Message Flows.
This is a clean way to define step by step what happens in your system and verify the results. 
Testing with Message Flows, make your code closer to production like execution.
Message Flows are great candidate for writing acceptance tests or testing flow of your Aggregates and Sagas.
Setting up Flow Test
To enable Flow Test Support, as first parameter we pass list of classes we want to resolve for our testing scenario, this can be aggregate, saga or any class containing Ecotone's attributes.
$testSupport = EcotoneLite::bootstrapFlowTesting([User::class]);
For more details on how to set up EcotoneLite for the different test scenario, read introduction chapter Testing Messaging.
Testing Aggregate or Sagas
It does not matter, if we test Saga or Aggregate, as the case will looks similar.
So as an example, let's take Aggregate that looks like this:
#[Aggregate]
final class User
{
    use WithEvents;
​
    public function __construct(
        #[Identifier] private UuidInterface $userId,
        private string $name,
        private Email $email,
        private PhoneNumber $phoneNumber,
        private $isBlocked = false,
        private $isVerified = false
    ) {
        $this->recordThat(new UserWasRegistered($this->userId, $this->email, $this->phoneNumber));
    }
​
    #[CommandHandler]
    public static function register(RegisterUser $command): self
    {
        return new self(
            $command->getUserId(),
            $command->getName(),
            $command->getEmail(),
            $command->getPhoneNumber()
        );
    }
​
    #[CommandHandler("user.block")]
    public function block(): void
    {
        $this->isBlocked = true;
    }
    
    #[CommandHandler("user.verify")]
    public function verify(VerifyUser $command): void
    {
        $this->isVerified = true;
    }
​
    public function isBlocked(): bool
    {
        return $this->isBlocked;
    }
}
When we've our Ecotone Lite set up, we may start using flow testing:
public function test_registering_user()
{
    $userId = Uuid::uuid4();
    $email = Email::create("[email protected]");
    $phoneNumber = PhoneNumber::create("148518518518");
​
    // 1. Comparing published events after registration
    $this->assertEquals(
        [new UserWasRegistered($userId, $email, $phoneNumber)],
        // 2. Running Message Flow Test support
        $testSupport
            ->sendCommand(new RegisterUser($userId, "johny", $email, $phoneNumber))
            ->getRecordedEvents()
    );
}   
1.We set up our expected event as outcome of running RegisterUser Command.
2.Then we can make use of Flow Support to send an Command and get event that was recorded as outcome.
You may send multiple command and chain them together, to build flow that you would like to test.
Verifying Aggregate's State
In cases when you're not using Event Sourced Aggregate, you may want to test state of the aggregate. We work only with high level API which are commands and we don't have direct access to Aggregate, Ecotone however exposes a possibility to fetch aggregate inside the flow.
$this->assertTrue(
    $testSupport
        ->sendCommand(new RegisterUser($userId, "johny", $email, $phoneNumber))
        // 1. Command with routing key
        ->sendCommandWithRoutingKey("user.block", metadata: ["aggregate.id" => $userId])
        // 2. Fetching aggregate
        ->getAggregate(User::class, $userId)
        // 3. Calling aggregate method
        ->isBlocked()
);
1.This Command Handler was registered by routing key without Command. With Flow support we may call Buses using routing key, and to tell which aggregate we want to call, we may use aggregate.id metadata.
2.Then we fetch given aggregate by id
3.And after that we can call method on aggregate that we've fetched
If you mark your query method with QueryHandler attribute it becomes part of the flow, and we don't need to add ->addAggregateUnderTest(User::class) and we may write following test instead:
#[QueryHandler("user.isBlocked")]
public function isBlocked(): bool
{
    return $this->isBlocked;
}
$this->assertTrue(
    $testSupport
        ->sendCommand(new RegisterUser($userId, "johny", $email, $phoneNumber))
        ->sendCommandWithRoutingKey("user.block", metadata: ["aggregate.id" => $userId])
        ->sendQueryWithRouting('user.isBlocked', metadata: ["aggregate.id" => $userId])
);
Testing Communication between Aggregates and Sagas.
With Ecotone Lite you may create full acceptance tests, just add classes that should be used in your test scenarios and let Ecotone glue everything together.
public function test_success_verification_after_registration()
{
    $testSupport = EcotoneLite::bootstrapFlowTesting(
    // 1. We are resolving User aggregate and Verification Process Saga
        [User::class, VerificationProcess::class],
        enableAsynchronousProcessing: [
            SimpleMessageChannelBuilder::createQueueChannel("asynchronous_messages", true)        
        ]
    );
​
    $userId = Uuid::uuid4();
​
    $this->assertEquals(
        [['user.block', $userId->toString()]],
        $testSupport
            ->sendCommand(new RegisterUser($userId, "John Snow", Email::create('[email protected]'), PhoneNumber::create('148518518518')))
            ->discardRecordedMessages()
            ->releaseAwaitingMessagesAndRunConsumer("asynchronous_messages", 1000 * 60 * 60)
            ->getRecordedCommandsWithRouting()
    );
}
For given scenario you may add set of classes that should be used in this test.
You may include Interceptors, Converters, too. 

In general all your Ecotone's production code will work in your test scenarios.
This ensures tests will be as close to production as it's possible.
Testing with Real State-Stored Repository
By default Ecotone Lite provides for testing purposes In Memory Repositories.
If you want to run your test against real database, you may disable this behaviour and provide your own repository.
$testSupport = EcotoneLite::bootstrapFlowTesting(
// 1. We are resolving User aggregate and Verification Process Saga
    [User::class, UserRepository::class],
    [UserRepository::class => $this->container->get(UserRepository::class)],
    addInMemoryStateStoredRepository: false
);
You may also disable Event Sourced Repository:
addEventSourcedRepository: false
Testing Messaging
Testing Event Sourcing Applications
Last modified 1mo ago