PHPackages patchlevel/event-sourcing-phpunit - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Testing & Quality](/categories/testing) 4. / 5. patchlevel/event-sourcing-phpunit ActiveLibrary[Testing & Quality](/categories/testing) patchlevel/event-sourcing-phpunit ================================= PHPUnit testing utilities for patchlevel/event-sourcing 1.6.0(3mo ago)165.6k↓15.5%2[1 issues](https://github.com/patchlevel/event-sourcing-phpunit/issues)MITPHPPHP ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0CI passing Since Feb 12Pushed 2mo ago2 watchersCompare [ Source](https://github.com/patchlevel/event-sourcing-phpunit)[ Packagist](https://packagist.org/packages/patchlevel/event-sourcing-phpunit)[ Docs](https://event-sourcing.patchlevel.io)[ RSS](/packages/patchlevel-event-sourcing-phpunit/feed)WikiDiscussions 1.7.x Synced 1mo ago READMEChangelog (8)Dependencies (5)Versions (19)Used By (0) [![Mutation testing badge](https://camo.githubusercontent.com/30e14120b7357a81d5f11a5e56f67a5478c3f1278f90cc7549e32f5e42038f45/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f7374796c653d666c61742675726c3d687474707325334125324625324662616467652d6170692e737472796b65722d6d757461746f722e696f2532466769746875622e636f6d25324670617463686c6576656c2532466576656e742d736f757263696e672d706870756e6974253246312e302e78)](https://dashboard.stryker-mutator.io/reports/github.com/patchlevel/event-sourcing-phpunit/1.0.x)[![Latest Stable Version](https://camo.githubusercontent.com/9c094fdd83811b6131a08e0e8f01641ab6e27089c89bf4485f586ebae9c79412/68747470733a2f2f706f7365722e707567782e6f72672f70617463686c6576656c2f6576656e742d736f757263696e672d706870756e69742f76)](//packagist.org/packages/patchlevel/event-sourcing-phpunit)[![License](https://camo.githubusercontent.com/43e6d6aae2b134d7145ef807299a6ad09e58c95a19cc9701ccd4e5a85303d75e/68747470733a2f2f706f7365722e707567782e6f72672f70617463686c6576656c2f6576656e742d736f757263696e672d706870756e69742f6c6963656e7365)](//packagist.org/packages/patchlevel/event-sourcing-phpunit) Testing utilities ================= [](#testing-utilities) With this library you can ease the testing for your [event-sourcing](https://github.com/patchlevel/event-sourcing)project when using PHPUnit. It comes with utilities for aggregates and subscribers. Installation ------------ [](#installation) ``` composer require --dev patchlevel/event-sourcing-phpunit ``` Testing Aggregates ------------------ [](#testing-aggregates) There is a special `TestCase` for aggregate tests which you can extend from. Extending from `AggregateRootTestCase`enables you to use the given / when / then notation. This makes it very clear what the test is doing. When extending the class you will need to implement a method which provides the FQCN of the aggregate you want to test. ``` final class ProfileTest extends AggregateRootTestCase { protected function aggregateClass(): string { return Profile::class; } } ``` When this is done, you already can start testing your behaviour. For example testing that a event is recorded. ``` final class ProfileTest extends AggregateRootTestCase { // protected function aggregateClass(): string; public function testBehaviour(): void { $this ->given( new ProfileCreated( ProfileId::fromString('1'), Email::fromString('hq@patchlevel.de'), ), ) ->when(static fn (Profile $profile) => $profile->visitProfile(ProfileId::fromString('2'))) ->then(new ProfileVisited(ProfileId::fromString('2'))); } } ``` You can also provide multiple given events and expect multiple events: ``` final class ProfileTest extends AggregateRootTestCase { // protected function aggregateClass(): string; public function testBehaviour(): void { $this ->given( new ProfileCreated( ProfileId::fromString('1'), Email::fromString('hq@patchlevel.de'), ), new ProfileVisited(ProfileId::fromString('2')), ) ->when( static function (Profile $profile) { $profile->visitProfile(ProfileId::fromString('3')); $profile->visitProfile(ProfileId::fromString('4')); } ) ->then( new ProfileVisited(ProfileId::fromString('3')), new ProfileVisited(ProfileId::fromString('4')), ); } } ``` You can also test the creation of the aggregate: ``` final class ProfileTest extends AggregateRootTestCase { // protected function aggregateClass(): string; public function testBehaviour(): void { $this ->when(static fn () => Profile::createProfile(ProfileId::fromString('1'), Email::fromString('hq@patchlevel.de'))) ->then(new ProfileCreated(ProfileId::fromString('1'), Email::fromString('hq@patchlevel.de'))); } } ``` And expect an exception and the message of it: ``` final class ProfileTest extends AggregateRootTestCase { // protected function aggregateClass(): string; public function testBehaviour(): void { $this ->given( new ProfileCreated( ProfileId::fromString('1'), Email::fromString('hq@patchlevel.de'), ), ) ->when(static fn (Profile $profile) => $profile->throwException()) ->expectsException(ProfileError::class) ->expectsExceptionMessage('throwing so that you can catch it!'); } } ``` ### Asserting aggregate state [](#asserting-aggregate-state) You can pass closures to `then()` to assert on the aggregate's state after the events have been applied. This is useful when your aggregate exposes state via public properties or getters that are set in `apply` methods. Closures receive the aggregate instance and are executed after the event assertion. You can mix closures and expected events freely — event order is preserved regardless of callback placement. ``` final class ProfileTest extends AggregateRootTestCase { // protected function aggregateClass(): string; public function testBehaviour(): void { $this ->given( new ProfileCreated( ProfileId::fromString('1'), Email::fromString('hq@patchlevel.de'), ), ) ->when(static fn (Profile $profile) => $profile->visitProfile(ProfileId::fromString('2'))) ->then( new ProfileVisited(ProfileId::fromString('2')), static fn (Profile $profile) => self::assertSame('1', $profile->id()->toString()), ); } } ``` Note When `then()` receives only closures and no event objects, it strictly asserts that zero events were emitted. ### Using Commandbus like syntax [](#using-commandbus-like-syntax) When using the command bus and the `#[Handle]` attributes in your aggregate you can also provide the command directly for the `when` method. ``` final class ProfileTest extends AggregateRootTestCase { // protected function aggregateClass(): string; public function testBehaviour(): void { $this ->when(new CreateProfile(ProfileId::fromString('1'), Email::fromString('hq@patchlevel.de'))) ->then(new ProfileCreated(ProfileId::fromString('1'), Email::fromString('hq@patchlevel.de'))); } } ``` If more parameters than the command is needed, these can also be provided as additional parameters for `when`. In this example the we need a string which will be directly passed to the event. ``` final class ProfileTest extends AggregateRootTestCase { // protected function aggregateClass(): string; public function testBehaviour(): void { $this ->given( new ProfileCreated( ProfileId::fromString('1'), Email::fromString('hq@patchlevel.de'), ), ) ->when(new VisitProfile(ProfileId::fromString('2')), 'Extra Parameter / Dependency') ->then(new ProfileVisited(ProfileId::fromString('2'), 'Extra Parameter / Dependency')); } } ``` Testing Subscriber ------------------ [](#testing-subscriber) For testing a subscriber there is a utility class which you can use. Using `SubscriberUtilities` will provide you a bunch of dx features which makes the testing easier. First, you will need to provide the utility class the subscriptions you will want to test, this is done when initializing the class. After that, you can call these 3 methods: `executeSetup`, `executeRun` and `executeTeardown`. These methods will be calling the right methods which are defined via the attributes. For our example we are taking as simplified subscriber: ``` use Patchlevel\EventSourcing\Attribute\Setup; use Patchlevel\EventSourcing\Attribute\Subscribe; use Patchlevel\EventSourcing\Attribute\Subscriber; use Patchlevel\EventSourcing\Attribute\Teardown; #[Subscriber('profile_subscriber', RunMode::FromBeginning)] final class ProfileSubscriber { public int $called = 0; #[Subscribe(ProfileCreated::class)] public function run(): void { $this->called++; } #[Setup] public function setup(): void { $this->called++; } #[Teardown] public function teardown(): void { $this->called++; } } ``` With this, we can now write our test for it: ``` use Patchlevel\EventSourcing\Attribute\Subscriber; use Patchlevel\EventSourcing\Subscription\RunMode; use Patchlevel\EventSourcing\PhpUnit\Test\SubscriberUtilities; final class ProfileSubscriberTest extends TestCase { use SubscriberUtilities; public function testProfileCreated(): void { $subscriber = new ProfileSubscriber(/* inject deps, if needed */); $util = new SubscriberUtilities($subscriber); $util->executeSetup(); $util->executeRun( new ProfileCreated( ProfileId::fromString('1'), Email::fromString('hq@patchlevel.de'), ) ); $util->executeTeardown(); self::assertSame(3, $subscriber->count); } } ``` This Util class can be used for integration or unit tests. You can also pass `Message` instances with additional headers to the `executeRun` method. This allows testing subscribers that rely on additional parameters like header information: ``` use Patchlevel\EventSourcing\Attribute\Subscribe; use Patchlevel\EventSourcing\Attribute\Subscriber; use DateTimeImmutable; #[Subscriber('profile_subscriber', RunMode::FromBeginning)] final class ProfileSubscriber { #[Subscribe(ProfileCreated::class)] public function run(ProfileCreated $event, DateTimeImmutable $recordedOn): void { } } ``` Add any headers you want in the test: ``` use Patchlevel\EventSourcing\Attribute\Subscriber; use Patchlevel\EventSourcing\Message\Message; use Patchlevel\EventSourcing\Store\Header\RecordedOnHeader; use Patchlevel\EventSourcing\Subscription\RunMode; use Patchlevel\EventSourcing\PhpUnit\Test\SubscriberUtilities; use DateTimeImmutable; final class ProfileSubscriberTest extends TestCase { use SubscriberUtilities; public function testProfileCreated(): void { /* Setup and Teardown as before */ $util->executeRun( Message::createWithHeaders( new ProfileCreated( ProfileId::fromString('1'), Email::fromString('hq@patchlevel.de'), ), [new RecordedOnHeader(new DateTimeImmutable('now'))], ) ); /* Your assertions */ } } ``` ### Health Score 48 — FairBetter than 95% of packages Maintenance65 Regular maintenance activity Popularity35 Limited adoption so far Community16 Small or concentrated contributor base Maturity64 Established project with proven stability Bus Factor1 Top contributor holds 76.4% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~27 days Recently: every ~9 days Total 16 Last Release 54d ago PHP version history (4 changes)1.0.0PHP ~8.1.0 || ~8.2.0 || ~8.3.0 1.1.0PHP ~8.2.0 || ~8.3.0 1.2.0PHP ~8.2.0 || ~8.3.0 || ~8.4.0 1.3.0PHP ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/470138?v=4)[David Badura](/maintainers/DavidBadura)[@DavidBadura](https://github.com/DavidBadura) ![](https://www.gravatar.com/avatar/30c133675c8ebfdcbbdb25c641885f939c2f3d29b4ac9435d608b1c201e2f1bc?d=identicon)[DanielBadura](/maintainers/DanielBadura) --- Top Contributors [![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (133 commits)")[![DanielBadura](https://avatars.githubusercontent.com/u/2017762?v=4)](https://github.com/DanielBadura "DanielBadura (32 commits)")[![wikando-ck](https://avatars.githubusercontent.com/u/73299324?v=4)](https://github.com/wikando-ck "wikando-ck (6 commits)")[![DavidBadura](https://avatars.githubusercontent.com/u/470138?v=4)](https://github.com/DavidBadura "DavidBadura (2 commits)")[![fritz-gerneth](https://avatars.githubusercontent.com/u/1294731?v=4)](https://github.com/fritz-gerneth "fritz-gerneth (1 commits)") --- Tags testingphpunitdddevent sourcing ### Code Quality Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/patchlevel-event-sourcing-phpunit/health.svg) ``` [![Health](https://phpackages.com/badges/patchlevel-event-sourcing-phpunit/health.svg)](https://phpackages.com/packages/patchlevel-event-sourcing-phpunit) ``` ### Alternatives [brianium/paratest Parallel testing for PHP 2.5k118.8M754](/packages/brianium-paratest)[spatie/phpunit-snapshot-assertions Snapshot testing with PHPUnit 69617.9M510](/packages/spatie-phpunit-snapshot-assertions)[phpunit/phpunit-selenium Selenium Server integration for PHPUnit 59610.9M150](/packages/phpunit-phpunit-selenium)[yoast/phpunit-polyfills Set of polyfills for changed PHPUnit functionality to allow for creating PHPUnit cross-version compatible tests 18438.5M841](/packages/yoast-phpunit-polyfills)[ta-tikoma/phpunit-architecture-test Methods for testing application architecture 10745.9M13](/packages/ta-tikoma-phpunit-architecture-test)[matthiasnoback/symfony-config-test Library for testing user classes related to the Symfony Config Component 1679.8M395](/packages/matthiasnoback-symfony-config-test) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)