Messenger Test Laravel Package

Product Decisions This Supports

• Testing strategy for asynchronous workflows: This package lets the team verify that messages are actually dispatched to Symfony Messenger queues, and that handlers acknowledge, reject, or retry them as intended. That directly supports go/no-go decisions on whether a feature is safe to ship when it relies on background jobs (emails, webhooks, exports, payments, notifications).
• Build vs. buy for test infrastructure: Rather than funding internal queue-testing utilities, this is a low-cost, MIT-licensed dev dependency that wraps Symfony's own test transports with opinionated assertions. A decision to adopt is effectively "buy" at near-zero cost — only integration time and a config change in the test environment.
• Definition of Done and quality gates: Because it enables assertions like assertCount, assertContains, assertEmpty, acknowledged(), and rejected(), PMs can add explicit "queue behaviour is tested" criteria to acceptance criteria without asking engineering to invent a bespoke harness.
• Roadmap confidence for async-heavy features: For initiatives where user-visible outcomes depend on queued processing (delayed reminders, retry/backoff, multi-transport priority lanes), the ability to simulate DelayStamp with a mocked clock and to assert "nothing happens yet, then it does" turns speculative roadmap commitments into testable ones.
• Failure/branching decisions: rejected() vs acknowledged() visibility, plus throwExceptions() / catchExceptions(), lets the team encode product decisions — e.g. "a failed invoice message must land in rejected, not silently vanish" — as durable, executable expectations.
• Supporting deliberate test-scope trade-offs: intercept() vs unblock() is a product-relevant lever: intercept mode for testing dispatch contracts, unblock mode for testing end-to-end handler behaviour. PMs can specify which class of behaviour a story needs verified rather than accepting "we tested it manually once."
• Serialization-risk mitigation: The default serialize/unserialize round-trip check catches a class of production-only failures (payloads that don't survive the queue) that are expensive to discover post-launch. This informs release readiness, especially before scaling traffic or adding new transports.

When to Consider This Package

Adopt when all or most of these hold:

• The product runs on Symfony and uses symfony/messenger with at least one real transport (AMQP, Redis, Doctrine, SQS) rather than only synchronous handling.
• Async behaviour is user-visible or revenue-relevant — order confirmations, billing retries, onboarding emails, sync jobs — so silent queue failures are a genuine business risk, not just an engineering nicety.
• The team already writes KernelTestCase / WebTestCase integration tests and wants queue coverage inside that existing style, not a new test framework.
• You want queue assertions in CI without standing up real broker infrastructure in the pipeline.
• You need to verify delays, retries, priority lanes, or multiple transports in a deterministic way (requires a PSR-20 clock such as symfony/clock).
• Test environments can be configured via messenger.yaml overrides — i.e., you're comfortable with test:// DSNs scoped to the test environment only.

Look elsewhere when:

• The stack is not Symfony, or Messenger isn't in use — nothing here transfers to Laravel queues, Sidekiq, Celery, or custom queue code.
• You need true broker-level fidelity: dead-letter semantics, real AMQP/SQS redelivery, visibility timeouts, consumer concurrency. This is an in-memory interceptor; it cannot validate infrastructure behaviour. Pair it with a staging environment or contract tests against the real broker.
• The dependency footprint matters more than the benefit — with 0 dependents and modest adoption (279 stars), it's a single-maintainer-style package; teams with strict third-party risk policies should weigh bus-factor against the low replacement cost (the surface area is small and replaceable by hand-rolled assertions).
• You only need "was a message dispatched?" — the README explicitly points to bus-level assertions, so a heavier setup may be unnecessary.
• The team is unwilling to maintain test:// config overrides per transport; misconfiguration here silently weakens test coverage rather than failing loudly.

Practical caveat for the pitch: the package is dev-only (--dev), so it has no production runtime footprint — adoption risk is bounded to test suites.

How to Pitch It (Stakeholders)

For executives (one paragraph): Our async features are the ones most likely to fail silently in production — a confirmation email, a payment retry, or a sync job that never runs looks fine in the UI and surfaces days later as a support ticket or a refund. This is a small, free, dev-only add-on for our Symfony stack that makes those behaviours explicitly tested before release: we can assert that a message was queued, that it was processed, and that it was rejected rather than lost. Cost is roughly a config change plus a test-writing habit; the return is catching a whole class of launch-blocking bugs in CI instead of in production. It carries no production runtime code and is easy to remove if it doesn't earn its place.

For engineering leads: It's composer require --dev zenstruck/messenger-test, register the bundle under test, and point your transports at test:// in the when@test block. You get a TestTransport plus an InteractsWithMessenger trait compatible with existing KernelTestCase/WebTestCase — no new test framework. Defaults are sensible: messages are intercepted, messages are serialized/unserialized as a correctness check, and failures land in rejected() rather than blowing up the test. You can flip to unblock() for end-to-end handler testing, throwExceptions() when you want to assert on the exception path, and support_delay_stamp=true with symfony/clock for deterministic time-based tests. Multiple transports are supported by name, and per-transport DSN flags let you tune behaviour without code.

Explicit non-goals to set expectations: It does not replace broker-level testing (real SQS/AMQP redelivery, dead-letter queues, concurrency) and does not cover non-Symfony queues. It should sit alongside, not instead of, a staging soak test for critical async paths — and it's worth scheduling a small proof-of-concept on one high-value queue before standardising it across the codebase.