Weave Code
Event Sourcing Phpunit Laravel Package
patchlevel/event-sourcing-phpunit
A dev testing toolkit for patchlevel/event-sourcing that lets you test aggregates and subscribers with clear given/when/then notation. Dispatch commands through #[Handle] methods, assert aggregate state with closures, and use subscriber setup, run, and teardown utilities.
PHPUnit testing utilities for patchlevel/event-sourcing
Frequently asked questions about Event Sourcing Phpunit
- How do I install patchlevel/event-sourcing-phpunit?
- Install it as a dev dependency with composer require --dev patchlevel/event-sourcing-phpunit. It is a test-only package, so it belongs in require-dev rather than your production dependencies. After installing, extend the provided given/when/then test case in your aggregate tests. Confirm the Patchlevel event-sourcing version constraint in your composer.json before you start.
- Which PHP, PHPUnit, and patchlevel/event-sourcing versions are supported?
- Support for PHP, PHPUnit, and patchlevel/event-sourcing versions should be verified on Packagist and in the repository CI matrix before adopting. The package is on a 1.0.x line with a Stryker mutation testing badge, which suggests deliberate quality practices but does not confirm a specific compatibility matrix. Pin exact versions in composer.json, commit the lockfile, and add a CI job on your next planned PHPUnit major to surface upgrade friction early.
- Can I use patchlevel/event-sourcing-phpunit with Pest instead of PHPUnit?
- The README and documentation focus on PHPUnit test cases, and Pest compatibility is not clearly stated. Pest can often wrap PHPUnit-style test cases, but you should confirm with a small spike before committing. If Pest is your team standard, treat this as an open item in a timeboxed pilot rather than an assumption.
- How do I write a given/when/then test for an aggregate?
- Extend the provided test case and express your scenario in three parts: given past events, when a command or event occurs, then assertions about the resulting state. The when step can dispatch commands through your #[Handle] methods so the test follows the same path as production code. This replaces bespoke aggregate test scaffolding with a consistent notation, and it works best when your aggregates already follow Patchlevel conventions.
- How does command dispatch through #[Handle] methods work in the when step?
- Rather than calling aggregate methods directly, the when step sends a command object through the handler resolved from your #[Handle] annotated methods. That means the test exercises the same command-to-event flow your application uses, including any guards or validation. It also couples the test to Patchlevel conventions, so upstream changes in handler resolution can affect tests in non-obvious ways.
- How do I test subscribers and isolate side effects?
- A subscriber utility provides setup, run, and teardown steps so you can prepare dependencies, execute the subscriber, and clean up between tests. Use teardown to reset in-memory state and any fakes, so side-effect-heavy subscribers do not leak between cases. Exact handling of asynchronous transports and projections is not spelled out in the README, so verify it during a pilot.
- How do I assert aggregate state in tests?
- Aggregate state assertions are written as closures, letting you inspect properties and collections after the when step completes. Instead of comparing whole object graphs, assert exactly the invariants and fields that matter, which keeps tests resilient to internal refactors. Wrap common assertions in your own helpers so the internal base test case stays the single seam for future changes.
- Does it work with Spatie laravel-event-sourcing or EventSauce?
- No. It is a PHPUnit harness for patchlevel/event-sourcing and depends on Patchlevel aggregate and handler conventions. Teams using Spatie laravel-event-sourcing, EventSauce, or custom event sourcing should not adopt it, because the given/when/then DSL and #[Handle] command dispatch are specific to the Patchlevel stack.
- Is it a production dependency, and does it affect runtime?
- No runtime footprint: it is installed with composer require --dev and is only used by your test suite. That keeps production dependency surface and autoload overhead unchanged. Still treat it as a supply-chain item, since it is a low-dependency package with a small maintainer base, and pin versions in the lockfile.
- What is the maintenance risk, and what is the fallback if the package is abandoned?
- The package is on a 1.0.x line with a stated backward-compatibility promise, but it has a single maintainer, one star, and negligible community surface, so abandonment or slow PHPUnit major support is the main risk. Mitigate by wrapping the provided test case in an internal base class, keeping tests on standard PHPUnit where possible, and budgeting an exit path that vendors a small trait or base test case if needed. Validate release history and dates on Packagist before planning.
Weaver
How can I help you explore Laravel packages today?