feature #3136 [LiveComponent] Add dispatch browser event assertion in InteractsWithLiveComponents (Develog)

This PR was merged into the 2.x branch.

Discussion
----------

[LiveComponent] Add dispatch browser event assertion in InteractsWithLiveComponents

| Q              | A
| -------------- | ---
| Bug fix?       | no
| New feature?   | yes <!-- please update src/**/CHANGELOG.md files -->
| Deprecations?  | no <!-- if yes, also update UPGRADE-*.md and src/**/CHANGELOG.md -->
| Documentation? | yes <!-- required for new features, or documentation updates -->
| Issues         | no <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead -->
| License        | MIT

Next to this PR #2712 I wanted to add test assertion on dispatchBrowserEvent and not only on emited event.
I reuse same logic as the `ComponentWithEmit.php`.

```
$this->assertComponentDispatchEvent($testComponent->render(), 'browserEvent')
    ->withPayload(['amount' => 2, 'unit' => 'kg'])
    ->withPayloadSubset(['amount' => 2]) ;
```

`$this->assertComponentNotDispatchEvent($testComponent->render(), 'otherBrowserEvent');`

Commits
-------

5943c89 [LiveComponent] Add dispatch browser event test

Author: Kocal

src/LiveComponent/CHANGELOG.md

@@ -1,5 +1,24 @@
 # CHANGELOG
 
+## 2.31
+
+-  Add browser events assertions in `InteractsWithLiveComponents`:
+```php
+$testComponent = $this->createLiveComponent(name: 'MyComponent');
+
+$renderedComponent = $testComponent->render();
+
+// Assert that the component did dispatch a browser event named 'browser:event'
+$this->assertComponentDispatchBrowserEvent($render, 'browser:event')
+    // optionally, you can assert that the browser event was dispatched with specific data...
+    ->withData(['arg1' => 'foo', 'arg2' => 'bar'])
+    // ... or only with a subset of data
+    ->withDataSubset(['arg1' => 'foo']);
+
+// Assert that the component did not dispatch a browser event named 'another-browser:event'
+$this->assertComponentNotDispatchBrowserEvent($render, 'another-browser:event');
+```
+
 ## 2.30
 
 -  Ensure compatibility with PHP 8.5

src/LiveComponent/doc/index.rst

@@ -3851,6 +3851,23 @@ uses Symfony's test client to render and make requests to your components::
             // Assert that an event was not emitted
             $this->assertComponentNotEmitEvent($testComponent->render(), 'decreaseEvent');
 
+            // dispatch browser events
+            $testComponent
+                ->dispatchBrowserEvent('browserEvent')
+                ->dispatchBrowserEvent('browserEvent', ['amount' => 2, 'unit' => 'kg']) // dispatch a browser event with arguments
+            ;
+
+            // Assert that the event was dispatched
+            $this->assertComponentDispatchBrowserEvent($testComponent->render(), 'browserEvent')
+                // optionally, you can assert that the event was dispatched with specific data...
+                ->withPayload(['amount' => 2, 'unit' => 'kg'])
+                // ... or only with a subset of data
+                ->withPayloadSubset(['amount' => 2])
+            ;
+
+            // Assert that an event was not dispatched
+            $this->assertComponentNotDispatchBrowserEvent($testComponent->render(), 'otherBrowserEvent');
+
             // set live props
             $testComponent
                 ->set('count', 99)

src/LiveComponent/src/Test/InteractsWithLiveComponents.php

@@ -13,6 +13,7 @@
 
 use Symfony\Bundle\FrameworkBundle\KernelBrowser;
 use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
+use Symfony\UX\LiveComponent\Test\Util\AssertDispatchedEvent;
 use Symfony\UX\LiveComponent\Test\Util\AssertEmittedEvent;
 use Symfony\UX\TwigComponent\ComponentFactory;
 
@@ -59,4 +60,24 @@ protected function assertComponentNotEmitEvent(TestLiveComponent $testLiveCompon
     {
         self::assertNull($testLiveComponent->getEmittedEvent($testLiveComponent->render(), $eventName), \sprintf('The component "%s" did emit event "%s".', $testLiveComponent->getName(), $eventName));
     }
+
+    protected function assertComponentDispatchBrowserEvent(TestLiveComponent $testLiveComponent, string $expectedEventName): AssertDispatchedEvent
+    {
+        $event = $testLiveComponent->getDispatchedBrowserEvent($testLiveComponent->render(), $expectedEventName);
+
+        self::assertNotNull(
+            $event,
+            \sprintf('The component "%s" did no dispatch browser event "%s".', $testLiveComponent->getName(), $expectedEventName)
+        );
+
+        return new AssertDispatchedEvent($this, $event['event'], $event['payload']);
+    }
+
+    protected function assertComponentNotDispatchBrowserEvent(TestLiveComponent $testLiveComponent, string $eventName): void
+    {
+        self::assertNull(
+            $testLiveComponent->getDispatchedBrowserEvent($testLiveComponent->render(), $eventName),
+            \sprintf('The component "%s" did dispatch browser event "%s".', $testLiveComponent->getName(), $eventName)
+        );
+    }
 }

src/LiveComponent/src/Test/TestLiveComponent.php

@@ -12,6 +12,7 @@
 namespace Symfony\UX\LiveComponent\Test;
 
 use Symfony\Bundle\FrameworkBundle\KernelBrowser;
+use Symfony\Component\DomCrawler\Crawler;
 use Symfony\Component\HttpFoundation\File\UploadedFile;
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
@@ -251,7 +252,7 @@ public function getEmittedEvent(RenderedComponent $render, string $eventName): ?
      */
     public function getEmittedEvents(RenderedComponent $render): array
     {
-        $emit = $render->crawler()->filter('[data-live-name-value]')->attr('data-live-events-to-emit-value');
+        $emit = $this->getComponentNameValue($render)->attr('data-live-events-to-emit-value');
 
         if (null === $emit) {
             return [];
@@ -260,6 +261,41 @@ public function getEmittedEvents(RenderedComponent $render): array
         return json_decode($emit, associative: true, flags: \JSON_THROW_ON_ERROR);
     }
 
+    /**
+     * @return ?array{data: array<string, int|float|string|bool|null>, event: non-empty-string}
+     */
+    public function getDispatchedBrowserEvent(RenderedComponent $render, string $eventName): ?array
+    {
+        $events = $this->getDispatchedBrowserEvents($render);
+
+        foreach ($events as $event) {
+            if ($event['event'] === $eventName) {
+                return $event;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * @return array<array{data: array<string, int|float|string|bool|null>, event: non-empty-string}>
+     */
+    public function getDispatchedBrowserEvents(RenderedComponent $render): array
+    {
+        $dispatch = $this->getComponentNameValue($render)->attr('data-live-events-to-dispatch-value');
+
+        if (null === $dispatch) {
+            return [];
+        }
+
+        return json_decode($dispatch, associative: true, flags: \JSON_THROW_ON_ERROR);
+    }
+
+    private function getComponentNameValue(RenderedComponent $render): Crawler
+    {
+        return $render->crawler()->filter('[data-live-name-value]');
+    }
+
     public function getName(): string
     {
         return $this->metadata->getName();

src/LiveComponent/src/Test/Util/AssertDispatchedEvent.php

@@ -0,0 +1,59 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\LiveComponent\Test\Util;
+
+use PHPUnit\Framework\TestCase;
+
+final class AssertDispatchedEvent
+{
+    /**
+     * @param array<string, int|float|string|bool|null> $payload
+     */
+    public function __construct(
+        private readonly TestCase $testCase,
+        private readonly string $eventName,
+        private readonly array $payload,
+    ) {
+    }
+
+    /**
+     * @return self
+     */
+    public function withPayloadSubset(array $expectedEventPayload): object
+    {
+        foreach ($expectedEventPayload as $key => $value) {
+            $this->testCase::assertArrayHasKey($key, $this->payload, \sprintf('The expected event "%s" data "%s" does not exists', $this->eventName, $key));
+            $this->testCase::assertSame(
+                $value,
+                $this->payload[$key],
+                \sprintf(
+                    'The event "%s" data "%s" expect to be "%s", but "%s" given.',
+                    $this->eventName,
+                    $key,
+                    $value,
+                    $this->payload[$key]
+                )
+            );
+        }
+
+        return $this;
+    }
+
+    public function withPayload(array $expectedEventPayload): void
+    {
+        $this->testCase::assertEquals(
+            $expectedEventPayload,
+            $this->payload,
+            \sprintf('The event "%s" payload is different than expected.', $this->eventName)
+        );
+    }
+}

src/LiveComponent/tests/Fixtures/Component/ComponentWithEmit.php

@@ -24,7 +24,8 @@ final class ComponentWithEmit
     use DefaultActionTrait;
     use ComponentToolsTrait;
 
-    public $events = [];
+    public array $events = [];
+    public array $dispatchEvents = [];
 
     #[LiveAction]
     public function actionThatEmits(): void
@@ -36,9 +37,13 @@ public function actionThatEmits(): void
     #[LiveAction]
     public function actionThatDispatchesABrowserEvent(): void
     {
-        $this->liveResponder->dispatchBrowserEvent(
+        $this->dispatchBrowserEvent(
             'browser-event',
-            ['fooKey' => 'barVal'],
+            [
+                'fooKey' => 'barVal',
+                'barKey' => 'fooVal',
+            ],
         );
+        $this->dispatchEvents = $this->liveResponder->getBrowserEventsToDispatch();
     }
 }

src/LiveComponent/tests/Fixtures/templates/components/component_with_emit.html.twig

@@ -5,4 +5,9 @@
         Event: {{ event.event }}<br>
         Data: {{ event.data|json_encode|raw }}<br>
     {% endfor %}
+
+    {% for event in dispatchEvents %}
+        Event: {{ event.event }}<br>
+        Payload: {{ event.payload|json_encode|raw }}<br>
+    {% endfor %}
 </div>

src/LiveComponent/tests/Functional/LiveResponderTest.php

@@ -49,6 +49,8 @@ public function testComponentCanDispatchBrowserEvents()
                 'body' => ['data' => json_encode(['props' => $dehydrated->getProps()])],
             ])
             ->assertSuccessful()
+            ->assertSee('Event: browser-event')
+            ->assertSee('Payload: {"fooKey":"barVal","barKey":"fooVal"}')
             ->crawler()
         ;
 
@@ -57,7 +59,7 @@ public function testComponentCanDispatchBrowserEvents()
         $this->assertNotNull($browserDispatch);
         $browserDispatchData = json_decode($browserDispatch, true);
         $this->assertSame([
-            ['event' => 'browser-event', 'payload' => ['fooKey' => 'barVal']],
+            ['event' => 'browser-event', 'payload' => ['fooKey' => 'barVal', 'barKey' => 'fooVal']],
         ], $browserDispatchData);
     }
 }

src/LiveComponent/tests/Functional/Test/InteractsWithLiveComponentsTest.php

@@ -290,4 +290,76 @@ public function testComponentEmitsEventWithIncorrectDataFails()
             'foo2' => 'bar2',
         ]);
     }
+
+    public function testAssertComponentDispatchBrowserEvent()
+    {
+        $testComponent = $this->createLiveComponent('component_with_emit');
+
+        $testComponent->call('actionThatDispatchesABrowserEvent');
+
+        $this->assertComponentDispatchBrowserEvent($testComponent, 'browser-event')
+            ->withPayload([
+                'fooKey' => 'barVal',
+                'barKey' => 'fooVal',
+            ]);
+    }
+
+    public function testAssertComponentDispatchBrowserEventFails()
+    {
+        $testComponent = $this->createLiveComponent('component_with_emit');
+
+        $testComponent->call('actionThatDispatchesABrowserEvent');
+
+        $this->expectException(AssertionFailedError::class);
+        $this->expectExceptionMessage('The event "browser-event" payload is different than expected.');
+        $this->assertComponentDispatchBrowserEvent($testComponent, 'browser-event')->withPayload([
+            'fooKey' => 'barVal',
+        ]);
+    }
+
+    public function testComponentDispatchesExpectedPartialBrowserEventData()
+    {
+        $testComponent = $this->createLiveComponent('component_with_emit');
+
+        $testComponent->call('actionThatDispatchesABrowserEvent');
+
+        $this->assertComponentDispatchBrowserEvent($testComponent, 'browser-event')
+            ->withPayloadSubset(['fooKey' => 'barVal'])
+            ->withPayloadSubset(['barKey' => 'fooVal'])
+        ;
+    }
+
+    public function testComponentDoesNotDispatchUnexpectedBrowserEvent()
+    {
+        $testComponent = $this->createLiveComponent('component_with_emit');
+
+        $testComponent->call('actionThatDispatchesABrowserEvent');
+
+        $this->assertComponentNotDispatchBrowserEvent($testComponent, 'browser-event2');
+    }
+
+    public function testComponentDoesNotDispatchUnexpectedBrowserEventFails()
+    {
+        $testComponent = $this->createLiveComponent('component_with_emit');
+
+        $testComponent->call('actionThatDispatchesABrowserEvent');
+
+        $this->expectException(AssertionFailedError::class);
+        $this->expectExceptionMessage('The component "component_with_emit" did dispatch browser event "browser-event".');
+        $this->assertComponentNotDispatchBrowserEvent($testComponent, 'browser-event');
+    }
+
+    public function testComponentDispatchesBrowserEventWithIncorrectDataFails()
+    {
+        $testComponent = $this->createLiveComponent('component_with_emit');
+
+        $testComponent->call('actionThatDispatchesABrowserEvent');
+
+        $this->expectException(AssertionFailedError::class);
+        $this->expectExceptionMessage('The event "browser-event" payload is different than expected.');
+        $this->assertComponentDispatchBrowserEvent($testComponent, 'browser-event')->withPayload([
+            'fooKey' => 'barVal',
+            'fooKey2' => 'barVal2',
+        ]);
+    }
 }