Weave Code
Messenger Test Laravel Package
zenstruck/messenger-test
Test helpers and assertions for symfony/messenger. Provides a TestTransport that intercepts and round-trips messages, lets you inspect queued items, assert counts/contents and processing states (acked/rejected), and optionally process queued messages in Kernel/Web tests.
Assertions and helpers for testing your symfony/messenger queues.
Frequently asked questions about Messenger Test
- How do I install zenstruck/messenger-test for Laravel queue testing?
- Run `composer require --dev zenstruck/messenger-test`, add the bundle to `config/bundles.php` under the `test` key, and override your transport in `messenger.yaml` to use `test://` in the test environment. This replaces real transports with a testable mock.
- Can I test retry behavior for Laravel jobs using this package?
- Yes, but only if you’re using Symfony’s `RetryMiddleware` with `spatie/laravel-messenger`. For native Laravel retries (e.g., `failAfterAttempts`), you’ll need a custom middleware adapter or manual retry simulation via `$transport->setRetryEnabled(false)`.
- Does this package work with Laravel’s Queue::fake()?
- No, it’s designed for Symfony Messenger. However, you can use it alongside `Queue::fake()` for hybrid testing, but focus on Symfony Messenger-specific assertions. For pure Laravel queues, consider alternatives like `laravel/queue-workbench` or custom mocks.
- How do I assert that a message was processed successfully?
- Use `$this->transport()->handled()->assertContains(MyMessage::class)` to verify a message was handled. For rejected messages, use `$this->transport()->rejected()->assertContains(MyMessage::class)`. The package tracks all processing states.
- Will this package slow down my test suite if I test many retries?
- Potentially, as retry simulations involve round-tripping messages. Optimize by testing critical retry paths or use `$transport->reset()` to clean up between tests. Avoid testing excessive retries in CI unless necessary.
- Can I use this for testing delayed jobs or middleware in Symfony Messenger?
- Yes, the `TestTransport` intercepts all messages, including delayed ones. For middleware, assert on the queue or handled/rejected states. However, complex middleware (e.g., custom retry logic) may require additional setup or adapters.
- What Laravel versions and Symfony Messenger versions are supported?
- The package targets Laravel 8+ and Symfony Messenger 5.3+. Check the [GitHub repo](https://github.com/zenstruck/messenger-test) for version-specific compatibility. Ensure your `spatie/laravel-messenger` or Symfony Messenger version aligns with the package’s requirements.
- How do I reset the transport between tests to avoid state leakage?
- Call `$this->transport()->reset()` after each test to clear queued, handled, and rejected messages. This prevents flaky tests caused by shared transport state, especially in test suites running in parallel.
- Is there a way to mock dependencies like Redis or database retries?
- The package doesn’t mock drivers directly, but you can use `$transport->setRetryEnabled(false)` to disable retries for testing. For database/Redis retries, consider mocking the underlying storage layer or using Laravel’s `Queue::fake()` for isolation.
- What alternatives exist for testing Laravel queues if I’m not using Symfony Messenger?
- For native Laravel queues, use `Queue::fake()` for basic assertions or `laravel/queue-workbench` for debugging. For Symfony Messenger, this package is the most robust option, but if you’re not using it, alternatives like `mockery` or custom test doubles may suffice.
Weaver
How can I help you explore Laravel packages today?