Messenger Test

https://github.com/zenstruck/messenger-test
Admin
Messenger Test is a PHP library for testing Symfony Messenger code, providing a test:// transport,...
Tokens:3,854
Snippets:19
Trust Score:7.6
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install zenstruck/messenger-test

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

This snippet shows the composer command to install the zenstruck/messenger-test library as a development dependency.

```bash
composer require --dev zenstruck/messenger-test

```

--------------------------------

### Test Delayed Actions with Mocked Clock in PHP

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

Provides an example of testing code that dispatches messages with `DelayStamp` using a mocked clock. It demonstrates how to use `self::mockTime()` to control time, process messages at different intervals, and assert the status of dispatched and acknowledged messages using `transport()->process()`, `queue()->assertCount()`, and `acknowledged()->assertCount()`.

```php
// Let's say somewhere in your app, you register some actions that should occur in the future:

$bus->dispatch(new Enevelope(new TakeSomeAction1(), [DelayStamp::delayFor(new \DateInterval('P1D'))])); // will be handled in 1 day
$bus->dispatch(new Enevelope(new TakeSomeAction2(), [DelayStamp::delayFor(new \DateInterval('P3D'))])); // will be handled in 3 days

// In your test, you can check that the action is not yet performed:

class TestDelayedActions extends KernelTestCase
{
    use InteractsWithMessenger;
    use ClockSensitiveTrait;

    public function testDelayedActions(): void
    {
        // 1. mock the clock, in order to perform sleeps
        $clock = self::mockTime();

        // 2. trigger the action that will dispatch the two messages

        // ...

        // 3. assert nothing happens yet
        $transport = $this->transport('async');

        $transport->process();
        $transport->queue()->assertCount(2);
        $transport->acknowledged()->assertCount(0);

        // 4. sleep, process queue, and assert some messages have been handled
        $clock->sleep(60 * 60 * 24); // wait one day
        $transport->process()->acknowledged()->assertContains(TakeSomeAction1::class);
        $this->asssertTakeSomeAction1IsHandled();

        // TakeSomeAction2 is still in the queue
        $transport->queue()->assertCount(1);

        $clock->sleep(60 * 60 * 24 * 2); // wait two other days
        $transport->process()->acknowledged()->assertContains(TakeSomeAction2::class);
        $this->asssertTakeSomeAction2IsHandled();
    }
}
```

--------------------------------

### Enable Message Retries in Test Transport

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

Configure the test transport to enable message retries by setting `disable_retries` to `false` in the DSN. This allows testing retry logic within your messenger setup.

```yaml
when@test:
    framework:
        messenger:
            transports:
                async: test://?disable_retries=false
```

--------------------------------

### Configure Multiple Transports for Testing in YAML

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

Explains how to configure multiple messenger transports to use the `test://` DSN in the test environment. This allows you to test different transport configurations independently by specifying their names when interacting with them in your tests.

```yaml
# config/packages/messenger.yaml

# ...

when@test:
    framework:
        messenger:
            transports:
                low: test://
                high: test://

```

--------------------------------

### Configure Messenger Test Bundle

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

This PHP code snippet demonstrates how to register the ZenstruckMessengerTestBundle in your Symfony application's `config/bundles.php` file, ensuring it's only enabled for the test environment.

```php
use Zenstruck\Messenger\Test\ZenstruckMessengerTestBundle::class => ['test' => true],

```

--------------------------------

### Enable DelayStamp Support via Transport DSN in YAML

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

Shows how to enable support for `DelayStamp` on a per-transport basis using the transport DSN in messenger.yaml. Setting `support_delay_stamp=true` in the `test://` DSN allows testing of delayed message processing within the test environment.

```yaml
# config/packages/messenger.yaml

when@test:
    framework:
        messenger:
            transports:
                async: test://?support_delay_stamp=true
```

--------------------------------

### Configure Messenger Transport for Test Environment

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

This YAML configuration snippet shows how to override the default messenger transports in your Symfony application's `messenger.yaml` file for the test environment, setting them to use the 'test://' transport provided by zenstruck/messenger-test.

```yaml
# config/packages/messenger.yaml

# ...

when@test:
    framework:
        messenger:
            transports:
                async: test://

```

--------------------------------

### Process Queue with InteractsWithMessenger

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

This PHP code snippet shows how to use the `InteractsWithMessenger` trait to process messages on the queue. It includes methods for processing a specific number of messages or all messages, with options to fail if the queue is empty.

```php
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Zenstruck\Messenger\Test\InteractsWithMessenger;

class MyTest extends KernelTestCase // or WebTestCase
{
    use InteractsWithMessenger;

    public function test_something(): void
    {
        // ...some code that routes messages to your configured transport

        // let's assume 3 messages are on this queue
        $this->transport()->queue()->assertCount(3);

        $this->transport()->process(1); // process one message
        $this->transport()->processOrFail(1); // equivalent to above but fails if queue empty

        $this->transport()->queue()->assertCount(2); // queue now only has 2 items

        $this->transport()->process(); // process all messages on the queue
        $this->transport()->processOrFail(); // equivalent to above but fails if queue empty

        $this->transport()->queue()->assertEmpty(); // queue is now empty
    }
}

```

--------------------------------

### Assert Messages Dispatched on Multiple Buses

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

When using multiple buses, specify the bus name in the `bus()` method to assert messages dispatched on specific buses. This helps isolate testing for different message routing scenarios.

```php
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Zenstruck\Messenger\Test\InteractsWithMessenger;

class MyTest extends KernelTestCase
{
    use InteractsWithMessenger;

    public function test_something(): void
    {
        // ... some code that use bus

        // Let's assume two messages are handled by two different buses
        $this->bus('bus-a')->dispatched()->assertCount(1);
        $this->bus('bus-b')->dispatched()->assertCount(1);
        $this->bus('bus-c')->dispatched()->assertCount(0);

        $this->bus('bus-a')->dispatched()->assertContains(MessageA::class, 1);
        $this->bus('bus-b')->dispatched()->assertContains(MessageB::class, 1);
    }
}
```

--------------------------------

### Control Message Processing with Unblock Mode in PHP

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

Demonstrates how to manually control message processing in the TestTransport. Use `$this->transport()->unblock()` to process messages immediately as they are sent and `$this->transport()->intercept()` to return to the default queued behavior. This is useful for testing scenarios where message handling needs to be synchronized.

```php
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Zenstruck\Messenger\Test\InteractsWithMessenger;

class MyTest extends KernelTestCase // or WebTestCase
{
    use InteractsWithMessenger;

    public function test_something(): void
    {
        // disable intercept
        $this->transport()->unblock();

        // ...some code that routes messages to your configured transport
        // ...these messages are handled immediately

        // enable intercept
        $this->transport()->intercept();

        // ...some code that routes messages to your configured transport

        // if messages are on the queue when calling unblock(), they are processed
        $this->transport()->unblock();
    }
}
```

--------------------------------

### Assert Messages Dispatched on a Single Bus

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

Use the `InteractsWithMessenger` trait in `KernelTestCase` or `WebTestCase` to assert messages dispatched on the default bus. This allows verifying message counts and types without deep inspection of handlers.

```php
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Zenstruck\Messenger\Test\InteractsWithMessenger;

class MyTest extends KernelTestCase
{
    use InteractsWithMessenger;

    public function test_something(): void
    {
        // ... some code that uses the bus

        // Let's assume two messages are processed
        $this->bus()->dispatched()->assertCount(2);

        $this->bus()->dispatched()->assertContains(MessageA::class, 1);
        $this->bus()->dispatched()->assertContains(MessageB::class, 1);
    }
}
```

--------------------------------

### Testing Messenger Transports with Zenstruck

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

This PHP code demonstrates how to use Zenstruck's InteractsWithMessenger trait to test Symfony Messenger transports. It shows sending various message types, accessing and asserting on different message collections (queue, dispatched, acknowledged, rejected), and resetting transport states. It requires the Symfony Messenger component and Zenstruck Messenger Test library.

```php
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Stamp\DelayStamp;
use Zenstruck\Messenger\Test\InteractsWithMessenger;
use Zenstruck\Messenger\Test\Transport\TestTransport;

class MyTest extends KernelTestCase // or WebTestCase
{
    use InteractsWithMessenger;

    public function test_something(): void
    {
        // manually send a message to your transport
        $this->transport()->send(new MyMessage());

        // send with stamps
        $this->transport()->send(Envelope::wrap(new MyMessage(), [new SomeStamp()]));

        // send "pre-encoded" message
        $this->transport()->send(['body' => '...']);

        $queue = $this->transport()->queue();
        $dispatched = $this->transport()->dispatched();
        $acknowledged = $this->transport()->acknowledged(); // messages successfully processed
        $rejected = $this->transport()->rejected(); // messages not successfully processed

        // The 4 above variables are all instances of Zenstruck\Messenger\Test\EnvelopeCollection
        // which is a countable iterator with the following api (using $queue for the example).
        // Methods that return Envelope(s) actually return TestEnvelope(s) which is an Envelope
        // decorator (all standard Envelope methods can be used) with some stamp-related assertions.

        // collection assertions
        $queue->assertEmpty();
        $queue->assertNotEmpty();
        $queue->assertCount(3);
        $queue->assertContains(MyMessage::class); // contains this message
        $queue->assertContains(MyMessage::class, 3); // contains this message 3 times
        $queue->assertNotContains(MyMessage::class); // not contains this message

        // helpers
        $queue->count(); // number of envelopes
        $queue->all(); // TestEnvelope[]
        $queue->messages(); // object[] the messages unwrapped from their envelope
        $queue->messages(MyMessage::class); // MyMessage[] just instances of the passed message class

        // get specific envelope
        $queue->first(); // TestEnvelope - first one on the collection
        $queue->first(MyMessage::class); // TestEnvelope - first where message class is MyMessage
        $queue->first(function(Envelope $e): bool {
            return $e->getMessage() instanceof MyMessage && $e->getMessage()->isSomething();
        }); // TestEnvelope - first that matches the filter callback

        // Equivalent to above - use the message class as the filter function typehint to
        // auto-filter to this message type.
        $queue->first(fn(MyMessage $m): bool => $m->isSomething()); // TestEnvelope

        // TestEnvelope stamp assertions
        $queue->first()->assertHasStamp(DelayStamp::class);
        $queue->first()->assertNotHasStamp(DelayStamp::class);

        // reset collected messages on the transport
        $this->transport()->reset();

        // reset collected messages for all transports
        TestTransport::resetAll();

        // fluid assertions on different EnvelopeCollections
        $this->transport()
            ->queue()
                ->assertNotEmpty()
                ->assertContains(MyMessage::class)
            ->back() // returns to the TestTransport
            ->dispatched()
                ->assertEmpty()
            ->back()
            ->acknowledged()
                ->assertEmpty()
            ->back()
            ->rejected()
                ->assertEmpty()
            ->back()
        ;
    }
}

```

--------------------------------

### Queue Assertions with InteractsWithMessenger

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

This PHP code snippet demonstrates how to use the `InteractsWithMessenger` trait in a Symfony KernelTestCase or WebTestCase to perform various assertions on the message queue. It includes checking for emptiness, count, presence, and absence of specific message types.

```php
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Zenstruck\Messenger\Test\InteractsWithMessenger;

class MyTest extends KernelTestCase // or WebTestCase
{
    use InteractsWithMessenger;

    public function test_something(): void
    {
        // ...some code that routes messages to your configured transport

        // assert against the queue
        $this->transport()->queue()->assertEmpty();
        $this->transport()->queue()->assertNotEmpty();
        $this->transport()->queue()->assertCount(3);
        $this->transport()->queue()->assertContains(MyMessage::class); // queue contains this message
        $this->transport()->queue()->assertContains(MyMessage::class, 3); // queue contains this message 3 times
        $this->transport()->queue()->assertContains(MyMessage::class, 0); // queue contains this message 0 times
        $this->transport()->queue()->assertNotContains(MyMessage::class); // queue not contains this message

        // access the queue data
        $this->transport()->queue(); // Envelope[]
        $this->transport()->queue()->messages(); // object[] the messages unwrapped from envelope
        $this->transport()->queue()->messages(MyMessage::class); // MyMessage[] just messages matching class
    }
}

```

--------------------------------

### Processing Messenger Exceptions with TestTransport

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

This PHP code snippet illustrates how to control exception handling within the Zenstruck TestTransport. It shows how to temporarily disable exception catching to allow exceptions to propagate during message processing and how to re-enable it. This is useful for testing how your application handles message processing failures.

```php
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Zenstruck\Messenger\Test\InteractsWithMessenger;

class MyTest extends KernelTestCase // or WebTestCase
{
    use InteractsWithMessenger;

    public function test_something(): void
    {
        // ...some code that routes messages to your configured transport

        // disable exception catching
        $this->transport()->throwExceptions();

        // if processing fails, the exception will be thrown
        $this->transport()->process(1);

        // re-enable exception catching
        $this->transport()->catchExceptions();
    }
}

```

--------------------------------

### Interact with Specific Transports in PHP Tests

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

Demonstrates how to target specific messenger transports by name when using the `InteractsWithMessenger` trait in PHP tests. The `$this->transport('transport_name')` method allows you to queue or assert dispatched messages for individual transports, facilitating tests with multiple configured transports.

```php
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Zenstruck\Messenger\Test\InteractsWithMessenger;

class MyTest extends KernelTestCase // or WebTestCase
{
    use InteractsWithMessenger;

    public function test_something(): void
    {
        $this->transport('high')->queue();
        $this->transport('low')->dispatched();
    }
}
```

--------------------------------

### Configuring Default Exception Throwing for Test Transports

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

This YAML configuration snippet shows how to set the `catch_exceptions` parameter to `false` directly in the Messenger transport DSN within your Symfony application's configuration. This will cause all transports of type 'test://' to throw exceptions by default during message processing in a test environment.

```yaml
# config/packages/messenger.yaml

# ...

when@test:
    framework:
        messenger:
            transports:
                async: test://?catch_exceptions=false
 
```

--------------------------------

### Configure Unblock Mode via Transport DSN in YAML

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

Shows how to disable message interception by default for a specific transport using its DSN in the messenger.yaml configuration file. Setting `intercept=false` in the `test://` DSN ensures messages are handled immediately upon sending for that transport in the test environment.

```yaml
# config/packages/messenger.yaml

# ...

when@test:
    framework:
        messenger:
            transports:
                async: test://?intercept=false
```

--------------------------------

### Disable Serialization Testing via Transport DSN in YAML

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

Illustrates how to disable the automatic serialization and deserialization testing for messages in the TestTransport. By appending `?test_serialization=false` to the `test://` DSN in messenger.yaml, you can bypass this default behavior for specified transports in your test environment.

```yaml
# config/packages/messenger.yaml

# ...

when@test:
    framework:
        messenger:
            transports:
                async: test://?test_serialization=false
```

--------------------------------

### Disable Doctrine Entity Manager Clearing in Test Environment

Source: https://github.com/zenstruck/messenger-test/blob/1.x/README.md

To prevent Doctrine entities from becoming detached after message processing in tests, disable the `DoctrineClearEntityManagerWorkerSubscriber` service by aliasing it to `stdClass` in your test environment configuration.

```yaml
# config/packages/messenger.yaml

# ...

when@test:
    # ...

    services:
        # DoctrineClearEntityManagerWorkerSubscriber service
        doctrine.orm.messenger.event_subscriber.doctrine_clear_entity_manager:
            class: stdClass # effectively disables this service in your test env
```
Tokens:
Raw