Feature testing a event sourced application

[ametad]

Hi David and Daniel,

First of all, thank you for this great package! Building a Event Sourced application is new for us, but your package and blog is one of the great resources we use to learn about ES.

About testing I see a lot about unit testing, but not so much about feature tests. We are used to write feature tests a lot, because it always seemed to be more efficient: "one test to rule them all" 😉 But we are focusing more on the unit tests as well now. Mainly because to show the value that is gained in every (little) added code. Also to be able to build upon written code with confidence that we do not break things.

Still, we would like to use feature tests as well. Here I get in trouble a little bit, because of how to setup a database with data (fixture), to test a feature that will manipulate this data. In terms of Laravel: how to use factories to produce reusable test data, but now in a Event Sourced application?

How is feature testing be done in ES, where the source of truth is the event store. Can I seed an event store, or a projection before testing? Do we need to take a different approach perhaps?

Greetings 👋

[DanielBadura]

Hello,

Thanks for the kind words, really nice to hear that the blog and the docs are helping you so much!

Yes, the focus is more on unit tests, because event sourcing provides the perfect foundation for writing simple unit tests to fully test the business logic.

Integration tests are of course still important and also absolutely possible. Personally, I only used Laravel’s database seeder once in an ORM project, but that was a long time ago.

What we do is create the prerequisites directly in the test itself for feature/integration tests, then execute the feature, and finally verify whether the result is what we expect. So it’s fully aligned with the given / when / then principle, just like with the unit tests for aggregates / subscriptions (https://github.com/patchlevel/event-sourcing-phpunit).

It would look something like this (examples from a real world symfony app):

bootstrap.php contains the schema setup of the event store:

<?php

declare(strict_types=1);

use App\Shared\Application\Kernel;
use Symfony\Bundle\FrameworkBundle\Console\Application;
use Symfony\Component\Console\Input\ArrayInput;
use Symfony\Component\Dotenv\Dotenv;

require dirname(__DIR__) . '/vendor/autoload.php';

if ($_SERVER['APP_DEBUG']) {
    umask(0000);
}

$args = $_SERVER['argv'];
assert(is_array($args));

if (in_array('--testsuite=unit', $args, true)) {
    return;
}

(new Dotenv())->bootEnv(dirname(__DIR__) . '/.env');

$kernel = new Kernel('test', true);
$kernel->boot();

$application = new Application($kernel);
$application->setAutoExit(false);

$application->run(new ArrayInput(['command' => 'doctrine:database:drop', '--if-exists' => '1', '--force' => '1']));
$application->run(new ArrayInput(['command' => 'doctrine:database:create']));
$application->run(new ArrayInput(['command' => 'doctrine:migration:migrate', '--no-interaction' => '1', '--quiet' => '1']));

$kernel->shutdown();

Base IntegrationTestCase:

abstract class IntegrationTestCase extends WebTestCase
{
    protected static KernelBrowser|null $client = null;

    protected function setUp(): void
    {
        static::$kernel = static::createKernel();
        static::$kernel->boot();

        static::resetSubscriptions();
        Uuid::setFactory(new IncrementalRamseyUuidFactory()); // for better UUID testing, not necessary, but if wanted do this before creating any data
        // static::createStock(); maybe add some base data, but be careful with that: this quickly evolves into a data creep

        static::ensureKernelShutdown();
        static::$client = static::createClient();
    }

    /**
     * @param class-string<T> $id
     *
     * @return T
     *
     * @template T
     */
    protected static function getService(string $id): mixed
    {
        return static::getContainer()->get($id);
    }

    protected static function resetSubscriptions(): void
    {
        $engine = static::getService(SubscriptionEngine::class);
        $engine->setup(skipBooting: true);
    }

    protected static function dispatchCommand(object $command): void
    {
        $commandBus = static::getService(CommandBus::class);
        $commandBus->dispatch($command);
    }

    // more helpful test functions below, e.g. factory methods for different aggregates & entities
}

And the actual test:

final class CartTest extends IntegrationTestCase
{
    public function testCartShowWithoutCart(): void
    {
        $response = self::get('/cart');

        self::assertStatusCode(200);
        self::assertStringNotContainsString('Shipping costs are calculated at checkout.', $response);
    }

    public function testAddCartItemAndShow(): void
    {
        // given
        self::dispatchCommand(new AdjustStockForProduct(ProductId::fromString('basic-sunglasses'), 1));

        // when
        $response = self::get('/product/basic-sunglasses');
        self::$client->submitForm(
            'product-form-submit',
            [
                'color' => 'silver',
                'engraving' => 'Daniel',
            ],
        );

        // then
        self::assertStatusCode(301);
        self::$client->followRedirect();

        self::assertRouteSame('cart_show');
        self::assertStatusCode(200);
        self::assertStringContainsString('Basic Sunglasses', $response);
        self::assertStringContainsString('Quantity 1', $response);
        self::assertStringContainsString('€23.99', $response);
    }
}

You can also add factory methods to the base integration test class for data you need repeatedly, such as a user, for example:
static::createUser('username', 'firstname', /* and more user data */);
Internally, this can also use commands & the command bus to populate the application with data.

One more thing is that a transaction will be spanned with https://github.com/dmaicher/doctrine-test-bundle so after each test the transaction can be rolled back which results into atomic tests due all database changes are reverted.

My tip: always create the data through the business logic. This guarantees that the data arrives in the event store exactly the way it should.

Regarding projections: the subscription engine should always populate them based on the event store.

IIRC we need to port again some feature's we are having in the symfony-bundle here into the laravel integration so that more features of the library are easy accessible when using laravel.

[ametad]

Hi Daniel,

Wow, Thank you for your detailed and clear answer! I'll try to return the favor 👍

Yes, the focus is more on unit tests, because event sourcing provides the perfect foundation for writing simple unit tests to fully test the business logic.

Good to know indeed, the business logic is reflected in the code I understand of DDD. Therefore it is logical to test every detail in a simple unit test. Most ideally when you are building the component that reflects that detail.

Integration tests are of course still important and also absolutely possible. Personally, I only used Laravel’s database seeder once in an ORM project, but that was a long time ago.

A few integration tests can help of course to see everything is working together. I am learning and where I am right now in the process, I think it is handy to let an integration test of the API be a guide (and test) for the consumers of this API. Therefore I need an working example of the input-process-output. What do you think about this?
And btw, no more ORM projects for you, but only Event Sourced projects?

My tip: always create the data through the business logic. This guarantees that the data arrives in the event store exactly the way it should.

This is an eye opener for me! So what you suggest is create the prerequisites for a test with "commands" first, then do the test. Am I following you'd say? Perhaps use a factory of sorts for the input data, but it's better not to save it manually to database. Use the Commands on the Aggregate and let the Projections control the tables for the read-models.

IIRC we need to port again some feature's we are having in the symfony-bundle here into the laravel integration so that more features of the library are easy accessible when using laravel.

Yes please 😄 the Laravel plugin maintained would make me happy! Perhaps some day I can contribute some back.

[ametad]

You are already busy porting new features from the symfony-bundle right? (#28) Thank you for your commitment to this 👍

[DanielBadura]

So what you suggest is create the prerequisites for a test with "commands" first, then do the test.

Yes exactly.

Perhaps use a factory of sorts for the input data, but it's better not to save it manually to database. Use the Commands on the Aggregate and let the Projections control the tables for the read-models.

Yes, you can for sure create helper methods in the tests folder to have it easier to create the desired state quickly in your tests:

IntegrationTestCase

    protected static function registerAccount(AccountId $accountId, Email $email): void
    {
        self::dispatchCommand(new RegisterAccount($accountId, $email, 'my-password'));
    }

    protected static function registerAccountWithAnSuccessfulOrder(AccountId $accountId, Email $email, OrderId $orderId): void
    {
        self::dispatchCommand(new RegisterAccount($accountId, $email, 'my-password'));
        self::dispatchCommand(new SubmitOrder(
            $orderId, 
            $accountId,
            new OrderItemCollection([/* items */]), 
            new CheckoutInformation(/* shipping info */),
        ));
    }

The important part is: use your business logic and dont write yourself in the database to create some state. The only exception is imho: you want to have a faulty state in your database to test an error case, but with event sourcing, even that should and can be covered via commands/events.

I think it is handy to let an integration test of the API be a guide (and test) for the consumers of this API

I'm not sure if I understand you here correctly, could you rephrase this?

And btw, no more ORM projects for you, but only Event Sourced projects?

No, just had since ages no project using laravel. IIRC it was laravel 5.5 which I did update to 5.6 and added some features. And there were no tests present at all. That's why I did some research on Datasbase Seeders then to create some basic tests and verify my changes.

Nowadays I would try to not use such Seeders/global fixtures at all as they are often the culprit why people think testing is hard due to the maintainence burden a global fixture set can bring in the long run.

You are already busy porting new features from the symfony-bundle right?

Yes, I already did open a PR which should bring all features which we already have in the symfony bundle present into the laravel integration. Feel free to have a look there and make suggestions. We are happy to any feedback - and especially about stuff we can do to better fit the laravel world.

In this context I also looked how laravel is solving tests database rollbacks. And I found a trait they are using RefreshDatabase. Unfortunatly it's written in a way we cannot integrate ourself with. A solution would be to create something similiar, but we are not sure yet. In the meantime you could span yourself a transaction around each test using setUp and tearDown. Or overwrite yourself the trait, i saw this here that someone did this: laravel-doctrine/orm#460

The other solution would be to provide Eloquent based Connections for the eventstore and subscription. But this should be postponed until we have a bigger need then these test rollbacks, as they can be solved in another way.