Event Testing

This document explains how to test event dispatching in your application using the EventFake class. Event testing allows you to verify that specific events are dispatched during code execution without actually executing their listeners, preventing side effects and improving test isolation.

For information about the production event system, see Event System. For an overview of all testing capabilities, see Testing Overview. For general facade mocking strategies, see Facade Mocking.

---

Overview

The event testing system intercepts events dispatched via the Event facade and records them for inspection instead of executing their listeners. This enables you to:

• Verify that specific events were dispatched with correct payloads
• Assert that events were not dispatched
• Count how many times an event was dispatched
• Inspect dispatched event data
• Test only specific events while allowing others to execute normally

Sources: src/Testing/Fakes/EventFake.php1-327 src/Facades/Event.php1-105

---

Event Fake Architecture

Event Testing Flow

The fake intercepts events at the dispatcher level, records them based on configuration, and provides inspection methods for assertions.

Sources: src/Testing/Fakes/EventFake.php17-327 src/Facades/Event.php40-105

---

Basic Event Faking

Faking All Events

The Event::fake() method replaces the real event dispatcher with an EventFake instance that records all dispatched events without executing their listeners:

When called without arguments, Event::fake() intercepts all events. The method returns an EventFake instance and also registers it with the database model event system and cache layer.

Sources: src/Facades/Event.php45-53 src/Testing/Fakes/EventFake.php45-49

Faking Specific Events

To fake only specific events while allowing others to dispatch normally, pass event class names to Event::fake():

The shouldFakeEvent() method at src/Testing/Fakes/EventFake.php249-262 determines which events to intercept. If eventsToFake is empty, all events are faked. Otherwise, only specified events are intercepted.

Sources: src/Testing/Fakes/EventFake.php45-49 src/Testing/Fakes/EventFake.php249-262

---

Selective Faking Strategies

Faking Except Specific Events

The fakeExcept() method inverts the logic—it fakes all events except those specified:

This uses a closure-based filter at src/Facades/Event.php58-65 to exclude specified events from faking.

Sources: src/Facades/Event.php58-65

Excluding Events with except()

After creating a fake, use the except() method to specify additional events that should dispatch normally:

The except() method at src/Testing/Fakes/EventFake.php54-62 adds events to the eventsToDispatch array, which is checked by shouldDispatchEvent() at src/Testing/Fakes/EventFake.php275-288

Sources: src/Testing/Fakes/EventFake.php54-62 src/Testing/Fakes/EventFake.php275-288

Dynamic Filtering with Closures

Both fake() and fakeExcept() accept closures for dynamic filtering:

The closure receives the event name and payload, and returns true to fake the event or false to dispatch it normally. This is evaluated at src/Testing/Fakes/EventFake.php256-260

Sources: src/Testing/Fakes/EventFake.php256-260 src/Testing/Fakes/EventFake.php282-285

---

Event Filtering Decision Matrix

Configuration	Empty eventsToFake	Specified eventsToFake	Event in eventsToDispatch
Action	Fake all events	Fake only specified	Always dispatch
Methods	Event::fake()	Event::fake(['Event'])	->except(['Event'])
Priority	Lowest	Medium	Highest

The dispatch decision logic at src/Testing/Fakes/EventFake.php231-244 follows this hierarchy:

1. Check if event should be faked via shouldFakeEvent()
2. If yes, record to events array
3. If no, forward to real dispatcher

Sources: src/Testing/Fakes/EventFake.php231-244 src/Testing/Fakes/EventFake.php249-262

---

Event Assertions

assertDispatched

Verifies that an event was dispatched at least once:

With a callback for conditional assertion:

With a count:

The implementation at src/Testing/Fakes/EventFake.php100-115 supports three parameter types:

• String event name: asserts dispatched at least once
• Closure as first parameter: extracts event type from closure parameter type hint
• Integer as second parameter: delegates to assertDispatchedTimes()

Sources: src/Testing/Fakes/EventFake.php100-115

assertDispatchedTimes

Verifies an event was dispatched exactly N times:

The implementation at src/Testing/Fakes/EventFake.php120-129 uses PHPUnit's assertSame() to ensure exact count matching.

Sources: src/Testing/Fakes/EventFake.php120-129

assertNotDispatched

Verifies that an event was not dispatched:

With a callback:

The implementation at src/Testing/Fakes/EventFake.php134-145 asserts that the filtered collection is empty.

Sources: src/Testing/Fakes/EventFake.php134-145

assertNothingDispatched

Verifies that no events of any type were dispatched:

This flattens the entire events array at src/Testing/Fakes/EventFake.php150-159 and asserts the count is zero.

Sources: src/Testing/Fakes/EventFake.php150-159

assertListening

Verifies that a listener is registered for an event:

This introspects the real dispatcher's listeners at src/Testing/Fakes/EventFake.php67-95 using reflection to extract the actual listener class from closure wrappers.

Sources: src/Testing/Fakes/EventFake.php67-95

---

Assertion Method Reference

Assertion and Inspection Method Relationships

All assertion methods ultimately query the events array, with dispatched() serving as the primary filtering mechanism.

Sources: src/Testing/Fakes/EventFake.php40-327

---

Event Inspection

dispatched()

Returns a collection of all dispatched events matching the criteria:

The method at src/Testing/Fakes/EventFake.php164-177 returns a Collection instance containing the event arguments for each dispatch. Each element is an array of arguments passed to dispatch().

Sources: src/Testing/Fakes/EventFake.php164-177

hasDispatched()

Returns a boolean indicating whether an event was dispatched:

The implementation at src/Testing/Fakes/EventFake.php182-185 checks if the event exists in the events array and is non-empty.

Sources: src/Testing/Fakes/EventFake.php182-185

dispatchedEvents()

Returns the complete raw events array:

This provides access to the internal events storage at src/Testing/Fakes/EventFake.php315-318

Sources: src/Testing/Fakes/EventFake.php315-318

---

Event Storage Structure

The EventFake stores dispatched events in a nested array structure:

Each entry contains the arguments passed to dispatch():

1. Event object or name
2. Payload array
3. Halt flag

This structure is populated at src/Testing/Fakes/EventFake.php236 when shouldFakeEvent() returns true.

Sources: src/Testing/Fakes/EventFake.php39-40 src/Testing/Fakes/EventFake.php231-244

---

Scoped Faking

fakeFor()

Executes a callback with event faking, then restores the original dispatcher:

The implementation at src/Facades/Event.php70-82 saves the original dispatcher, activates the fake, executes the callback, then restores the original via tap().

Sources: src/Facades/Event.php70-82

fakeExceptFor()

Like fakeFor() but uses fakeExcept() for inverse filtering:

The implementation at src/Facades/Event.php87-99 follows the same pattern as fakeFor() but calls fakeExcept() instead.

Sources: src/Facades/Event.php87-99

---

Integration with Database Models

When Event::fake() is called, it registers the fake with Hyperf's database model event system:

This occurs at src/Facades/Event.php49-50 to ensure model events (like created, updated, deleted) are also captured by the fake. The Cache facade must refresh its event dispatcher reference to maintain consistency.

Sources: src/Facades/Event.php45-53

---

EventFake Implementation Details

EventFake Internal Architecture

The fake maintains the original dispatcher for forwarding, configuration arrays for filtering, and a recording array for assertions.

Sources: src/Testing/Fakes/EventFake.php17-327

Traits Used

The EventFake class uses two traits:

Trait	Purpose	Usage
ForwardsCalls	Forwards unknown method calls to real dispatcher	src/Testing/Fakes/EventFake.php19
ReflectsClosures	Extracts parameter types from closures	src/Testing/Fakes/EventFake.php20

The ReflectsClosures trait enables the closure-as-first-parameter syntax at src/Testing/Fakes/EventFake.php102-103 by extracting the type hint from the closure's first parameter.

Sources: src/Testing/Fakes/EventFake.php19-20 src/Testing/Fakes/EventFake.php102-103

Method Forwarding

Methods not implemented by EventFake are forwarded to the real dispatcher using the ForwardsCalls trait at src/Testing/Fakes/EventFake.php323-326 This includes:

• listen() - Registers listeners with real dispatcher
• hasListeners() - Checks real dispatcher for listeners
• subscribe() - Registers subscribers with real dispatcher

This ensures that listener registration continues to work normally even when events are faked.

Sources: src/Testing/Fakes/EventFake.php189-219 src/Testing/Fakes/EventFake.php323-326

---

Testing Patterns

Testing Event Payload

Verify specific event properties:

The callback receives the dispatched event arguments and returns true if the assertion should pass.

Sources: src/Testing/Fakes/EventFake.php100-115 src/Testing/Fakes/EventFake.php164-177

Testing Multiple Event Types

Assert multiple events in sequence:

Each assertion independently queries the events array.

Testing Event Order

Inspect the dispatchedEvents() array to verify dispatch order:

Sources: src/Testing/Fakes/EventFake.php315-318

Selective Testing with Partial Faking

Test critical events while allowing infrastructure events to dispatch:

This is useful for integration tests where you need some side effects but want to isolate business-critical events.

Sources: src/Testing/Fakes/EventFake.php54-62 src/Facades/Event.php58-65

---

Common Testing Scenarios

Scenario	Method	Example
Event dispatched	assertDispatched()	Event::assertDispatched(OrderShipped::class)
Event not dispatched	assertNotDispatched()	Event::assertNotDispatched(OrderCancelled::class)
Event count	assertDispatchedTimes()	Event::assertDispatchedTimes(OrderShipped::class, 2)
No events	assertNothingDispatched()	Event::assertNothingDispatched()
Listener registered	assertListening()	Event::assertListening(OrderShipped::class, SendEmail::class)
Conditional dispatch	assertDispatched(callback)	Event::assertDispatched(fn($e) => $e->order->id === 1)
Inspect events	dispatched()	Event::dispatched(OrderShipped::class)

Sources: src/Testing/Fakes/EventFake.php67-159

---

Fake Interface Implementation

The EventFake implements the PSR-14 EventDispatcherInterface:

The EventFake extends this interface to support additional parameters and methods used by Hypervel's event system. Stub implementations for methods like push(), flush(), forget(), and forgetPushed() are provided at src/Testing/Fakes/EventFake.php208-302 but do nothing since deferred events are not relevant in testing contexts.

Sources: src/Testing/Fakes/EventFake.php17 src/Testing/Fakes/EventFake.php208-302

---

Complete Testing Example

Sources: src/Testing/Fakes/EventFake.php1-327 src/Facades/Event.php1-105