Implement custom reporting for event-based testing (requires snapshot of PHPUnit 12.3)

Author: sebastianbergmann

.gitignore

@@ -4,4 +4,5 @@
 /.php-cs-fixer.cache
 /.phpunit.cache
 /vendor
+/build
 /projections

phpunit.xml

@@ -53,4 +53,10 @@
     <php>
         <const name="TEST_WEB_SERVER_BASE_URL" value="http://127.0.0.1:8080"/>
     </php>
+
+    <extensions>
+        <bootstrap class="example\framework\event\test\extension\Extension">
+            <parameter name="target" value="build/events.md"/>
+        </bootstrap>
+    </extensions>
 </phpunit>

tests/integration/application/processor/PurchaseGoodCommandProcessorTest.php

@@ -0,0 +1,41 @@
+<?php declare(strict_types=1);
+namespace example\caledonia\application;
+
+use example\caledonia\domain\Good;
+use example\caledonia\domain\Price;
+use example\caledonia\domain\PurchaseGoodCommand;
+use example\framework\event\EventTestCase;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Medium;
+use PHPUnit\Framework\Attributes\TestDox;
+
+#[CoversClass(ProcessingPurchaseGoodCommandProcessor::class)]
+#[Medium]
+#[TestDox('ProcessingPurchaseGoodCommandProcessor')]
+final class PurchaseGoodCommandProcessorTest extends EventTestCase
+{
+    #[TestDox('A GoodPurchasedEvent and a PriceChangedEvent are emitted when the price changes after a good is purchased')]
+    public function testEmitsGoodPurchasedAndPriceChangedEvents(): void
+    {
+        $this->given(
+            $this->goodPurchased(Good::Bread, Price::from(10), 1),
+            $this->goodPurchased(Good::Bread, Price::from(11), 1),
+        );
+
+        $this->when(new PurchaseGoodCommand(Good::Bread, 1));
+
+        $this->then(
+            $this->goodPurchased(Good::Bread, Price::from(11), 1),
+            $this->priceChanged(Good::Bread, Price::from(11), Price::from(12)),
+        );
+    }
+
+    private function when(PurchaseGoodCommand $command): void
+    {
+        $processor = new ProcessingPurchaseGoodCommandProcessor($this->emitter(), $this->sourcer());
+
+        $processor->process($command);
+
+        $this->recordWhen($command);
+    }
+}

tests/integration/application/processor/SellGoodCommandProcessorTest.php

@@ -0,0 +1,38 @@
+<?php declare(strict_types=1);
+namespace example\caledonia\application;
+
+use example\caledonia\domain\Good;
+use example\caledonia\domain\Price;
+use example\caledonia\domain\SellGoodCommand;
+use example\framework\event\EventTestCase;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Medium;
+use PHPUnit\Framework\Attributes\TestDox;
+
+#[CoversClass(ProcessingSellGoodCommandProcessor::class)]
+#[Medium]
+#[TestDox('ProcessingPurchaseSellCommandProcessor')]
+final class SellGoodCommandProcessorTest extends EventTestCase
+{
+    #[TestDox('A GoodSoldEvent and a PriceChangedEvent are emitted when the price changes after a good is sold')]
+    public function testEmitsGoodPurchasedAndPriceChangedEvents(): void
+    {
+        $this->given();
+
+        $this->when(new SellGoodCommand(Good::Bread, 1));
+
+        $this->then(
+            $this->goodSold(Good::Bread, Price::from(10), 1),
+            $this->priceChanged(Good::Bread, Price::from(10), Price::from(9)),
+        );
+    }
+
+    private function when(SellGoodCommand $command): void
+    {
+        $processor = new ProcessingSellGoodCommandProcessor($this->emitter(), $this->sourcer());
+
+        $processor->process($command);
+
+        $this->recordWhen($command);
+    }
+}

tests/src/CollectingEventDispatcher.php

@@ -0,0 +1,20 @@
+<?php declare(strict_types=1);
+namespace example\framework\event;
+
+final class CollectingEventDispatcher implements EventDispatcher
+{
+    /**
+     * @var list<Event>
+     */
+    private array $events = [];
+
+    public function dispatch(Event $event): void
+    {
+        $this->events[] = $event;
+    }
+
+    public function events(): EventCollection
+    {
+        return EventCollection::fromArray($this->events);
+    }
+}

tests/src/EventTestCase.php

@@ -0,0 +1,147 @@
+<?php declare(strict_types=1);
+namespace example\framework\event;
+
+use const PHP_EOL;
+use function array_keys;
+use function array_values;
+use function assert;
+use example\caledonia\application\DispatchingEventEmitter;
+use example\caledonia\application\EventEmitter;
+use example\caledonia\application\MarketEventSourcer;
+use example\caledonia\application\MarketSourcer;
+use example\caledonia\domain\Command;
+use example\caledonia\domain\Good;
+use example\caledonia\domain\GoodPurchasedEvent;
+use example\caledonia\domain\GoodSoldEvent;
+use example\caledonia\domain\Price;
+use example\caledonia\domain\PriceChangedEvent;
+use example\framework\library\RandomUuidGenerator;
+use PHPUnit\Framework\MockObject\Stub;
+use PHPUnit\Framework\TestCase;
+
+abstract class EventTestCase extends TestCase
+{
+    private EventReader&Stub $reader;
+    private MarketEventSourcer $sourcer;
+    private DispatchingEventEmitter $emitter;
+    private CollectingEventDispatcher $dispatcher;
+    private string $documentation;
+
+    final protected function setUp(): void
+    {
+        $this->reader     = $this->createStub(EventReader::class);
+        $this->sourcer    = new MarketEventSourcer($this->reader);
+        $this->dispatcher = new CollectingEventDispatcher;
+
+        $this->emitter = new DispatchingEventEmitter(
+            $this->dispatcher,
+            new RandomUuidGenerator,
+        );
+    }
+
+    final protected function given(Event ...$events): void
+    {
+        $events = EventCollection::fromArray(array_values($events));
+
+        $this
+            ->reader
+            ->method('topic')
+            ->willReturn($events);
+
+        $this->documentation = 'Given:' . PHP_EOL . PHP_EOL;
+
+        foreach ($events as $event) {
+            $this->documentation .= '    - ' . $event->asString() . PHP_EOL;
+        }
+
+        $this->documentation .= PHP_EOL;
+    }
+
+    final protected function recordWhen(Command $command): void
+    {
+        $this->documentation .= 'When:' . PHP_EOL . PHP_EOL;
+        $this->documentation .= '    - ' . $command->asString() . PHP_EOL . PHP_EOL;
+    }
+
+    final protected function then(Event ...$events): void
+    {
+        $events = EventCollection::fromArray(array_values($events));
+
+        $expected = $events->asArray();
+        $actual   = $this->dispatcher->events()->asArray();
+
+        $this->assertSameSize($expected, $actual);
+
+        foreach (array_keys($expected) as $key) {
+            assert(isset($expected[$key]));
+            assert(isset($actual[$key]));
+
+            $this->assertEventObjectsAreEqualExceptForUuid($expected[$key], $actual[$key]);
+        }
+
+        $this->documentation .= 'Then:' . PHP_EOL . PHP_EOL;
+
+        foreach ($events as $event) {
+            $this->documentation .= '    - ' . $event->asString() . PHP_EOL;
+        }
+
+        $this->provideAdditionalInformation($this->documentation);
+    }
+
+    /**
+     * @param positive-int $amount
+     */
+    final protected function goodPurchased(Good $good, Price $price, int $amount): GoodPurchasedEvent
+    {
+        return new GoodPurchasedEvent(
+            (new RandomUuidGenerator)->generate(),
+            $good,
+            $price,
+            $amount,
+        );
+    }
+
+    /**
+     * @param positive-int $amount
+     */
+    final protected function goodSold(Good $good, Price $price, int $amount): GoodSoldEvent
+    {
+        return new GoodSoldEvent(
+            (new RandomUuidGenerator)->generate(),
+            $good,
+            $price,
+            $amount,
+        );
+    }
+
+    final protected function priceChanged(Good $good, Price $old, Price $new): PriceChangedEvent
+    {
+        return new PriceChangedEvent(
+            (new RandomUuidGenerator)->generate(),
+            $good,
+            $old,
+            $new,
+        );
+    }
+
+    final protected function emitter(): EventEmitter
+    {
+        return $this->emitter;
+    }
+
+    final protected function sourcer(): MarketSourcer
+    {
+        return $this->sourcer;
+    }
+
+    private function assertEventObjectsAreEqualExceptForUuid(Event $expected, Event $actual): void
+    {
+        $this->assertInstanceOf($expected::class, $actual);
+
+        $this->assertArrayIsEqualToArrayIgnoringListOfKeys(
+            (array) $expected,
+            (array) $actual,
+            ["\0example\\framework\\event\\Event\0id"],
+        );
+    }
+}

tests/src/extension/AdditionalInformationProvidedSubscriber.php

@@ -0,0 +1,18 @@
+<?php declare(strict_types=1);
+namespace example\framework\event\test\extension;
+
+use PHPUnit\Event\Test\AdditionalInformationProvided as TestProvidedAdditionalInformation;
+use PHPUnit\Event\Test\AdditionalInformationProvidedSubscriber as TestProvidedAdditionalInformationSubscriber;
+
+/**
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ *
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
+final readonly class AdditionalInformationProvidedSubscriber extends Subscriber implements TestProvidedAdditionalInformationSubscriber
+{
+    public function notify(TestProvidedAdditionalInformation $event): void
+    {
+        $this->extension()->testProvidedAdditionalInformation($event);
+    }
+}

tests/src/extension/Extension.php

@@ -0,0 +1,93 @@
+<?php declare(strict_types=1);
+namespace example\framework\event\test\extension;
+
+use const PHP_EOL;
+use function assert;
+use function dirname;
+use function file_put_contents;
+use function is_dir;
+use function is_file;
+use function ksort;
+use function mkdir;
+use function unlink;
+use PHPUnit\Event\Test\AdditionalInformationProvided;
+use PHPUnit\Runner\Extension\Extension as ExtensionInterface;
+use PHPUnit\Runner\Extension\Facade as ExtensionFacade;
+use PHPUnit\Runner\Extension\ParameterCollection;
+use PHPUnit\TextUI\Configuration\Configuration;
+
+final class Extension implements ExtensionInterface
+{
+    /**
+     * @var non-empty-string
+     */
+    private string $target;
+
+    /**
+     * @var array<string, list<array{testdox: string, specification: string}>>
+     */
+    private array $specification = [];
+
+    public function bootstrap(Configuration $configuration, ExtensionFacade $facade, ParameterCollection $parameters): void
+    {
+        $target = '/tmp/events.md';
+
+        if ($parameters->has('target')) {
+            $target = $parameters->get('target');
+        }
+
+        assert($target !== '');
+
+        $this->target = $target;
+
+        $this->prepareLogfile($this->target);
+
+        $facade->registerSubscribers(
+            new AdditionalInformationProvidedSubscriber($this),
+            new TestRunnerExecutionFinishedSubscriber($this),
+        );
+    }
+
+    public function testProvidedAdditionalInformation(AdditionalInformationProvided $event): void
+    {
+        if (!isset($this->specification[$event->test()->testDox()->prettifiedClassName()])) {
+            $this->specification[$event->test()->testDox()->prettifiedClassName()] = [];
+        }
+
+        $this->specification[$event->test()->testDox()->prettifiedClassName()][] = [
+            'testdox'       => $event->test()->testDox()->prettifiedMethodName(),
+            'specification' => $event->additionalInformation(),
+        ];
+    }
+
+    public function flush(): void
+    {
+        ksort($this->specification);
+
+        $buffer = '';
+
+        foreach ($this->specification as $class => $methods) {
+            $buffer .= '# ' . $class . PHP_EOL . PHP_EOL;
+
+            foreach ($methods as $method) {
+                $buffer .= '## ' . $method['testdox'] . PHP_EOL . PHP_EOL;
+                $buffer .= $method['specification'] . PHP_EOL . PHP_EOL;
+            }
+        }
+
+        file_put_contents($this->target, $buffer);
+    }
+
+    private function prepareLogfile(string $target): void
+    {
+        if (is_file($target)) {
+            unlink($target);
+
+            return;
+        }
+
+        if (!is_dir(dirname($target))) {
+            @mkdir(dirname($target), 0o777, true);
+        }
+    }
+}

tests/src/extension/Subscriber.php

@@ -0,0 +1,17 @@
+<?php declare(strict_types=1);
+namespace example\framework\event\test\extension;
+
+abstract readonly class Subscriber
+{
+    private Extension $extension;
+
+    public function __construct(Extension $extension)
+    {
+        $this->extension = $extension;
+    }
+
+    final protected function extension(): Extension
+    {
+        return $this->extension;
+    }
+}