Download the PHP package zenstruck/messenger-test without Composer

zenstruck/messenger-test

Assertions and helpers for testing your symfony/messenger queues.

This library provides a TestTransport that, by default, intercepts any messages sent to it. You can then inspect and assert against these messages. Sent messages are serialized and unserialized as an added check.

The transport also allows for processing these queued messages.

Installation

1. Install the library:

2. If not added automatically by Symfony Flex, add the bundle in config/bundles.php:

3. Update config/packages/messenger.yaml and override your transport(s) in your test environment with test://:

Transport

You can interact with the test transports in your tests by using the InteractsWithMessenger trait in your KernelTestCase/WebTestCase tests. You can assert the different steps of message processing by asserting on the queue and the different states of message processing like "acknowledged", "rejected" and so on.

Note: If you only need to know if a message has been dispatched you can make assertions on the bus itself.

Queue Assertions

Processing The Queue

NOTE: Calling process() not only processes messages on the queue but any messages created during the handling of messages (all by default or up to $number).

Other Transport Assertions and Helpers

Processing Exceptions

By default, when processing a message that fails, the TestTransport catches the exception and adds to the rejected list. You can change this behaviour:

You can enable exception throwing for your transport(s) by default in the transport dsn:

Unblock Mode

By default, messages sent to the TestTransport are intercepted and added to a queue, waiting to be processed manually. You can change this behaviour so messages are handled as they are sent:

You can disable intercepting messages for your transport(s) by default in the transport dsn:

Testing Serialization

By default, the TestTransport tests that messages can be serialized and deserialized. This behavior can be disabled with the transport dsn:

Multiple Transports

If you have multiple transports you'd like to test, change all their dsn's to test:// in your test environment:

In your tests, pass the name to the transport() method:

Support of DelayStamp

Support of DelayStamp could be enabled per transport, within its dsn:

[!NOTE] Support of delay stamp was added in version 1.8.0.

Usage of a clock

[!WARNING] Support of delay stamp needs an implementation of PSR-20 Clock.

You can, for example use Symfony's clock component:

When using Symfony's clock component, the service will be automatically configured. Otherwise, you need to configure it manually:

Example of code supporting DelayStamp

[!NOTE] This example uses symfony/clock component, but you can use any other implementation of Psr\Clock\ClockInterface.

DelayStamp and unblock mode

"delayed" messages cannot be handled by the unblocking mechanism, $transport->process() must be called after a sleep() has been made.

Enable Retries

By default, the TestTransport does not retry failed messages (your retry settings are ignored). This behavior can be disabled with the transport dsn:

[!NOTE] When using retries along with support_delay_stamp you must mock the time to sleep between retries.

Bus

In addition to transport testing you also can make assertions on the bus. You can test message handling by using the same InteractsWithMessenger trait in your KernelTestCase / WebTestCase tests. This is especially useful when you only need to test if a message has been dispatched by a specific bus but don't need to know how the handling has been made.

It allows you to use your custom transport while asserting your messages are still dispatched properly.

Single bus

Multiple buses

If you use multiple buses you can test that a specific bus has handled its own messages.

In your tests, pass the name to the bus() method:

Troubleshooting

Detached Doctrine Entities

When processing messages in your tests that interact with Doctrine entities you may notice they become detached from the object manager after processing. This is because of DoctrineClearEntityManagerWorkerSubscriber which clears the object managers after a message is processed. Currently, the only way to disable this functionality is to disable the service in your test environment: