Add PoC for testing utilities: AggregateTestCase, SubscriberUtilities

phpstan-baseline.neon

@@ -131,3 +131,9 @@ parameters:
 			identifier: trait.unused
 			count: 1
 			path: src/Subscription/Subscriber/SubscriberUtil.php
+
+		-
+			message: '#^Trait Patchlevel\\EventSourcing\\Test\\SubscriberUtilities is used zero times and is not analysed\.$#'
+			identifier: trait.unused
+			count: 1
+			path: src/Test/SubscriberUtilities.php

src/Test/AggregateAlreadySet.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Test;
+
+final class AggregateAlreadySet extends AggregateTestError
+{
+    public function __construct()
+    {
+        parent::__construct('Aggregate already set. You should only return the aggregate if there is no given present.');
+    }
+}

src/Test/AggregateRootTestCase.php

@@ -0,0 +1,149 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Test;
+
+use Closure;
+use Patchlevel\EventSourcing\Aggregate\AggregateRoot;
+use PHPUnit\Framework\Attributes\After;
+use PHPUnit\Framework\Attributes\Before;
+use PHPUnit\Framework\Constraint\Exception as ExceptionConstraint;
+use PHPUnit\Framework\Constraint\ExceptionMessageIsOrContains;
+use PHPUnit\Framework\TestCase;
+use Throwable;
+
+abstract class AggregateRootTestCase extends TestCase
+{
+    /** @var array<object> */
+    private array $givenEvents = [];
+
+    /** @var array<Closure> */
+    private array $whens = [];
+
+    /** @var array<object> */
+    private array $expectedEvents = [];
+    /** @var class-string<Throwable>|null  */
+    private string|null $expectedException = null;
+    private string|null $expectedExceptionMessage = null;
+
+    /** @return class-string<AggregateRoot> */
+    abstract protected function aggregateClass(): string;
+
+    public function given(object ...$events): self
+    {
+        $this->givenEvents = $events;
+
+        return $this;
+    }
+
+    public function when(Closure ...$callables): self
+    {
+        $this->whens = $callables;
+
+        return $this;
+    }
+
+    public function then(object ...$events): self
+    {
+        $this->expectedEvents = $events;
+
+        return $this;
+    }
+
+    /** @param class-string<Throwable> $exception */
+    public function expectsException(string $exception): self
+    {
+        $this->expectedException = $exception;
+
+        return $this;
+    }
+
+    public function expectsExceptionMessage(string $exceptionMessage): self
+    {
+        $this->expectedExceptionMessage = $exceptionMessage;
+
+        return $this;
+    }
+
+    #[After]
+    public function assert(): self
+    {
+        $aggregate = null;
+
+        if ($this->givenEvents) {
+            $aggregate = $this->aggregateClass()::createFromEvents($this->givenEvents);
+        }
+
+        try {
+            foreach ($this->whens as $callable) {
+                $return = $callable($aggregate);
+
+                if ($aggregate !== null && $return instanceof AggregateRoot) {
+                    throw new AggregateAlreadySet();
+                }
+
+                if ($aggregate === null && !$return instanceof AggregateRoot) {
+                    throw new NoAggregateCreated();
+                }
+
+                if ($aggregate !== null || !($return instanceof AggregateRoot)) {
+                    continue;
+                }
+
+                $aggregate = $return;
+            }
+        } catch (AggregateTestError $exception) {
+            throw $exception;
+        } catch (Throwable $throwable) {
+            $this->handleException($throwable);
+        }
+
+        if (!$aggregate instanceof AggregateRoot) {
+            throw new NoAggregateCreated();
+        }
+
+        $events = $aggregate->releaseEvents();
+
+        self::assertEquals($this->expectedEvents, $events, 'The events doesn\'t match the expected events.');
+
+        return $this;
+    }
+
+    #[Before]
+    public function reset(): void
+    {
+        $this->givenEvents = [];
+        $this->whens = [];
+        $this->expectedEvents = [];
+        $this->expectedException = null;
+        $this->expectedExceptionMessage = null;
+    }
+
+    private function handleException(Throwable $throwable): void
+    {
+        if ($this->expectedException === null && $this->expectedExceptionMessage === null) {
+            throw $throwable;
+        }
+
+        if ($this->expectedException) {
+            $this->assertThat(
+                $throwable,
+                new ExceptionConstraint(
+                    $this->expectedException,
+                ),
+            );
+        }
+
+        if (!$this->expectedExceptionMessage) {
+            return;
+        }
+
+        $this->assertThat(
+            $throwable->getMessage(),
+            new ExceptionMessageIsOrContains(
+                $this->expectedExceptionMessage,
+            ),
+        );
+    }
+}

src/Test/AggregateTestError.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Test;
+
+use RuntimeException;
+
+abstract class AggregateTestError extends RuntimeException
+{
+}

src/Test/NoAggregateCreated.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Test;
+
+final class NoAggregateCreated extends AggregateTestError
+{
+    public function __construct()
+    {
+        parent::__construct('No aggregate set and no aggregate returned. Please provide given events or create the aggregate with the first action.');
+    }
+}

src/Test/SubscriberUtilities.php

@@ -0,0 +1,91 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Test;
+
+use Patchlevel\EventSourcing\Message\Message;
+use Patchlevel\EventSourcing\Subscription\Subscriber\MetadataSubscriberAccessor;
+use Patchlevel\EventSourcing\Subscription\Subscriber\MetadataSubscriberAccessorRepository;
+use PHPUnit\Framework\Attributes\Before;
+
+trait SubscriberUtilities
+{
+    /** @var array<object> */
+    private array $givenEvents = [];
+    /**  @var MetadataSubscriberAccessor[] */
+    private iterable $subscriberAccessors;
+
+    public function given(object ...$events): self
+    {
+        $this->givenEvents = $events;
+
+        return $this;
+    }
+
+    public function executeSetup(object ...$subscribers): self
+    {
+        $subscriberAccessors = $this->createSubscriberAccessors($subscribers);
+
+        foreach ($subscriberAccessors as $subscriberAccessor) {
+            $setupMethod = $subscriberAccessor->setupMethod();
+
+            if (!$setupMethod) {
+                continue;
+            }
+
+            $setupMethod();
+        }
+
+        return $this;
+    }
+
+    public function executeRun(object ...$subscribers): self
+    {
+        $subscriberAccessors = $this->createSubscriberAccessors($subscribers);
+
+        foreach ($this->givenEvents as $event) {
+            foreach ($subscriberAccessors as $subscriberAccessor) {
+                foreach ($subscriberAccessor->subscribeMethods($event::class) as $subscribeMethod) {
+                    $subscribeMethod(Message::create($event));
+                }
+            }
+        }
+
+        return $this;
+    }
+
+    public function executeTeardown(object ...$subscribers): self
+    {
+        $subscriberAccessors = $this->createSubscriberAccessors($subscribers);
+
+        foreach ($subscriberAccessors as $subscriberAccessor) {
+            $teardownMethod = $subscriberAccessor->teardownMethod();
+
+            if (!$teardownMethod) {
+                continue;
+            }
+
+            $teardownMethod();
+        }
+
+        return $this;
+    }
+
+    #[Before]
+    public function reset(): void
+    {
+        $this->givenEvents = [];
+        unset($this->subscriberAccessors);
+    }
+
+    /**
+     * @param array<object> $subscribers
+     *
+     * @return iterable<MetadataSubscriberAccessor>
+     */
+    private function createSubscriberAccessors(array $subscribers): iterable
+    {
+        return $this->subscriberAccessors ??= (new MetadataSubscriberAccessorRepository($subscribers))->all();
+    }
+}

tests/Unit/Fixture/Profile.php

@@ -9,6 +9,7 @@
 use Patchlevel\EventSourcing\Attribute\Apply;
 use Patchlevel\EventSourcing\Attribute\Id;
 use Patchlevel\EventSourcing\Attribute\SuppressMissingApply;
+use RuntimeException;
 
 #[Aggregate('profile')]
 #[SuppressMissingApply([MessageDeleted::class])]
@@ -66,6 +67,11 @@ public function splitIt(): void
         $this->recordThat(new SplittingEvent($this->email, $this->visits));
     }
 
+    public function throwException(): void
+    {
+        throw new RuntimeException('throwing so that you can catch it!');
+    }
+
     #[Apply(ProfileCreated::class)]
     #[Apply(ProfileVisited::class)]
     protected function applyProfileCreated(ProfileCreated|ProfileVisited $event): void