Better explain orphan events (#116)

Author: TavoNiievez

src/Codeception/Module/Symfony/EventsAssertionsTrait.php

@@ -14,30 +14,35 @@
 trait EventsAssertionsTrait
 {
     /**
-     * Verifies that one or more orphan events were not dispatched during the test.
+     * Verifies that there were no orphan events during the test.
      *
-     * An orphan event is an event that is triggered by manually executing the
+     * An orphan event is an event that was triggered by manually executing the
      * [`dispatch()`](https://symfony.com/doc/current/components/event_dispatcher.html#dispatch-the-event) method
-     * of the EventDispatcher, in other words, it is an event that is not handled by any listener.
+     * of the EventDispatcher but was not handled by any listener after it was dispatched.
      *
      * ```php
      * <?php
-     * $I->dontSeeOrphanEventTriggered('App\MyEvent');
-     * $I->dontSeeOrphanEventTriggered(new App\Events\MyEvent());
-     * $I->dontSeeOrphanEventTriggered(['App\MyEvent', 'App\MyOtherEvent']);
+     * $I->dontSeeOrphanEvent();
+     * $I->dontSeeOrphanEvent('App\MyEvent');
+     * $I->dontSeeOrphanEvent(new App\Events\MyEvent());
+     * $I->dontSeeOrphanEvent(['App\MyEvent', 'App\MyOtherEvent']);
      * ```
      *
      * @param string|object|string[] $expected
      */
-    public function dontSeeOrphanEventTriggered($expected): void
+    public function dontSeeOrphanEvent($expected = null): void
     {
         $eventCollector = $this->grabEventCollector(__FUNCTION__);
 
         /** @var Data $data */
         $data = $eventCollector->getOrphanedEvents();
         $expected = is_array($expected) ? $expected : [$expected];
 
-        $this->assertEventNotTriggered($data, $expected);
+        if ($expected === null) {
+            $this->assertSame(0, $data->count());
+        } else {
+            $this->assertEventNotTriggered($data, $expected);
+        }
     }
 
     /**
@@ -66,20 +71,20 @@ public function dontSeeEventTriggered($expected): void
     /**
      * Verifies that one or more orphan events were dispatched during the test.
      *
-     * An orphan event is an event that is triggered by manually executing the
+     * An orphan event is an event that was triggered by manually executing the
      * [`dispatch()`](https://symfony.com/doc/current/components/event_dispatcher.html#dispatch-the-event) method
-     * of the EventDispatcher, in other words, it is an event that is not handled by any listener.
+     * of the EventDispatcher but was not handled by any listener after it was dispatched.
      *
      * ```php
      * <?php
-     * $I->seeOrphanEventTriggered('App\MyEvent');
-     * $I->seeOrphanEventTriggered(new App\Events\MyEvent());
-     * $I->seeOrphanEventTriggered(['App\MyEvent', 'App\MyOtherEvent']);
+     * $I->seeOrphanEvent('App\MyEvent');
+     * $I->seeOrphanEvent(new App\Events\MyEvent());
+     * $I->seeOrphanEvent(['App\MyEvent', 'App\MyOtherEvent']);
      * ```
      *
      * @param string|object|string[] $expected
      */
-    public function seeOrphanEventTriggered($expected): void
+    public function seeOrphanEvent($expected): void
     {
         $eventCollector = $this->grabEventCollector(__FUNCTION__);
 
@@ -115,10 +120,6 @@ public function seeEventTriggered($expected): void
 
     protected function assertEventNotTriggered(Data $data, array $expected): void
     {
-        if ($data->count() === 0) {
-            $this->fail('No event was triggered');
-        }
-
         $actual = $data->getValue(true);
 
         foreach ($expected as $expectedEvent) {
@@ -132,6 +133,10 @@ protected function assertEventNotTriggered(Data $data, array $expected): void
 
     protected function assertEventTriggered(Data $data, array $expected): void
     {
+        if ($data->count() === 0) {
+            $this->fail('No event was triggered');
+        }
+
         $actual = $data->getValue(true);
 
         foreach ($expected as $expectedEvent) {
@@ -148,8 +153,14 @@ protected function eventWasTriggered(array $actual, string $expectedEvent): bool
         $triggered = false;
 
         foreach ($actual as $actualEvent) {
-            if (strpos($actualEvent['pretty'], $expectedEvent) === 0) {
-                $triggered = true;
+            if (is_array($actualEvent)) { // Called Listeners
+                if (strpos($actualEvent['pretty'], $expectedEvent) === 0) {
+                    $triggered = true;
+                }
+            } else { // Orphan Events
+                if ($actualEvent === $expectedEvent) {
+                    $triggered = true;
+                }
             }
         }
         return $triggered;